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.
- The user signs in to the IdP and gets an ID token, for example, with the kubelogin plug-in for kubectl.
- The client, for example, kubectl, sends the token to the Kubernetes API server of the cluster.
- 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.
- The API server maps the token to a Kubernetes username and groups according to the claim mappings of the provider.
- Kubernetes RBAC decides what the user can do. A new user has no permissions until you grant them.
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, andteam: user description. The specific claims contained in the token and their names depend on the identity provider (IdP) and its settings.
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 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 useralice@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.
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 asnebius:viewer,nebius:editor, andnebius:admin, and these groups already have permissions in the cluster.
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.
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 theclaim_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:
-
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 omitrequired_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 totrue.
- Exact match:
-
User validation rules check the mapped user after mapping:
{"expression": "<expression>", "message": "<message>"}. The expression can useuser.usernameanduser.groups.
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.