> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to configure external OIDC providers in Managed Service for Kubernetes®

Add an external OpenID Connect (OIDC) identity provider (IdP) to a Managed Service for Kubernetes cluster to let users sign in to the cluster with the IdP. For an overview of how OIDC authentication works and what the provider parameters mean, see [Authentication with external OIDC providers in Managed Service for Kubernetes®](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md).

## Prerequisites

1. In your IdP, register an OIDC client application for the cluster and assign the users and groups who need access to the cluster. For the documentation of popular IdPs, see [Issuer URLs](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md#issuer-urls). Note the client ID of the application and the issuer URL of the IdP.

   This guide uses [kubelogin](https://github.com/int128/kubelogin), a kubectl plug-in, to get ID tokens from the IdP. kubelogin is optional: users can get tokens with any other client. If users sign in with kubelogin, also configure the application:

   * Allow the authorization code grant type.
   * Add `http://localhost:8000` as a redirect URI. kubelogin listens on this address by default.

2. To grant access by IdP group, configure the IdP to add a `groups` claim to ID tokens. For more information about claims, see [Claims](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md#claims).

3. Make sure that the issuer URL is publicly accessible over HTTPS. The API server of the cluster uses this URL to get the discovery document and the public keys of the IdP.

4. [Install and configure](https://docs.nebius.com/cli/install.md) the Nebius AI Cloud CLI.

5. To manage the cluster with Terraform, [install and configure](https://docs.nebius.com/terraform-provider/install.md) the Nebius AI Cloud provider for Terraform. The cluster must be managed by Terraform: create it with Terraform or [import it](https://developer.hashicorp.com/terraform/cli/import) into your configuration.

6. [Create a Managed Kubernetes cluster](https://docs.nebius.com/kubernetes/clusters/manage.md) with a public endpoint, or use an existing one. Users who sign in with the IdP connect to the cluster through its public endpoint. You can also add an OIDC provider when you create a cluster. For more information, see [How to add an OIDC provider](#how-to-add-an-oidc-provider).

7. [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [connect to the cluster](https://docs.nebius.com/kubernetes/connect.md) with your Nebius AI Cloud credentials. You need this access to grant permissions to OIDC users. If OIDC users can't sign in because of a configuration error, you can still use this access to fix it.

## How to view OIDC providers

To see the OIDC providers of a cluster and their parameters, run:

```bash theme={null}
nebius mk8s cluster get \
  --id <cluster_ID> \
  --format jsonpath='{.spec.control_plane.authentication}'
```

The command prints the configuration in the JSON format, for example, `{"oidc":[{"name":"my-idp",...}]}`. The value of `oidc` is the list of providers. If the cluster has no providers, the output is `{}`.

## How to add an OIDC provider

> [tab] CLI
>
> * To add a provider when you create a cluster, run:
>
>   ```bash theme={null}
>   nebius mk8s cluster create \
>     --name <cluster_name> \
>     --control-plane-version 1.36 \
>     --control-plane-subnet-id <subnet_ID> \
>     --control-plane-endpoints-public-endpoint=true \
>     --control-plane-authentication-oidc '[{
>       "name": "my-idp",
>       "issuer": {
>         "url": "<issuer_URL>",
>         "audiences": ["<client_ID>"]
>       },
>       "claim_mappings": {
>         "username": {"claim": "email", "prefix": "oidc:"},
>         "groups": {"claim": "groups", "prefix": "oidc:"}
>       }
>     }]'
>   ```
>
> * To add a provider to an existing cluster that has no providers, run:
>
>   ```bash theme={null}
>   nebius mk8s cluster update \
>     --id <cluster_ID> \
>     --control-plane-authentication-oidc '[{
>       "name": "my-idp",
>       "issuer": {
>         "url": "<issuer_URL>",
>         "audiences": ["<client_ID>"]
>       },
>       "claim_mappings": {
>         "username": {"claim": "email", "prefix": "oidc:"},
>         "groups": {"claim": "groups", "prefix": "oidc:"}
>       }
>     }]'
>   ```
>
>   The command sets the complete list of providers for the cluster. If the cluster already has providers, see [How to update OIDC providers](#how-to-update-oidc-providers).
>
> The commands contain the following parameters:
>
> * `--name`: Cluster name.
> * `--control-plane-subnet-id`: [Subnet ID](https://docs.nebius.com/vpc/networking/resources.md#how-to-get-a-subnet-id).
> * `--control-plane-endpoints-public-endpoint`: Creates a public endpoint. Users who sign in with the IdP connect to the cluster through it.
> * `--control-plane-authentication-oidc`: List of OIDC providers with the following parameters:
>
>   * `name`: Provider name, for example, `my-idp`.
>   * `issuer.url`: Issuer URL of your IdP.
>   * `issuer.audiences`: Client ID of the application that you registered in the IdP.
>   * `claim_mappings.username`: The `email` claim with the `oidc:` prefix as the username.
>   * `claim_mappings.groups`: The `groups` claim with the `oidc:` prefix as the groups.

> [tab] Terraform
>
> 1. Create a configuration file with a cluster that has an OIDC provider:
>
>    ```hcl theme={null}
>    resource "nebius_mk8s_v1_cluster" "oidc_cluster" {
>      name      = "<cluster_name>"
>      parent_id = "<project_ID>"
>      control_plane = {
>        version   = "1.36"
>        subnet_id = "<subnet_ID>"
>        endpoints = {
>          public_endpoint = {}
>        }
>        authentication = {
>          oidc = [
>            {
>              name = "my-idp"
>              issuer = {
>                url       = "<issuer_URL>"
>                audiences = ["<client_ID>"]
>              }
>              claim_mappings = {
>                username = {
>                  claim  = "email"
>                  prefix = "oidc:"
>                }
>                groups = {
>                  claim  = "groups"
>                  prefix = "oidc:"
>                }
>              }
>            }
>          ]
>        }
>      }
>    }
>    ```
>
>    To add a provider to an existing cluster, add the `authentication` block to `control_plane` in the `nebius_mk8s_v1_cluster` resource of the cluster.
>
>    The configuration contains the following parameters:
>
>    * `name`: Cluster name.
>    * `parent_id`: [Project ID](https://docs.nebius.com/iam/manage-projects.md#how-to-get-a-project-id-terraform).
>    * `control_plane.subnet_id`: [Subnet ID](https://docs.nebius.com/vpc/networking/resources.md#how-to-get-a-subnet-id).
>    * `control_plane.authentication.oidc`: List of OIDC providers with the following parameters:
>
>      * `name`: Provider name, for example, `my-idp`.
>      * `issuer.url`: Issuer URL of your IdP.
>      * `issuer.audiences`: Client ID of the application that you registered in the IdP.
>      * `claim_mappings.username`: The `email` claim with the `oidc:` prefix as the username.
>      * `claim_mappings.groups`: The `groups` claim with the `oidc:` prefix as the groups.
>
> 2. Check that the configuration is correct:
>    ```bash theme={null}
>    terraform validate
>    ```
>
> 3. Apply the changes:
>    ```bash theme={null}
>    terraform apply
>    ```

With this configuration, the user `alice@example.com` from the `k8s-engineering` IdP group becomes the user `oidc:alice@example.com` in the `oidc:k8s-engineering` group. For all provider parameters, see [Provider configuration](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md#provider-configuration).

When the operation completes, the cluster starts accepting tokens from the provider. To check the configuration, see [How to view OIDC providers](#how-to-view-oidc-providers).

## How to grant access with RBAC

OIDC users are authenticated but have no permissions until you bind them to Kubernetes roles with role-based access control (RBAC). Create the bindings with your Nebius AI Cloud credentials. Use the mapped names, including the prefixes.

For example, to give read-only access to all members of the `k8s-engineering` IdP group:

1. Create an `oidc-engineering-view.yaml` file with a ClusterRoleBinding:

   ```yaml theme={null}
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: oidc-engineering-view
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
     - kind: Group
       apiGroup: rbac.authorization.k8s.io
       name: oidc:k8s-engineering
   ```

   To bind a single user, use `kind: User` and the mapped username, for example, `oidc:alice@example.com`.

2. Apply the file:

   ```bash theme={null}
   kubectl apply -f oidc-engineering-view.yaml
   ```

For more information, see [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) in the Kubernetes documentation.

## How to prepare a kubeconfig file for users

Users who sign in with the IdP don't need Nebius AI Cloud credentials. To connect to the cluster, they only need its API server endpoint and its certificate authority (CA) certificate. You get both with your Nebius AI Cloud credentials, put them into a kubeconfig file and give the file to the users.

The following steps create a kubeconfig file in which kubectl gets ID tokens from the IdP through kubelogin. For the settings of the client application that kubelogin needs, see [Prerequisites](#prerequisites).

kubelogin is optional. Users can get ID tokens with any other client and send them to the API server in the `Authorization: Bearer <token>` header of requests. In this case, configure the kubeconfig file and the client application according to the documentation of that client.

1. Get the public endpoint of the cluster:

   ```bash theme={null}
   nebius mk8s cluster get \
     --id <cluster_ID> \
     --format jsonpath='{.status.control_plane.endpoints.public_endpoint}'
   ```

2. Save the CA certificate of the cluster to the `ca.crt` file:

   ```bash theme={null}
   nebius mk8s cluster get \
     --id <cluster_ID> \
     --format jsonpath='{.status.control_plane.auth.cluster_ca_certificate}' \
     > ca.crt
   ```

3. Create a kubeconfig file, `oidc.kubeconfig`, with the cluster and a user that gets tokens from the IdP through kubelogin:

   ```bash theme={null}
   kubectl config set-cluster <kubeconfig_cluster_name> \
     --kubeconfig=oidc.kubeconfig \
     --server=<cluster_endpoint> \
     --certificate-authority=ca.crt \
     --embed-certs
   kubectl config set-credentials oidc \
     --kubeconfig=oidc.kubeconfig \
     --exec-api-version=client.authentication.k8s.io/v1 \
     --exec-interactive-mode=IfAvailable \
     --exec-command=kubectl \
     --exec-arg=oidc-login \
     --exec-arg=get-token \
     --exec-arg=--oidc-issuer-url=<issuer_URL> \
     --exec-arg=--oidc-client-id=<client_ID> \
     --exec-arg=--oidc-extra-scope=email
   kubectl config set-context oidc \
     --kubeconfig=oidc.kubeconfig \
     --cluster=<kubeconfig_cluster_name> \
     --user=oidc
   kubectl config use-context oidc --kubeconfig=oidc.kubeconfig
   ```

   The commands contain the following parameters:

   * `--server`: Public endpoint of the cluster that you got earlier.
   * `--oidc-issuer-url`: Issuer URL of your IdP.
   * `--oidc-client-id`: Client ID of the application that you registered in the IdP.
   * `<kubeconfig_cluster_name>`: Name of the cluster in the kubeconfig file, for example, the name of the Managed Kubernetes cluster.

   The `--oidc-extra-scope=email` parameter requests the `email` claim. If your IdP adds the `groups` claim to ID tokens only for a separate scope, request it as well, for example, with `--exec-arg=--oidc-extra-scope=groups`.

4. Give the `oidc.kubeconfig` file to the users.

## How to sign in to the cluster

If your cluster administrator gave you a kubeconfig file for signing in with an IdP through kubelogin, as described in [How to prepare a kubeconfig file for users](#how-to-prepare-a-kubeconfig-file-for-users), follow these steps on your machine. You don't need Nebius AI Cloud credentials. If your administrator set up a different client, follow their instructions.

1. [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).

2. Install [kubelogin](https://github.com/int128/kubelogin), the kubectl plug-in for signing in with an IdP, by using [krew](https://krew.sigs.k8s.io/docs/user-guide/setup/install/):

   ```bash theme={null}
   kubectl krew install oidc-login
   ```

3. Check which user you're signed in as:

   ```bash theme={null}
   kubectl auth whoami --kubeconfig=oidc.kubeconfig
   ```

   A browser opens with the sign-in page of your IdP. After you sign in, the output shows the mapped username and groups, for example:

   ```text theme={null}
   ATTRIBUTE   VALUE
   Username    oidc:alice@example.com
   Groups      [oidc:k8s-engineering system:authenticated]
   ```

kubelogin caches the token and gets a new one when it expires. To use the file in every kubectl command without the `--kubeconfig` parameter, set the `KUBECONFIG` environment variable to its path.

## How to update OIDC providers

The update replaces the whole list of providers with the list that you pass. For more information, see [How the cluster updates providers](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md#how-the-cluster-updates-providers).

> [tab] CLI
>
> 1. [Get the current configuration](#how-to-view-oidc-providers) and copy the value of `oidc`.
>
> 2. Pass the complete edited list, including the providers and parameters that you don't change. For example, to add a second provider, run:
>
>    ```bash theme={null}
>    nebius mk8s cluster update \
>      --id <cluster_ID> \
>      --control-plane-authentication-oidc '[
>        {
>          "name": "my-idp",
>          "issuer": {
>            "url": "<issuer_URL>",
>            "audiences": ["<client_ID>"]
>          },
>          "claim_mappings": {
>            "username": {"claim": "email", "prefix": "oidc:"},
>            "groups": {"claim": "groups", "prefix": "oidc:"}
>          }
>        },
>        {
>          "name": "ci-idp",
>          "issuer": {
>            "url": "<second_issuer_URL>",
>            "audiences": ["<second_client_ID>"]
>          },
>          "claim_mappings": {
>            "username": {"claim": "sub", "prefix": "ci:"}
>          }
>        }
>      ]'
>    ```
>
>    The second provider in this example has the following parameters:
>
>    * `name`: Provider name, for example, `ci-idp`.
>    * `issuer.url`: Issuer URL of the second IdP.
>    * `issuer.audiences`: Client ID of the application that you registered in the second IdP.
>    * `claim_mappings.username`: The `sub` claim with the `ci:` prefix as the username. The provider has no groups mapping.
>
>    To remove a provider, pass the list without it.
>
> 3. [Check the configuration](#how-to-view-oidc-providers).
>
> You can also edit the configuration in a text editor. The following command opens the cluster specification. Change the `spec.control_plane.authentication.oidc` parameter and save the file:
>
> ```bash theme={null}
> nebius mk8s cluster edit --id <cluster_ID>
> ```

> [tab] Terraform
>
> 1. In the `nebius_mk8s_v1_cluster` resource of the cluster, change the `control_plane.authentication.oidc` list:
>
>    * To add a provider, add an element to the list.
>    * To change a provider, change its element.
>    * To remove a provider, delete its element.
>
> 2. Check that the configuration is correct:
>    ```bash theme={null}
>    terraform validate
>    ```
>
> 3. Apply the changes:
>    ```bash theme={null}
>    terraform apply
>    ```
>
> 4. [Check the configuration](#how-to-view-oidc-providers).

### How to change a claim mapping

The following example maps the username with an expression instead of the `email` claim in a cluster that has only the provider from [How to add an OIDC provider](#how-to-add-an-oidc-provider). If the cluster has other providers, include them in the list. Otherwise, the update removes them.

> [tab] CLI
>
> ```bash theme={null}
> nebius mk8s cluster update \
>   --id <cluster_ID> \
>   --control-plane-authentication-oidc '[{
>     "name": "my-idp",
>     "issuer": {
>       "url": "<issuer_URL>",
>       "audiences": ["<client_ID>"]
>     },
>     "claim_mappings": {
>       "username": {"expression": "\"oidc:\" + claims.email"},
>       "groups": {"claim": "groups", "prefix": "oidc:"}
>     },
>     "claim_validation_rules": [{
>       "expression": "claims.?email_verified.orValue(true) == true",
>       "message": "The email address must be verified"
>     }]
>   }]'
> ```
>
> In the command, specify the same values as in [How to add an OIDC provider](#how-to-add-an-oidc-provider).

> [tab] Terraform
>
> 1. In the `username` block of the provider, replace `claim` and `prefix` with `expression`, and add a claim validation rule:
>
>    ```hcl theme={null}
>    resource "nebius_mk8s_v1_cluster" "oidc_cluster" {
>      name      = "<cluster_name>"
>      parent_id = "<project_ID>"
>      control_plane = {
>        version   = "1.36"
>        subnet_id = "<subnet_ID>"
>        endpoints = {
>          public_endpoint = {}
>        }
>        authentication = {
>          oidc = [
>            {
>              name = "my-idp"
>              issuer = {
>                url       = "<issuer_URL>"
>                audiences = ["<client_ID>"]
>              }
>              claim_mappings = {
>                username = {
>                  expression = "\"oidc:\" + claims.email"
>                }
>                groups = {
>                  claim  = "groups"
>                  prefix = "oidc:"
>                }
>              }
>              claim_validation_rules = [
>                {
>                  expression = "claims.?email_verified.orValue(true) == true"
>                  message    = "The email address must be verified"
>                }
>              ]
>            }
>          ]
>        }
>      }
>    }
>    ```
>
>    In the configuration, specify the same values as in [How to add an OIDC provider](#how-to-add-an-oidc-provider).
>
> 2. Check that the configuration is correct:
>    ```bash theme={null}
>    terraform validate
>    ```
>
> 3. Apply the changes:
>    ```bash theme={null}
>    terraform apply
>    ```

The claim validation rule in this example checks `email_verified`, because the expression uses `claims.email`. For more information, see [Claim mappings](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md#claim-mappings).

## How to remove all OIDC providers

> [tab] CLI
>
> Pass an empty list:
>
> ```bash theme={null}
> nebius mk8s cluster update \
>   --id <cluster_ID> \
>   --control-plane-authentication-oidc '[]'
> ```

> [tab] Terraform
>
> 1. In the `nebius_mk8s_v1_cluster` resource of the cluster, delete the `authentication` block from `control_plane`.
> 2. Check that the configuration is correct:
>    ```bash theme={null}
>    terraform validate
>    ```
> 3. Apply the changes:
>    ```bash theme={null}
>    terraform apply
>    ```
> 4. [Check the configuration](#how-to-view-oidc-providers).

After you remove the providers, users can still access the cluster with their Nebius AI Cloud credentials.

## See also

* [Authentication with external OIDC providers in Managed Service for Kubernetes®](https://docs.nebius.com/kubernetes/authentication/oidc-providers.md)
* [Troubleshooting authentication with external OIDC providers in Managed Service for Kubernetes®](https://docs.nebius.com/kubernetes/authentication/troubleshoot-oidc-providers.md)
* [How to connect to Managed Service for Kubernetes® clusters using kubectl](https://docs.nebius.com/kubernetes/connect.md)
* [kubelogin](https://github.com/int128/kubelogin) on GitHub
