Skip to main content
Access to the cluster through an OIDC provider
Last update:

Access to the cluster through an OIDC provider

In Managed Kubernetes, you can configure access to the cluster using the OpenID Connect (OIDC) protocol. OIDC is an authentication protocol that is based on the OAuth 2.0 protocol and additionally provides the ability to transfer user information. The user information is transferred in an access token ID Token. It is a token in JSON Web Token (JWT) format, which is signed by the server. Learn more about using OpenID Connect in Kubernetes in the Authenticating Kubernetes documentation article.

OIDC allows users to authenticate to one service and then access other services without having to re-authenticate, so single sign-on (SSO) for users to multiple services or applications can be provided using OIDC.

OIDC providers such as Keycloak or Dex are used to authenticate users by OIDC. With an OIDC provider, you can centrally manage users and their access to all services and applications for 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, in case of an employee's dismissal, you can do it through the OIDC-provider.

Connect the OIDC provider to the cluster⁠

OIDC provider connectivity is available in Managed Kubernetes clusters version 1.28 and later. You can upgrade the cluster version on the cloud server.

You can connect an OIDC provider to the cluster through the control panel and Terraform.You can view the connection data in your OIDC provider.

  1. In the dashboard, on the top menu, click Products and select Managed Kubernetes.
  2. Open the cluster page → Settings tab.
  3. In the OIDC provider field, click Connect.
  4. Enter the name of the OIDC provider. The name is only used to identify the provider in the control panel.
  5. In the Issuer URL field, enter the URL of the OIDC provider that is accessible via the Internet. This will be used to authenticate users who request access to the cluster.
  6. In the Client ID field, enter the service identifier that is required to identify the cluster on the OIDC provider side. For example, kubernetes.
  7. Optional: In the Username claim field, enter the name of the JWT token field where the username will be stored. This name is used to identify the user. The default value is sub. Depending on the OIDC provider, other options such as email or name can be used.
  8. Optional: in the Groups claim field, enter the name of the JWT token field that will store the name of the group to which the user belongs. The default value is groups.
  9. Optional: To add a root certificate, check the Upload your root certificate checkbox and paste the root certificate. It must begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE -----. The certificate cannot be changed once the OIDC provider is connected.

Set up a connection through an OIDC provider⁠

  1. In the dashboard, on the top menu, click Products and select Managed Kubernetes.

  2. Open the cluster page → Settings tab.

  3. Click Download kubeconfig. The kubeconfig file download is not available if the cluster status is PENDING_CREATE, PENDING_ROTATE_CERTS, PENDING_DELETE, or ERROR.

  4. Add data to the kubeconfig file to connect via OIDC provider:

    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> — The URL of the OIDC provider that is accessible via the Internet. It will be used to authenticate users who request access to the cluster;
    • <client_id> — service identifier, which is required to identify the cluster on the OIDC provider side. For example, kubernetes;
    • <client_secret> — a shared secret key set between the authorization server and the client, which is used to sign requests;
    • Optional: --certificate-authority = <oidc_ca_certificate> — tag to add the root certificate of the OIDC provider. The <oidc_ca_certificate> parameter is the path to the root certificate that you downloaded when you connected the OIDC provider to the cluster.

  5. 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 the developer role, which gives 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

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

Connect to the cluster by OIDC⁠

We recommend that you perform all actions with nodes, balancers and disks in the cluster only through kubectl.

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

  1. Install the Kubernetes kubectl console client.

  2. Install the kubelogin plug in.

  3. Open the CLI.

  4. Export the path to the kubeconfig file to the KUBECONFIG environment variable:

    export KUBECONFIG=<path>

    Specify <path> -path to the kubeconfig file name_cluster.yaml.

  5. Access the cluster via kubectl. For example, request information about the cluster nodes:

    kubectl get nodes

    The authentication page from the OIDC provider will automatically open in your browser.

  6. Authenticate with the OIDC provider.

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

Disconnect the OIDC provider⁠

Once an OIDC provider is disconnected, all users who connected to the cluster through that provider will lose access to the cluster.

  1. In the dashboard, on the top menu, click Products and select Managed Kubernetes.
  2. Open the cluster page → Settings tab.
  3. In the Server Settings block, in the OIDC Provider field, open the OIDC Provider block.
  4. Click Disable.