Access to a Managed Kubernetes cluster via an OIDC provider

Managed Kubernetes allows you to configure cluster access via the OpenID Connect (OIDC) protocol. OIDC is an authentication protocol based on OAuth 2.0 that additionally provides the ability to transfer user information. User information is transferred in an ID Token. This is a JSON Web Token (JWT) signed by the server. Learn more about using OpenID Connect in Kubernetes in the Authenticating article in the Kubernetes documentation.

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

OIDC providers are used to authenticate users via OIDC — for example, Keycloak or Dex. An OIDC provider can be used to centrally manage users and their access to all services and applications for which the OIDC provider is configured, including a Managed Kubernetes cluster. If you need to change a user role or restrict access to all services, for example, in the event of an employee leaving, 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 of 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 or Terraform. Connection details can be found in your OIDC provider.

In the Control panel, on the top menu, click Products and select Managed Kubernetes.
Open the cluster page → Settings tab.
In the OIDC provider field, click Connect.
Enter the name of the OIDC provider. The name is used only 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 who request access to the cluster.
In the Client ID field, enter the service identifier used 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 user name. This name is used to identify the user. The default value is sub. Depending on the OIDC provider, other options can be used, for example 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 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 the OIDC provider is connected.

Configure the connection via an OIDC provider

In the Control panel, on the top menu, click Products and select Managed Kubernetes.
Open the cluster page → Settings tab.
Click Download kubeconfig. Downloading the kubeconfig file is not available 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> — OIDC provider URL accessible over the internet; it will be used to authenticate users who request access to the cluster;
<client_id> — service identifier used to identify the cluster on the OIDC provider side. For example, kubernetes;
<client_secret> — shared secret key established between the authorization server and the client, used to sign requests;
optional: --certificate-authority = <oidc_ca_certificate> — tag for adding the OIDC provider root certificate. The <oidc_ca_certificate> parameter is the path to the root certificate that you uploaded when connecting an OIDC provider to a cluster.

Configure user roles in the cluster using the RBAC authorization mechanism. Learn more about using RBAC in Kubernetes in the Using RBAC Authorization article of the official Kubernetes documentation. For example, to configure a developer role that provides access to viewing pods and services, add the following 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 the certificates for system components, you must reconnect to the cluster.

Linux
Windows

Install the Kubernetes console 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> — path to the cluster_name.yaml kubeconfig file.
Connect to the cluster via kubectl. For example, request information about the cluster nodes:
```
kubectl get nodes
```
An 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.

Disable the OIDC provider

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

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