Skip to main content
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®.

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. Note the client ID of the application and the issuer URL of the IdP. This guide uses 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.
  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 the Nebius AI Cloud CLI.
  5. To manage the cluster with Terraform, install and configure the Nebius AI Cloud provider for Terraform. The cluster must be managed by Terraform: create it with Terraform or import it into your configuration.
  6. Create a Managed Kubernetes cluster 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.
  7. Install kubectl and connect to the cluster 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:
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

  • To add a provider when you create a cluster, run:
  • To add a provider to an existing cluster that has no providers, run:
    The command sets the complete list of providers for the cluster. If the cluster already has providers, see How to update OIDC providers.
The commands contain the following parameters:
  • --name: Cluster name.
  • --control-plane-subnet-id: 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.
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. When the operation completes, the cluster starts accepting tokens from the provider. To check the configuration, see 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:
    To bind a single user, use kind: User and the mapped username, for example, oidc:alice@example.com.
  2. Apply the file:
For more information, see Using RBAC Authorization 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. 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:
  2. Save the CA certificate of the cluster to the ca.crt file:
  3. Create a kubeconfig file, oidc.kubeconfig, with the cluster and a user that gets tokens from the IdP through kubelogin:
    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, 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.
  2. Install kubelogin, the kubectl plug-in for signing in with an IdP, by using krew:
  3. Check which user you’re signed in as:
    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:
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.
  1. Get the current configuration 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:
    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.
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:

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. If the cluster has other providers, include them in the list. Otherwise, the update removes them.
In the command, specify the same values as in How to add an OIDC provider.
The claim validation rule in this example checks email_verified, because the expression uses claims.email. For more information, see Claim mappings.

How to remove all OIDC providers

Pass an empty list:
After you remove the providers, users can still access the cluster with their Nebius AI Cloud credentials.

See also