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 transmitting user information. User information is passed in an ID Token access token. This is a JSON Web Token (JWT) formatted token 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 identity providers are used, such as Keycloak or Dex. Using an OIDC provider, you can centrally manage users and their access to all services and applications connected to the OIDC provider, 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 the company, 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 running 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, from 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 JWT token field name where the username will be stored. This name is used to identify the user. Default value is sub. Depending on the OIDC provider, you can use other options, such as email or name.
Optional: in the Groups claim field, enter the JWT token field name where the name of the group the user belongs to will be stored. Default value is groups.
Optional: to add a root certificate, select the Upload your root certificate checkbox and paste the root certificate. It must start 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, from 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 status is 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 that is used to sign requests;
optional: --certificate-authority = <oidc_ca_certificate> — tag for adding the OIDC provider root certificate. The parameter <oidc_ca_certificate> is the path to the root certificate that you uploaded when connecting the OIDC provider to the cluster.

Configure user roles in the cluster using RBAC authorization. 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 viewing pods and services, add the 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 on cluster nodes, load balancers, and disks only through kubectl.

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

Linux
Windows

Install the Kubernetes command-line tool 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, from 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.