Skip to main content
By default, users access the Kubernetes API of a Managed Service for Kubernetes cluster with their Nebius AI Cloud credentials. You can also let users sign in with an external OpenID Connect (OIDC) identity provider (IdP), such as Okta, Microsoft Entra ID, or Keycloak. Users authorized via IdP tokens don’t need Nebius AI Cloud accounts to work with the cluster: you manage their permissions with Kubernetes role-based access control (RBAC). Authentication with Nebius AI Cloud credentials keeps working after you add an OIDC provider. If your cluster administrator gave you a kubeconfig file for signing in with an IdP, see How to sign in to the cluster.
This article covers tokens issued for the cluster by an external IdP. To let external systems verify tokens that the cluster issues to its workloads, see Using an OIDC public endpoint in Managed Service for Kubernetes® clusters.

How OIDC authentication works

You set up OIDC authentication in three places:
  • In the IdP, you register a client application for the cluster and assign users and groups to it. The IdP signs users in and issues ID tokens to them.
  • In the cluster configuration in Nebius AI Cloud, you add the IdP as an OIDC provider. The provider configuration tells the cluster which tokens to trust and how to turn them into Kubernetes users and groups.
  • In the cluster itself, you grant permissions to these users and groups with Kubernetes RBAC. The IdP and Nebius AI Cloud Identity and Access Management (IAM) don’t grant any permissions in the cluster.
When a user works with the cluster:
  1. The user signs in to the IdP and gets an ID token, for example, with the kubelogin plug-in for kubectl.
  2. The client, for example, kubectl, sends the token to the Kubernetes API server of the cluster.
  3. The API server verifies the token. It gets the public keys of the IdP over HTTPS and checks the token’s signature, issuer, and audience. Then it checks the token against the validation rules of the provider.
  4. The API server maps the token to a Kubernetes username and groups according to the claim mappings of the provider.
  5. Kubernetes RBAC decides what the user can do. A new user has no permissions until you grant them.
The issuer URL of the IdP must be publicly accessible over HTTPS.

Claims

An ID token contains a set of claims: name-value pairs that the IdP states about the user and the token. For example, the payload of an ID token can look like this:
  • iss: issuer, the IdP that issued the token.
  • aud: audience, the client application that the token is issued for. Most IdPs set it to the client ID of the application.
  • sub: unique ID of the user in the IdP.
  • exp: time when the token expires.
  • email, email_verified, groups, and team: user description. The specific claims contained in the token and their names depend on the identity provider (IdP) and its settings.
The cluster uses claims to check the token and to get a Kubernetes username and groups from it.

Provider configuration

You pass provider configurations to the cluster when you add or update OIDC providers. For instructions, see How to add an OIDC provider. A minimal provider configuration contains the provider name, the issuer of tokens, and the claim mappings:
The following example shows the configuration of a provider with all parameters:
The cluster checks the configuration when you add or update providers and rejects invalid configurations. During this check, the cluster doesn’t contact the IdP, so a configuration can be accepted even if the IdP is unreachable.

Issuer URLs

The following table lists the issuer URL formats of popular IdPs and their documentation on registering applications:

Claim mappings

Claim mappings tell the cluster which claims to use as the Kubernetes username and groups. For example, with the configuration above, the user alice@example.com from the k8s-engineering IdP group becomes the user oidc:alice@example.com in the oidc:k8s-engineering group. You use these mapped names in RBAC bindings. Map a claim in one of the following ways:
  • By claim name: {"claim": "email", "prefix": "oidc:"}. Kubernetes adds the prefix to the claim value. The prefix is optional. Use a prefix to keep users and groups from different providers apart.
  • By a Common Expression Language (CEL) expression: {"expression": "\"oidc:\" + claims.email"}. The expression can use any claims of the token. An expression mapping can’t have a prefix, not even an empty one.
Claim names and values depend on the IdP. Check which claims the ID tokens of your IdP contain and adjust the claim mappings if needed. If you map the username from the email claim by its name, Kubernetes rejects tokens in which the email_verified claim is false. Tokens without the email_verified claim are accepted. If an expression uses claims.email, the configuration must also check email_verified, for example, with a claim validation rule.

Reserved names

The following prefixes are reserved:
  • system:: Kubernetes reserves it for its own users and groups.
  • nebius:: Nebius AI Cloud reserves it for users who access the cluster with Nebius AI Cloud credentials. These users are in groups such as nebius:viewer, nebius:editor, and nebius:admin, and these groups already have permissions in the cluster.
A prefix in a claim mapping can’t start with system: or nebius:. The cluster rejects such a configuration. A token is rejected if its mapped username or any of its mapped groups starts with system:. This check is always on and you can’t turn it off. For example, if you don’t use a group prefix, a member of an IdP group named system:masters can’t sign in.
Use a group prefix, for example, oidc:. Without a prefix, members of an IdP group named nebius:admin get the same permissions in the cluster as Nebius AI Cloud admins.

Validation rules

By default, the cluster accepts any valid token from the provider. Validation rules restrict which tokens and users the cluster accepts, for example, only users from a certain team or group. You add the rules to the provider configuration, in the claim_validation_rules and user_validation_rules parameters. A token is accepted only if it passes all rules. The API server checks the rules in the following order:
  1. Claim validation rules check the token claims before mapping. Each rule uses one of the following forms:
    • Exact match: {"claim": "<claim>", "required_value": "<value>"}. The claim must exist and equal the value. If you omit required_value, the claim must be an empty string. This form doesn’t support a message.
    • CEL expression: {"expression": "<expression>", "message": "<message>"}. The expression must evaluate to true.
  2. User validation rules check the mapped user after mapping: {"expression": "<expression>", "message": "<message>"}. The expression can use user.username and user.groups.
For example, the rules in the configuration with all parameters accept only tokens with the team claim set to platform, and only users in the oidc:k8s-engineering group. A user who doesn’t pass a rule gets the Unauthorized error.

How the cluster updates providers

When you update the providers, the cluster replaces the whole list of providers with the list that you pass. The following rules apply:
  • Pass the complete list of providers, including the providers that you don’t change. The cluster removes providers that aren’t in the list.
  • Specify all parameters of each provider. The cluster doesn’t keep parameters from the current configuration, so if you omit an optional parameter, the provider no longer has it.
  • Updates of other cluster parameters don’t change the providers.
  • When the update operation completes, the new configuration is active.
For instructions, see How to update OIDC providers.

See also