> ## 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.

# Authentication with external OIDC providers in Managed Service for Kubernetes®

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](https://docs.nebius.com/kubernetes/authentication/oidc-authentication.md#how-to-sign-in-to-the-cluster).

> [!NOTE]
>
> 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](https://docs.nebius.com/kubernetes/networking/oidc-public-endpoint.md).

## 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:

```json theme={null}
{
  "iss": "https://idp.example.com",
  "aud": "kubernetes",
  "sub": "00u1a2b3c4",
  "exp": 1767225600,
  "email": "alice@example.com",
  "email_verified": true,
  "groups": ["k8s-engineering"],
  "team": "platform"
}
```

* `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](https://docs.nebius.com/kubernetes/authentication/oidc-authentication.md#how-to-add-an-oidc-provider).

A minimal provider configuration contains the provider name, the issuer of tokens, and the claim mappings:

```json theme={null}
{
  "name": "my-idp",
  "issuer": {
    "url": "https://idp.example.com",
    "audiences": ["kubernetes"]
  },
  "claim_mappings": {
    "username": {"claim": "email", "prefix": "oidc:"},
    "groups": {"claim": "groups", "prefix": "oidc:"}
  }
}
```

The following example shows the configuration of a provider with all parameters:

```json theme={null}
{
  "name": "my-idp",
  "issuer": {
    "url": "https://idp.example.com",
    "audiences": ["kubernetes"],
    "discovery_url": "https://idp.example.com/.well-known/openid-configuration",
    "certificate_authority": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "claim_mappings": {
    "username": {"claim": "email", "prefix": "oidc:"},
    "groups": {"claim": "groups", "prefix": "oidc:"}
  },
  "claim_validation_rules": [
    {"claim": "team", "required_value": "platform"}
  ],
  "user_validation_rules": [
    {
      "expression": "user.groups.exists(g, g == \"oidc:k8s-engineering\")",
      "message": "The user must be in the oidc:k8s-engineering group"
    }
  ]
}
```

| Parameter | Required or optional | Description |
| - | - | - |
| `name` | Required | Provider name. Must be unique within the cluster. It doesn't become part of usernames or group names. |
| `issuer.url` | Required | Issuer URL of the IdP. It must match the `iss` claim of tokens and the `issuer` field of the IdP's discovery document. The URL must use HTTPS, must not contain a query or a fragment, and must be unique within the cluster. For the issuer URL formats of popular IdPs, see [Issuer URLs](#issuer-urls). The issuer URL can't point to the cluster itself, for example, to its API server endpoints or its [OIDC public endpoint](https://docs.nebius.com/kubernetes/networking/oidc-public-endpoint.md). The cluster already trusts the tokens that it issues to its ServiceAccounts. |
| `issuer.audiences` | Required | Token audiences that the cluster accepts, usually the client ID of the application that you registered in the IdP. Specify at least one. The values must be unique. A token is accepted if its `aud` claim contains at least one of them. |
| `claim_mappings.username` | Required | How to get the Kubernetes username from the token claims. For more information, see [Claim mappings](#claim-mappings). |
| `claim_mappings.groups` | Optional | How to get Kubernetes groups from the token claims. If you don't specify it, users from this provider have no groups from the token. |
| `issuer.discovery_url` | Optional | URL of the discovery document, if it differs from `<issuer_URL>/.well-known/openid-configuration`. Must differ from `issuer.url`. The `issuer` field of the document must still match `issuer.url`. |
| `issuer.certificate_authority` | Optional | PEM bundle of certificate authorities that the API server trusts when it gets the discovery document and the public keys of the IdP. If you don't specify it, the API server uses the system trust store. |
| `claim_validation_rules` | Optional | Rules that the token claims must pass. For more information, see [Validation rules](#validation-rules). |
| `user_validation_rules` | Optional | Rules that the mapped username and groups must pass. For more information, see [Validation rules](#validation-rules). |

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:

| IdP | Issuer URL | Documentation |
| - | - | - |
| Okta | `https://<okta_domain>/oauth2/default` for the default custom authorization server | [Create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) |
| Microsoft Entra ID | `https://login.microsoftonline.com/<tenant_ID>/v2.0` | [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) |
| Google | `https://accounts.google.com` | [OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect) |
| Keycloak | `https://<keycloak_host>/realms/<realm>` | [Managing OpenID Connect clients](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients) |

### 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)](https://kubernetes.io/docs/reference/using-api/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.

> [!WARNING]
>
> 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](#provider-configuration) 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](https://docs.nebius.com/kubernetes/authentication/oidc-authentication.md#how-to-update-oidc-providers).

## See also

* [How to configure external OIDC providers in Managed Service for Kubernetes®](https://docs.nebius.com/kubernetes/authentication/oidc-authentication.md)
* [Troubleshooting authentication with external OIDC providers in Managed Service for Kubernetes®](https://docs.nebius.com/kubernetes/authentication/troubleshoot-oidc-providers.md)
* [Configuration via configuration file](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#api-server-authn-config-file) in the Kubernetes documentation
