Prerequisites
-
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:8000as a redirect URI. kubelogin listens on this address by default.
-
To grant access by IdP group, configure the IdP to add a
groupsclaim to ID tokens. For more information about claims, see Claims. - 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.
- Install and configure the Nebius AI Cloud CLI.
- 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.
- 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.
- 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:{"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
- CLI
- Terraform
-
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.
-
--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: Theemailclaim with theoidc:prefix as the username.claim_mappings.groups: Thegroupsclaim with theoidc:prefix as the groups.
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 thek8s-engineering IdP group:
-
Create an
oidc-engineering-view.yamlfile with a ClusterRoleBinding:To bind a single user, usekind: Userand the mapped username, for example,oidc:alice@example.com. -
Apply the file:
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 theAuthorization: Bearer <token> header of requests. In this case, configure the kubeconfig file and the client application according to the documentation of that client.
-
Get the public endpoint of the cluster:
-
Save the CA certificate of the cluster to the
ca.crtfile: -
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.
--oidc-extra-scope=emailparameter requests theemailclaim. If your IdP adds thegroupsclaim to ID tokens only for a separate scope, request it as well, for example, with--exec-arg=--oidc-extra-scope=groups. -
Give the
oidc.kubeconfigfile 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.- Install kubectl.
-
Install kubelogin, the kubectl plug-in for signing in with an IdP, by using krew:
-
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:
--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.- CLI
- Terraform
-
Get the current configuration and copy the value of
oidc. -
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: Thesubclaim with theci:prefix as the username. The provider has no groups mapping.
- Check the configuration.
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 theemail 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.
- CLI
- Terraform
email_verified, because the expression uses claims.email. For more information, see Claim mappings.
How to remove all OIDC providers
- CLI
- Terraform
Pass an empty list: