Access to a Managed Kubernetes cluster via an OIDC provider

In Managed Kubernetes, you can configure access to a cluster via the OpenID Connect (OIDC) protocol. OIDC is an authentication protocol based on OAuth 2.0 that additionally allows transferring user information. User information is transferred in the ID Token access token. This is a token in JSON Web Token (JWT) format signed by the server. For more information about using OpenID Connect in Kubernetes, see the Authenticating article in the Kubernetes documentation.

OIDC allows users to authenticate in one service and then gain access to other services without needing to re-authenticate, so OIDC can provide Single Sign-On (SSO) for users to access multiple services or applications.

To authenticate users via OIDC, OIDC providers are used — for example, Keycloak or Dex. With an OIDC provider, you can centrally manage users and their access to all services and applications to which the OIDC provider is connected, including the Managed Kubernetes cluster. If you need to change a user's role or restrict access to all services, for example, if an employee leaves, you can do this through the OIDC provider.

Connect an OIDC provider to a cluster

Connecting to an OIDC provider is available in Managed Kubernetes clusters version 1.28 and higher. You can upgrade the cluster version on a cloud server.

You can connect an OIDC provider to a cluster via the Control panel and Terraform. Connection details can be found in your OIDC provider.

In the Control panel, on the top menu, click Products and select Managed Kubernetes.
In the Clusters section, open the cluster page → Settings tab.
In the OIDC provider field, click Connect.
Enter a name for the OIDC provider. The name is only used to identify the provider in the Control panel.
In the Issuer URL field, enter the URL of the OIDC provider accessible over the Internet. It will be used to authenticate users requesting access to the cluster.
In the Client ID field, enter the service ID required to identify the cluster on the OIDC provider side. For example, kubernetes.
Optional: in the Username claim field, enter the name of the JWT token field that will store the username. This name is used for identification. The default value is sub. Depending on the OIDC provider, other options can be used, such as email or name.
Optional: in the Groups claim field, enter the name of the JWT token field that will store the name of the group the user belongs to. The default value is groups.
Optional: to add a root certificate, select the Upload custom root certificate checkbox and paste the root certificate. It must begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----. The certificate cannot be changed after connecting the OIDC provider.

Configure connection via an OIDC provider

In the Control panel, on the top menu, click Products and select Managed Kubernetes.
In the Clusters section, open the cluster page → Settings tab.
Click Download kubeconfig. Downloading the kubeconfig file is unavailable if the cluster has the status PENDING_CREATE, PENDING_ROTATE_CERTS, PENDING_DELETE or ERROR.

Add the connection details via the OIDC provider to the kubeconfig file:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: cluster_ca_certificate
    server: server_path
  name: cluster_name
contexts:
- context:
    cluster: cluster_name
    user: oidc
  name: oidc-context
current-context: oidc-context
kind: Config
preferences: {}
users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=<issuer_url>
          - --oidc-client-id=<client_id>
          - --oidc-client-secret=<client_secret>
          - --certificate-authority=<oidc_ca_certificate>
        command: kubectl

Specify:

<issuer_url> — URL of the OIDC provider accessible over the Internet. It will be used to authenticate users requesting access to the cluster;
<client_id> — service ID required to identify the cluster on the OIDC provider side. For example, kubernetes;
<client_secret> — shared secret established between the authorization server and the client, used to sign requests;
optional: --certificate-authority = <oidc_ca_certificate> — flag for adding the OIDC provider root certificate. The <oidc_ca_certificate> parameter is the path to the root certificate you uploaded when connecting the OIDC provider to the cluster.

Configure user roles in the cluster using the RBAC authorization mechanism. For more information about using RBAC in Kubernetes, see the Using RBAC Authorization article in the official Kubernetes documentation. For example, to configure the developer role, which grants access to view pods and services, add a manifest:

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: developer
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "watch", "list"]
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: developer-crb
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: developer
subjects:
- kind: Group
  name: "developers"
  apiGroup: rbac.authorization.k8s.io

Send the updated kubeconfig file to users who do not have access to the Control panel.

Connect to a cluster via OIDC

We recommend performing all actions with cluster nodes, load balancers, and volumes only via kubectl.

After updating certificates for system components, you must reconnect to the cluster.

Linux
Windows

Install the Kubernetes CLI client kubectl.
Install the kubelogin plugin.
Open the CLI.
Export the path to the kubeconfig file to the KUBECONFIG environment variable:
```
export KUBECONFIG=<path>
```
Specify <path> — the path to the kubeconfig file. The file name is formatted as <cluster_name>.yaml, where <cluster_name> is the cluster name.
Query the cluster using kubectl. For example, request information about the cluster nodes:
```
kubectl get nodes
```
The OIDC provider authentication page will open automatically in your browser.
Authenticate with the OIDC provider.

After authentication, the output of the command you entered in step 5 will appear.

Disconnect an OIDC provider

After disconnecting the OIDC provider, all users who connected to the cluster through this provider will lose access to the cluster.

In the Control panel, on the top menu, click Products and select Managed Kubernetes.
In the Clusters section, open the cluster page → Settings tab.
In the Server settings block, in the OIDC provider field, open the OIDC provider block.
Click Disconnect.