---
title: "Access to a Managed Kubernetes cluster via an OIDC provider"
sidebar_label: "Access to a cluster via an OIDC provider"
sidebar_position: 2
description: "How to connect an OIDC provider to a cluster, connect to a cluster via OIDC, and disconnect an OIDC provider"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { TabItemLabel } from '@selectel/docux/components';
import Formbricks from '@theme/MDXComponents/Formbricks';

# 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](https://openid.net/developers/how-connect-works/)) 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](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) 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](https://www.keycloak.org/) or [Dex](https://dexidp.io/). 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 \{#connect-oidc-provider-to-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](/managed-kubernetes/clusters/upgrade-version.mdx).

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

1. In the [Control panel](https://my.selectel.ru/mks/), on the top menu, click **Products** and select **Managed Kubernetes**.
2. In the **Clusters** section, open the cluster page → **Settings** tab.
3. In the **OIDC provider** field, click **Connect**.
4. Enter a name for 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 accessible over the Internet. It will be used to authenticate users requesting access to the cluster.
6. In the **Client ID** field, enter the service ID 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 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`.
8. 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`.
9. 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 \{#configure-oidc-connection}

1. In the [Control panel](https://my.selectel.ru/mks/), on the top menu, click **Products** and select **Managed Kubernetes**.

2. In the **Clusters** section, open the cluster page → **Settings** tab.

3. Click **Download kubeconfig**. Downloading the kubeconfig file is unavailable if the cluster has the status `PENDING_CREATE`, `PENDING_ROTATE_CERTS`, `PENDING_DELETE` or `ERROR`.

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

   ```yaml
   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](#connect-oidc-provider-to-cluster).

5. Configure user roles in the cluster using the RBAC authorization mechanism. For more information about using RBAC in Kubernetes, see the [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) article in the official Kubernetes documentation. For example, to configure the developer role, which grants access to view pods and services, add a manifest:

   ```yaml
   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 a cluster via OIDC \{#connect-to-cluster-with-oidc-provider}

We recommend performing all actions with cluster nodes, load balancers, and volumes only via [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/).

After [updating certificates for system components](/managed-kubernetes/clusters/update-certificate.mdx#update-certificates-when-error-occurs), you must reconnect to the cluster.

<Tabs queryString="connect-to-cluster-with-oidc-provider">
  <TabItem value="kubectl" default>
    <TabItemLabel>
      Linux
    </TabItemLabel>

    1. Install the Kubernetes CLI client [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).

    2. Install the [kubelogin plugin](https://github.com/int128/kubelogin).

    3. Open the CLI.

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

       ```bash
       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.

    5. Query the cluster using kubectl. For example, request information about the cluster nodes:

       ```bash
       kubectl get nodes
       ```

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

    6. Authenticate with the OIDC provider.

       After authentication, the output of the command you entered in step 5 will appear.
  </TabItem>

  <TabItem value="windows">
    <TabItemLabel>
      Windows
    </TabItemLabel>

    1. Install the Kubernetes CLI client [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/).

    2. Install the [kubelogin plugin](https://github.com/int128/kubelogin).

    3. Run PowerShell as an administrator.

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

       ```bash
       $env: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.

    5. Query the cluster using kubectl. For example, request information about the cluster nodes:

       ```bash
       kubectl get nodes
       ```

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

    6. Authenticate with the OIDC provider.

       After authentication, the output of the command you entered in step 5 will appear.
  </TabItem>
</Tabs>

## Disconnect an OIDC provider \{#disconnect-oidc-provider}

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

1. In the [Control panel](https://my.selectel.ru/mks/), on the top menu, click **Products** and select **Managed Kubernetes**.
2. In the **Clusters** section, open the cluster page → **Settings** tab.
3. In the **Server settings** block, in the **OIDC provider** field, open the OIDC provider block.
4. Click **Disconnect**.

<Formbricks />