--- reviewers: - erictune - lavalamp - deads2k - liggitt title: Authenticating content_type: concept weight: 10 --- This page provides an overview of authentication in Kubernetes, with a focus on authentication to the [Kubernetes API](/docs/concepts/overview/kubernetes-api/). ## Users in Kubernetes All Kubernetes clusters have two categories of users: service accounts managed by Kubernetes, and normal users. It is assumed that a cluster-independent service manages normal users in the following ways: - an administrator distributing private keys - a user store like Keystone or Google Accounts - a file with a list of usernames and passwords In this regard, _Kubernetes does not have objects which represent normal user accounts._ Normal users cannot be added to a cluster through an API call. Even though a normal user cannot be added via an API call, any user that presents a valid certificate signed by the cluster's certificate authority (CA) is considered authenticated. In this configuration, Kubernetes determines the username from the common name field in the 'subject' of the cert (e.g., "/CN=bob"). From there, the role based access control (RBAC) sub-system would determine whether the user is authorized to perform a specific operation on a resource. In contrast, service accounts are users managed by the Kubernetes API. They are bound to specific namespaces, and created automatically by the API server or manually through API calls. Service accounts are tied to a set of credentials stored as `Secrets`, which are mounted into pods allowing in-cluster processes to talk to the Kubernetes API. API requests are tied to either a normal user or a service account, or are treated as [anonymous requests](#anonymous-requests). This means every process inside or outside the cluster, from a human user typing `kubectl` on a workstation, to `kubelets` on nodes, to members of the control plane, must authenticate when making requests to the API server, or be treated as an anonymous user. If you attempt to authenticate and it succeeds, the API server automatically marks that you are a member of the special group `system:authenticated`. ## Authentication strategies Kubernetes uses client certificates, bearer tokens, or an authenticating proxy to authenticate API requests through authentication plugins. As HTTP requests are made to the API server, plugins attempt to associate the following attributes with the request: * Username: a string which identifies the end user. Common values might be `kube-admin` or `jane@example.com`. * UID: a string which identifies the end user and attempts to be more consistent and unique than username. * Groups: a set of strings, each of which indicates the user's membership in a named logical collection of users. Common values might be `system:masters` or `devops-team`. * Extra fields: a map of strings to list of strings which holds additional information authorizers may find useful. {{< note >}} All values are opaque to the authentication system and only hold significance when interpreted by an [authorizer](/docs/reference/access-authn-authz/authorization/). {{< /note >}} ## Anonymous requests When enabled, requests that are not rejected by other configured authentication methods are treated as anonymous requests, and given a username of `system:anonymous` and a group of `system:unauthenticated`. For example, on a server with token authentication configured, and anonymous access enabled, a request providing an invalid bearer token would receive a `401 Unauthorized` error. A request providing no bearer token would be treated as an anonymous request. Anonymous access is enabled by default if an [authorization mode](/docs/reference/access-authn-authz/authorization/#authorization-modules) other than `AlwaysAllow` is used; you can disable it by passing the `--anonymous-auth=false` command line option to the API server. The built-in ABAC and RBAC authorizers require explicit authorization of the `system:anonymous` user or the `system:unauthenticated` group; if you have legacy policy rules (from Kubernetes version 1.5 or earlier), those legacy rules that grant access to the `*` user or `*` group do not automatically allow access to anonymous users. ### Anonymous authenticator configuration {{< feature-state feature_gate_name="AnonymousAuthConfigurableEndpoints" >}} The `AuthenticationConfiguration` can be used to configure the anonymous authenticator. If you set the anonymous field in the `AuthenticationConfiguration` file then you cannot set the `--anonymous-auth` command line option. The main advantage of configuring anonymous authenticator using the authentication configuration file is that in addition to enabling and disabling anonymous authentication you can also configure which endpoints support anonymous authentication. A sample authentication configuration file is below: {{< highlight yaml "linenos=false,hl_lines=2-5" >}} --- # # CAUTION: this is an example configuration. # Do not use this as-is for your own cluster! # apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration anonymous: enabled: true conditions: - path: /livez - path: /readyz - path: /healthz {{< /highlight >}} In the configuration above, only the `/livez`, `/readyz` and `/healthz` endpoints are reachable by anonymous requests. Any other endpoints will not be reachable anonymously, even if your authorization configuration would allow it. ## Authentication methods You can enable multiple authentication methods at once. You should usually use at least two methods: - [service account tokens](/docs/concepts/security/service-accounts/#authenticating-credentials) for ServiceAccounts - at least one other method for (normal) user authentication Available authentication methods include: * [X.509 client certificates](#x509-client-certificates) * [Bootstrap tokens](#bootstrap-tokens) * [Service account tokens](#service-account-tokens) * [Static token file](#static-token-file) * [External integrations](#external-integrations) * [JSON Web Tokens](#json-web-token-authentication) * [OpenID Connect Tokens](#openid-connect-tokens) * [Webhook token authentication](#webhook-token-authentication) * [Authenticating reverse proxy](#authenticating-proxy) When multiple authenticator modules are enabled, the first module to successfully authenticate the request short-circuits evaluation. The API server does not guarantee the order authenticators run in. ### X.509 client certificates {#x509-client-certificates} Any Kubernetes client that presents a valid client certificate signed by the cluster's _client trust_ certificate authority (CA) is considered authenticated. In this configuration, Kubernetes determines the username from the `commonName` field in the _subject_ of the certificate (for example, `commonName=bob` represents a user with username "bob"). From there, Kubernetes [authorization](/docs/reference/access-authn-authz/authorization) mechanisms determine whether the user is allowed to perform a specific operation on a resource. Client certificate authentication is enabled by passing the `--client-ca-file=` option to the API server. This option configures the cluster's _client trust_ certificate authority. The referenced file must contain one or more certificate authorities that the API server can use, when it needs to validate client certificates. If a client certificate is presented and verified, the common name of the subject is used as the user name for the request. Client certificates can also indicate a user's group memberships using the certificate's organization fields. To include multiple group memberships for a user, include multiple organization fields in the certificate. See [Managing Certificates](/docs/tasks/administer-cluster/certificates/) for how to generate a client cert, or read the brief [example](#x509-client-certificates-example) later in this page. #### Kubernetes-compatible client certificates {#x509-client-certificates-k8s} You can present a valid certificate, issued by a CA in a trust chain that the API server accepts for client certificates, and use that to authenticate to Kubernetes. The certificate must be valid; the API server checks that based on the X.509 `notBefore` and `notAfter` attributes, and the certificate must have an _extended key usage_ that includes client authentication (`ClientAuth`). {{< note >}} Kubernetes {{< skew currentVersion >}} does not support certificate _revocation_. Any certificate that is issued remains valid until it expires. {{< /note >}} ##### Username mapping {#x509-client-certificates-k8s-username} Kubernetes expects a client certificate that contains a `commonName` (OID `2.5.4.3`) attribute, that is used as the username of the subject. ##### User ID mapping {{< feature-state feature_gate_name="AllowParsingUserUIDFromCertAuth" >}} To use this feature, the certificate must have the attribute `1.3.6.1.4.1.57683.2` included, and the `AllowParsingUserUIDFromCertAuth` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) must be enabled (it is on by default). Kubernetes can parse an **optional** user UID from a certificate. UID is different from user name; it is an opaque value with a meaning defined by the person who requested the certificate, or alternatively by whoever has set the certificate approval rules. For example, the UID could be `1042` (a simple integer) in one cluster, but another certificate might use `d3f77937-ec82-4f16-8010-61821abe315a` (a UUID) as the UID. Here is an example to explain what that means. If you have a certificate with the common name set to "Ada Lovelace" and the certificate also had a `uid` attribute, (OID `0.9.2342.19200300.100.1.1`) with uid set to "aaking1815", Kubernetes considers that the client's username is "Ada Lovelace"; Kubernetes ignores the `uid` attribute because it is not the CNCF-specific OID that Kubernetes looks for. If you wanted `aaking1815` to be recognized as UID by Kubernetes, it must be set as a value to the OID `1.3.6.1.4.1.57683.2` attribute in the certificate's subject. ##### Group mapping {#x509-client-certificates-k8s-group} You can map a user into groups by statically including group information into the certificate. For each group that the user is a member of, add the group name as an `organization` (OID `2.5.6.4`) in your certificate's subject. To include multiple group memberships for a user, include multiple organizations in the certificate subject (the order does not matter). For the example user, the distinguished name for a certificate might be CN=Ada Lovelace,O=Users,O=Staff,O=Programmers, which would place her into the groups "Programmers", "Staff", "system:authenticated", and "Users". Putting group information into a certificate is optional; if you don't specify any groups in the certificate, then the user will be a member of "system:authenticated" only. ##### Node client certificates {#x509-client-certificates-nodes} Kubernetes can use the same approach for node identity; nodes are clients of the Kubernetes API server that run a {{}} (also, although less relevant here, the API server is usually also a client of each node). For example: a Node "server-1a-antarctica42", with the domain name "server-1a-antarctica42.cluster.example", could use a certificate issued to "CN=system:node:server-1a-antarctica/42,O=system:nodes". The node's username is then "system:node:server-1a-antarctica/g42", and the node is a member of "system:authenticated" and "system:nodes". The kubelet uses the node's certificate and private key to authenticate to the cluster's API server. {{< note >}} Machine identities for nodes are not the same as {{< glossary_tooltip text="ServiceAccounts" term_id="service-account" >}}. {{< /note >}} #### Example {#x509-client-certificates-example} You could use the `openssl` command line tool to generate a certificate signing request: ```bash # This example assumes that you already have a private key alovelace.pem openssl req -new -key alovelace.pem -out alovelace-csr.pem -subj "/CN=alovelace/O=app1/O=app2" ``` This would create a signing request for the username "alovelace", belonging to two groups, "app1" and "app2". You could then have that signing request be signed by your cluster's client trust certificate authority to obtain a certificate you can use for client authentication to your cluster. ### Bootstrap tokens {{< feature-state for_k8s_version="v1.18" state="stable" >}} To allow for streamlined bootstrapping for new clusters, Kubernetes includes a dynamically-managed Bearer token type called a *Bootstrap Token*. These tokens are stored as Secrets in the `kube-system` namespace, where they can be dynamically managed and created. Controller Manager contains a TokenCleaner controller that deletes bootstrap tokens as they expire. The tokens are of the form `[a-z0-9]{6}.[a-z0-9]{16}`. The first component is a Token ID and the second component is the Token Secret. You specify the token in an HTTP header as follows: ```http Authorization: Bearer 781292.db7bc3a58fc5f07e ``` You must enable the Bootstrap Token Authenticator with the `--enable-bootstrap-token-auth` flag on the API Server. You must enable the TokenCleaner controller via the `--controllers` command line argument for kube-controller-manager. This is done with something like `--controllers=*,tokencleaner`. The `kubeadm` tool will do this for you if you are using it to bootstrap a cluster. The authenticator authenticates as `system:bootstrap:`. It is included in the `system:bootstrappers` group. The naming and groups are intentionally limited to discourage users from using these tokens past bootstrapping. The user names and group can be used (and are used by `kubeadm`) to craft the appropriate authorization policies to support bootstrapping a cluster. Please see [Bootstrap Tokens](/docs/reference/access-authn-authz/bootstrap-tokens/) for in depth documentation on the Bootstrap Token authenticator and controllers along with how to manage these tokens with `kubeadm`. #### Putting a bearer token in a request When using bearer token authentication from an HTTP client, the API server expects an `Authorization` header with a value of `Bearer `. The bearer token must be a character sequence that can be put in an HTTP header value using no more than the encoding and quoting facilities of HTTP. For example: if the bearer token is `31ada4fd-adec-460c-809a-9e56ceb75269` then it would appear in an HTTP header as shown below. ```http Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269 ``` ### Service account tokens A service account is an automatically enabled authenticator that uses signed bearer tokens to verify requests. The plugin takes two optional flags: * `--service-account-key-file` File containing PEM-encoded x509 RSA or ECDSA private or public keys, used to verify ServiceAccount tokens. The specified file can contain multiple keys, and the flag can be specified multiple times with different files. If unspecified, --tls-private-key-file is used. * `--service-account-lookup` If enabled, tokens which are deleted from the API will be revoked. Service accounts are usually created automatically by the API server and associated with pods running in the cluster through the `ServiceAccount` [Admission Controller](/docs/reference/access-authn-authz/admission-controllers/). Bearer tokens are mounted into pods at well-known locations, and allow in-cluster processes to talk to the API server. Accounts may be explicitly associated with pods using the `serviceAccountName` field of a `PodSpec`. {{< note >}} `serviceAccountName` is usually omitted because this is done automatically. {{< /note >}} ```yaml apiVersion: apps/v1 # this apiVersion is relevant as of Kubernetes 1.9 kind: Deployment metadata: name: nginx-deployment namespace: default spec: replicas: 3 template: metadata: # ... spec: serviceAccountName: bob-the-bot containers: - name: nginx image: nginx:1.14.2 ``` Service account bearer tokens are perfectly valid to use outside the cluster and can be used to create identities for long standing jobs that wish to talk to the Kubernetes API. To manually create a service account, use the `kubectl create serviceaccount (NAME)` command. This creates a service account in the current namespace. ```bash kubectl create serviceaccount jenkins ``` ```none serviceaccount/jenkins created ``` You can manually create an associated token: ```bash kubectl create token jenkins ``` ```none eyJhbGciOiJSUzI1NiIsImtp... ``` The created token is a signed [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (JWT). The signed JWT can be used as a bearer token to authenticate as the given service account. See [above](#putting-a-bearer-token-in-a-request) for how the token is included in a request. Normally these tokens are mounted into pods for in-cluster access to the API server, but can be used from outside the cluster as well. Service accounts authenticate with the username `system:serviceaccount:(NAMESPACE):(SERVICEACCOUNT)`, and are assigned to the groups `system:serviceaccounts` and `system:serviceaccounts:(NAMESPACE)`. {{< warning >}} Because service account tokens can also be stored in Secret API objects, any user with write access to Secrets can request a token, and any user with read access to those Secrets can authenticate as the service account. Be cautious when granting permissions to service accounts and read or write capabilities for Secrets. {{< /warning >}} ## External integrations Kubernetes has native support for JWT and for OpenID Connect (OIDC); see [JSON Web Token authentication](#json-web-token-authentication). Integrations with other authentication protocols (for example: LDAP, SAML, Kerberos, alternate X.509 schemes) can be accomplished using an [authenticating proxy](#authenticating-proxy) or by integrating with an [authentication webhook](#webhook-token-authentication). You can also use any custom method that issues [client X.509 certificates](#x509-client-certificates) to clients, provided that the API server will trust the valid certificates. Read [X.509 client certificates](#x509-client-certificates) to learn about how to generate a certificate. If you do issue certificates to clients, it is up to you (as a cloud platform administrator) to make sure that the certificate validity period, and other design choices you make, provide a suitable level of security. ### JSON Web Token authentication You can configure Kubernetes to authenticate users using [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (JWT) compliant tokens. JWT authentication mechanism is used for the ServiceAccount tokens that Kubernetes itself issues, and you can also use it to integrate with other identity sources. The authenticator attempts to parse a raw ID token, verify it's been signed by the configured issuer. For externally issued tokens, the public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery. The minimum valid JWT payload **must** contain the following claims: ```javascript { "iss": "https://example.com", // must match the issuer.url "aud": ["my-app"], // at least one of the entries in issuer.audiences must match the "aud" claim in presented JWTs. "exp": 1234567890, // token expiration as Unix time (the number of seconds elapsed since January 1, 1970 UTC) "": "user" // this is the username claim configured in the claimMappings.username.claim or claimMappings.username.expression } ``` #### JWT egress selector type {{< feature-state feature_gate_name="StructuredAuthenticationConfigurationEgressSelector" >}} The `egressSelectorType` field in the JWT issuer configuration allows you to specify which _egress selector_ should be used for sending all traffic related to the issuer (discovery, JWKS, distributed claims, etc). This feature requires the `StructuredAuthenticationConfigurationEgressSelector` feature gate to be enabled. #### OpenID Connect tokens [OpenID Connect](https://openid.net/connect/) is a flavor of OAuth2 supported by some OAuth2 providers, notably Microsoft Entra ID, Salesforce, and Google. The protocol's main extension of OAuth2 is an additional field returned with the access token called an [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). This token is a JSON Web Token (JWT) with well known fields, such as a user's email, signed by the server. To identify the user, the authenticator uses the `id_token` (not the `access_token`) from the OAuth2 [token response](https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) as a bearer token. See [above](#putting-a-bearer-token-in-a-request) for how the token is included in a request. {{< mermaid >}} sequenceDiagram participant user as User participant idp as Identity Provider participant kube as kubectl participant api as API Server user ->> idp: 1. Log in to IdP activate idp idp -->> user: 2. Provide access_token,
id_token, and refresh_token deactivate idp activate user user ->> kube: 3. Call kubectl
with --token being the id_token
OR add tokens to .kube/config deactivate user activate kube kube ->> api: 4. Authorization: Bearer... deactivate kube activate api api ->> api: 5. Is JWT signature valid? api ->> api: 6. Has the JWT expired? (iat+exp) api ->> api: 7. User authorized? api -->> kube: 8. Authorized: Perform
action and return result deactivate api activate kube kube --x user: 9. Return result deactivate kube {{< /mermaid >}} 1. Log in to your identity provider 1. Your identity provider will provide you with an `access_token`, `id_token` and a `refresh_token` 1. When using `kubectl`, use your `id_token` with the `--token` command line argument or add it directly to your `kubeconfig` 1. `kubectl` sends your `id_token` in a header called Authorization to the API server 1. The API server will make sure the JWT signature is valid 1. Check to make sure the `id_token` hasn't expired Perform claim and/or user validation if CEL expressions are configured with `AuthenticationConfiguration`. 1. Make sure the user is authorized 1. Once authorized the API server returns a response to `kubectl` 1. `kubectl` provides feedback to the user Since all of the data needed to validate who you are is in the `id_token`, Kubernetes doesn't need to "phone home" to the identity provider. In a model where every request is stateless this provides a very scalable solution for authentication. It does offer a few challenges: 1. Kubernetes has no "web interface" to trigger the authentication process. There is no browser or interface to collect credentials which is why you need to authenticate to your identity provider first. 1. The `id_token` can't be revoked, it's like a certificate so it should be short-lived (only a few minutes) so it can be very annoying to have to get a new token every few minutes. 1. To authenticate to the Kubernetes dashboard, you must use the `kubectl proxy` command or a reverse proxy that injects the `id_token`. #### Configuring the API Server ##### Using command line arguments To enable the plugin, configure the following command line arguments for the API server: | Parameter | Description | Example | Required | | --------- | ----------- | ------- | ------- | | `--oidc-issuer-url` | URL of the provider that allows the API server to discover public signing keys. Only URLs that use the `https://` scheme are accepted. This is typically the provider's discovery URL, changed to have an empty path. | If the issuer's OIDC discovery URL is `https://accounts.provider.example/.well-known/openid-configuration`, the value should be `https://accounts.provider.example` | Yes | | `--oidc-client-id` | A client id that all tokens must be issued for. | kubernetes | Yes | | `--oidc-username-claim` | JWT claim to use as the user name. By default `sub`, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as `email` or `name`, depending on their provider. However, claims other than `email` will be prefixed with the issuer URL to prevent naming clashes with other plugins. | sub | No | | `--oidc-username-prefix` | Prefix prepended to username claims to prevent clashes with existing names (such as `system:` users). For example, the value `oidc:` will create usernames like `oidc:jane.doe`. If this argument isn't provided and `--oidc-username-claim` is a value other than `email` the prefix defaults to `( Issuer URL )#` where `( Issuer URL )` is the value of `--oidc-issuer-url`. The value `-` can be used to disable all prefixing. | `oidc:` | No | | `--oidc-groups-claim` | JWT claim to use as the user's group. If the claim is present it must be an array of strings. | groups | No | | `--oidc-groups-prefix` | Prefix prepended to group claims to prevent clashes with existing names (such as `system:` groups). For example, the value `oidc:` will create group names like `oidc:engineering` and `oidc:infra`. | `oidc:` | No | | `--oidc-required-claim` | A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. Repeat this argument to specify multiple claims. | `claim=value` | No | | `--oidc-ca-file` | The path to the certificate for the CA that signed your identity provider's web certificate. Defaults to the host's root CAs. | `/etc/kubernetes/ssl/kc-ca.pem` | No | | `--oidc-signing-algs` | The signing algorithms accepted. Default is RS256. Allowed values are: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Values are defined by RFC 7518 https://tools.ietf.org/html/rfc7518#section-3.1. | `RS512` | No | ##### Authentication configuration from a file {#using-authentication-configuration} {{< feature-state feature_gate_name="StructuredAuthenticationConfiguration" >}} The configuration file approach allows you to configure multiple JWT authenticators, each with a unique `issuer.url` and `issuer.discoveryURL`. The configuration file even allows you to specify [CEL](/docs/reference/using-api/cel/) expressions to map claims to user attributes, and to validate claims and user information. The API server also automatically reloads the authenticators when the configuration file is modified. You can use `apiserver_authentication_config_controller_automatic_reload_last_timestamp_seconds` metric to monitor the last time the configuration was reloaded by the API server. You must specify the path to the authentication configuration using the `--authentication-config` command line argument to the API server. If you want to use command line arguments instead of the configuration file, those will continue to work as-is. To access the new capabilities like configuring multiple authenticators, setting multiple audiences for an issuer, switch to using the configuration file. To use structured authentication, specify the `--authentication-config` command line argument to the kube-apiserver. An example of the structured authentication configuration file is shown below. {{< note >}} If you specify `--authentication-config` along with any of the `--oidc-*` command line arguments, this is a misconfiguration. In this situation, the API server reports an error and then immediately exits. If you want to switch to using structured authentication configuration, you have to remove the `--oidc-*` command line arguments, and use the configuration file instead. {{< /note >}} {{< highlight yaml "linenos=false,hl_lines=2-5" >}} --- # # CAUTION: this is an example configuration. # Do not use this for your own cluster! # apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration # list of authenticators to authenticate Kubernetes users using JWT compliant tokens. # the maximum number of allowed authenticators is 64. jwt: - issuer: # url must be unique across all authenticators. # url must not conflict with issuer configured in --service-account-issuer. url: https://example.com # Same as --oidc-issuer-url. # discoveryURL, if specified, overrides the URL used to fetch discovery # information instead of using "{url}/.well-known/openid-configuration". # The exact value specified is used, so "/.well-known/openid-configuration" # must be included in discoveryURL if needed. # # The "issuer" field in the fetched discovery information must match the "issuer.url" field # in the AuthenticationConfiguration and will be used to validate the "iss" claim in the presented JWT. # This is for scenarios where the well-known and jwks endpoints are hosted at a different # location than the issuer (such as locally in the cluster). # discoveryURL must be different from url if specified and must be unique across all authenticators. discoveryURL: https://discovery.example.com/.well-known/openid-configuration # PEM encoded CA certificates used to validate the connection when fetching # discovery information. If not set, the system verifier will be used. # Same value as the content of the file referenced by the --oidc-ca-file command line argument. certificateAuthority: # audiences is the set of acceptable audiences the JWT must be issued to. # At least one of the entries must match the "aud" claim in presented JWTs. audiences: - my-app # Same as --oidc-client-id. - my-other-app # this is required to be set to "MatchAny" when multiple audiences are specified. audienceMatchPolicy: MatchAny # egressSelectorType is an indicator of which egress selection should be used for sending all traffic related # to this issuer (discovery, JWKS, distributed claims, etc). If unspecified, no custom dialer is used. # The StructuredAuthenticationConfigurationEgressSelector feature gate must be enabled # before you can use the egressSelectorType field. # When specified, the valid choices are "controlplane" and "cluster". These correspond to the associated # values in the --egress-selector-config-file. # - controlplane: for traffic intended to go to the control plane. # - cluster: for traffic intended to go to the system being managed by Kubernetes. egressSelectorType: # rules applied to validate token claims to authenticate users. claimValidationRules: # Same as --oidc-required-claim key=value. - claim: hd requiredValue: example.com # Instead of claim and requiredValue, you can use expression to validate the claim. # expression is a CEL expression that evaluates to a boolean. # all the expressions must evaluate to true for validation to succeed. - expression: 'claims.hd == "example.com"' # Message customizes the error message seen in the API server logs when the validation fails. message: the hd claim must be set to example.com - expression: 'claims.exp - claims.nbf <= 86400' message: total token lifetime must not exceed 24 hours claimMappings: # username represents an option for the username attribute. # This is the only required attribute. username: # Same as --oidc-username-claim. Mutually exclusive with username.expression. claim: "sub" # Same as --oidc-username-prefix. Mutually exclusive with username.expression. # if username.claim is set, username.prefix is required. # Explicitly set it to "" if no prefix is desired. prefix: "" # Mutually exclusive with username.claim and username.prefix. # expression is a CEL expression that evaluates to a string. # # 1. If username.expression uses 'claims.email', then 'claims.email_verified' must be used in # username.expression or extra[*].valueExpression or claimValidationRules[*].expression. # An example claim validation rule expression that matches the validation automatically # applied when username.claim is set to 'email' is 'claims.?email_verified.orValue(true) == true'. # By explicitly comparing the value to true, we let type-checking see the result will be a boolean, and # to make sure a non-boolean email_verified claim will be caught at runtime. # 2. If the username asserted based on username.expression is the empty string, the authentication # request will fail. expression: 'claims.username + ":external-user"' # groups represents an option for the groups attribute. groups: # Same as --oidc-groups-claim. Mutually exclusive with groups.expression. claim: "sub" # Same as --oidc-groups-prefix. Mutually exclusive with groups.expression. # if groups.claim is set, groups.prefix is required. # Explicitly set it to "" if no prefix is desired. prefix: "" # Mutually exclusive with groups.claim and groups.prefix. # expression is a CEL expression that evaluates to a string or a list of strings. expression: 'claims.roles.split(",")' # uid represents an option for the uid attribute. uid: # Mutually exclusive with uid.expression. claim: 'sub' # Mutually exclusive with uid.claim # expression is a CEL expression that evaluates to a string. expression: 'claims.sub' # extra attributes to be added to the UserInfo object. Keys must be domain-prefix path and must be unique. extra: # key is a string to use as the extra attribute key. # key must be a domain-prefix path (e.g. example.org/foo). All characters before the first "/" must be a valid # subdomain as defined by RFC 1123. All characters trailing the first "/" must # be valid HTTP Path characters as defined by RFC 3986. # k8s.io, kubernetes.io and their subdomains are reserved for Kubernetes use and cannot be used. # key must be lowercase and unique across all extra attributes. - key: 'example.com/tenant' # valueExpression is a CEL expression that evaluates to a string or a list of strings. valueExpression: 'claims.tenant' # validation rules applied to the final user object. userValidationRules: # expression is a CEL expression that evaluates to a boolean. # all the expressions must evaluate to true for the user to be valid. - expression: "!user.username.startsWith('system:')" # Message customizes the error message seen in the API server logs when the validation fails. message: 'username cannot used reserved system: prefix' - expression: "user.groups.all(group, !group.startsWith('system:'))" message: 'groups cannot used reserved system: prefix' {{< /highlight >}} * Claim validation rule expression `jwt.claimValidationRules[i].expression` represents the expression which will be evaluated by CEL. CEL expressions have access to the contents of the token payload, organized into `claims` CEL variable. `claims` is a map of claim names (as strings) to claim values (of any type). * User validation rule expression `jwt.userValidationRules[i].expression` represents the expression which will be evaluated by CEL. CEL expressions have access to the contents of `userInfo`, organized into `user` CEL variable. Refer to the [UserInfo](/docs/reference/generated/kubernetes-api/v{{< skew currentVersion >}}/#userinfo-v1-authentication-k8s-io) API documentation for the schema of `user`. * Claim mapping expression `jwt.claimMappings.username.expression`, `jwt.claimMappings.groups.expression`, `jwt.claimMappings.uid.expression` `jwt.claimMappings.extra[i].valueExpression` represents the expression which will be evaluated by CEL. CEL expressions have access to the contents of the token payload, organized into `claims` CEL variable. `claims` is a map of claim names (as strings) to claim values (of any type). To learn more, see the [Documentation on CEL](/docs/reference/using-api/cel/) Here are examples of the `AuthenticationConfiguration` with different token payloads. {{< tabs name="example_configuration" >}} {{% tab name="Valid token" %}} ```yaml apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration jwt: - issuer: url: https://example.com audiences: - my-app claimMappings: username: expression: 'claims.username + ":external-user"' groups: expression: 'claims.roles.split(",")' uid: expression: 'claims.sub' extra: - key: 'example.com/tenant' valueExpression: 'claims.tenant' userValidationRules: - expression: "!user.username.startsWith('system:')" # the expression will evaluate to true, so validation will succeed. message: 'username cannot used reserved system: prefix' ``` ```bash TOKEN=eyJhbGciOiJSUzI1NiIsImtpZCI6ImY3dF9tOEROWmFTQk1oWGw5QXZTWGhBUC04Y0JmZ0JVbFVpTG5oQkgxdXMiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNzAzMjMyOTQ5LCJpYXQiOjE3MDExMDcyMzMsImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5jb20iLCJqdGkiOiI3YzMzNzk0MjgwN2U3M2NhYTJjMzBjODY4YWMwY2U5MTBiY2UwMmRkY2JmZWJlOGMyM2I4YjVmMjdhZDYyODczIiwibmJmIjoxNzAxMTA3MjMzLCJyb2xlcyI6InVzZXIsYWRtaW4iLCJzdWIiOiJhdXRoIiwidGVuYW50IjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjRhIiwidXNlcm5hbWUiOiJmb28ifQ.TBWF2RkQHm4QQz85AYPcwLxSk-VLvQW-mNDHx7SEOSv9LVwcPYPuPajJpuQn9C_gKq1R94QKSQ5F6UgHMILz8OfmPKmX_00wpwwNVGeevJ79ieX2V-__W56iNR5gJ-i9nn6FYk5pwfVREB0l4HSlpTOmu80gbPWAXY5hLW0ZtcE1JTEEmefORHV2ge8e3jp1xGafNy6LdJWabYuKiw8d7Qga__HxtKB-t0kRMNzLRS7rka_SfQg0dSYektuxhLbiDkqhmRffGlQKXGVzUsuvFw7IGM5ZWnZgEMDzCI357obHeM3tRqpn5WRjtB8oM7JgnCymaJi-P3iCd88iu1xnzA ``` where the token payload is: ```json { "aud": "kubernetes", "exp": 1703232949, "iat": 1701107233, "iss": "https://example.com", "jti": "7c337942807e73caa2c30c868ac0ce910bce02ddcbfebe8c23b8b5f27ad62873", "nbf": 1701107233, "roles": "user,admin", "sub": "auth", "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db4a", "username": "foo" } ``` The token with the above `AuthenticationConfiguration` will produce the following `UserInfo` object and successfully authenticate the user. ```json { "username": "foo:external-user", "uid": "auth", "groups": [ "user", "admin" ], "extra": { "example.com/tenant": ["72f988bf-86f1-41af-91ab-2d7cd011db4a"] } } ``` {{% /tab %}} {{% tab name="Fails claim validation" %}} ```yaml apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration jwt: - issuer: url: https://example.com audiences: - my-app claimValidationRules: - expression: 'claims.hd == "example.com"' # the token below does not have this claim, so validation will fail. message: the hd claim must be set to example.com claimMappings: username: expression: 'claims.username + ":external-user"' groups: expression: 'claims.roles.split(",")' uid: expression: 'claims.sub' extra: - key: 'example.com/tenant' valueExpression: 'claims.tenant' userValidationRules: - expression: "!user.username.startsWith('system:')" # the expression will evaluate to true, so validation will succeed. message: 'username cannot used reserved system: prefix' ``` ```bash TOKEN=eyJhbGciOiJSUzI1NiIsImtpZCI6ImY3dF9tOEROWmFTQk1oWGw5QXZTWGhBUC04Y0JmZ0JVbFVpTG5oQkgxdXMiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNzAzMjMyOTQ5LCJpYXQiOjE3MDExMDcyMzMsImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5jb20iLCJqdGkiOiI3YzMzNzk0MjgwN2U3M2NhYTJjMzBjODY4YWMwY2U5MTBiY2UwMmRkY2JmZWJlOGMyM2I4YjVmMjdhZDYyODczIiwibmJmIjoxNzAxMTA3MjMzLCJyb2xlcyI6InVzZXIsYWRtaW4iLCJzdWIiOiJhdXRoIiwidGVuYW50IjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjRhIiwidXNlcm5hbWUiOiJmb28ifQ.TBWF2RkQHm4QQz85AYPcwLxSk-VLvQW-mNDHx7SEOSv9LVwcPYPuPajJpuQn9C_gKq1R94QKSQ5F6UgHMILz8OfmPKmX_00wpwwNVGeevJ79ieX2V-__W56iNR5gJ-i9nn6FYk5pwfVREB0l4HSlpTOmu80gbPWAXY5hLW0ZtcE1JTEEmefORHV2ge8e3jp1xGafNy6LdJWabYuKiw8d7Qga__HxtKB-t0kRMNzLRS7rka_SfQg0dSYektuxhLbiDkqhmRffGlQKXGVzUsuvFw7IGM5ZWnZgEMDzCI357obHeM3tRqpn5WRjtB8oM7JgnCymaJi-P3iCd88iu1xnzA ``` where the token payload is: ```json { "aud": "kubernetes", "exp": 1703232949, "iat": 1701107233, "iss": "https://example.com", "jti": "7c337942807e73caa2c30c868ac0ce910bce02ddcbfebe8c23b8b5f27ad62873", "nbf": 1701107233, "roles": "user,admin", "sub": "auth", "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db4a", "username": "foo" } ``` The token with the above `AuthenticationConfiguration` will fail to authenticate because the `hd` claim is not set to `example.com`. The API server will return `401 Unauthorized` error. {{% /tab %}} {{% tab name="Fails user validation" %}} ```yaml apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration jwt: - issuer: url: https://example.com audiences: - my-app claimValidationRules: - expression: 'claims.hd == "example.com"' message: the hd claim must be set to example.com claimMappings: username: expression: '"system:" + claims.username' # this will prefix the username with "system:" and will fail user validation. groups: expression: 'claims.roles.split(",")' uid: expression: 'claims.sub' extra: - key: 'example.com/tenant' valueExpression: 'claims.tenant' userValidationRules: - expression: "!user.username.startsWith('system:')" # the username will be system:foo and expression will evaluate to false, so validation will fail. message: 'username cannot used reserved system: prefix' ``` ```bash TOKEN=eyJhbGciOiJSUzI1NiIsImtpZCI6ImY3dF9tOEROWmFTQk1oWGw5QXZTWGhBUC04Y0JmZ0JVbFVpTG5oQkgxdXMiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNzAzMjMyOTQ5LCJoZCI6ImV4YW1wbGUuY29tIiwiaWF0IjoxNzAxMTEzMTAxLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tIiwianRpIjoiYjViMDY1MjM3MmNkMjBlMzQ1YjZmZGZmY2RjMjE4MWY0YWZkNmYyNTlhYWI0YjdlMzU4ODEyMzdkMjkyMjBiYyIsIm5iZiI6MTcwMTExMzEwMSwicm9sZXMiOiJ1c2VyLGFkbWluIiwic3ViIjoiYXV0aCIsInRlbmFudCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0YSIsInVzZXJuYW1lIjoiZm9vIn0.FgPJBYLobo9jnbHreooBlvpgEcSPWnKfX6dc0IvdlRB-F0dCcgy91oCJeK_aBk-8zH5AKUXoFTlInfLCkPivMOJqMECA1YTrMUwt_IVqwb116AqihfByUYIIqzMjvUbthtbpIeHQm2fF0HbrUqa_Q0uaYwgy8mD807h7sBcUMjNd215ff_nFIHss-9zegH8GI1d9fiBf-g6zjkR1j987EP748khpQh9IxPjMJbSgG_uH5x80YFuqgEWwq-aYJPQxXX6FatP96a2EAn7wfPpGlPRt0HcBOvq5pCnudgCgfVgiOJiLr_7robQu4T1bis0W75VPEvwWtgFcLnvcQx0JWg ``` where the token payload is: ```json { "aud": "kubernetes", "exp": 1703232949, "hd": "example.com", "iat": 1701113101, "iss": "https://example.com", "jti": "b5b0652372cd20e345b6fdffcdc2181f4afd6f259aab4b7e35881237d29220bc", "nbf": 1701113101, "roles": "user,admin", "sub": "auth", "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db4a", "username": "foo" } ``` The token with the above `AuthenticationConfiguration` will produce the following `UserInfo` object: ```json { "username": "system:foo", "uid": "auth", "groups": [ "user", "admin" ], "extra": { "example.com/tenant": ["72f988bf-86f1-41af-91ab-2d7cd011db4a"] } } ``` which will fail user validation because the username starts with `system:`. The API server will return `401 Unauthorized` error. {{% /tab %}} {{< /tabs >}} ##### Limitations {#oidc-limitations} 1. Distributed claims do not work via [CEL](/docs/reference/using-api/cel/) expressions. Kubernetes does not provide an OpenID Connect Identity Provider. You can use an existing public OpenID Connect Identity Provider or run your own Identity Provider that supports the OpenID Connect protocol. For an identity provider to work with Kubernetes it must: 1. Support [OpenID connect discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) The public key to verify the signature is discovered from the issuer's public endpoint using OIDC discovery. If you're using the authentication configuration file, the identity provider doesn't need to publicly expose the discovery endpoint. You can host the discovery endpoint at a different location than the issuer (such as locally in the cluster) and specify the `issuer.discoveryURL` in the configuration file. 1. Run in TLS with non-obsolete ciphers 1. Have a CA signed certificate (even if the CA is not a commercial CA or is self signed) A note about requirement #3 above, requiring a CA signed certificate. If you deploy your own identity provider you MUST have your identity provider's web server certificate signed by a certificate with the `CA` flag set to `TRUE`, even if it is self signed. This is due to GoLang's TLS client implementation being very strict to the standards around certificate validation. If you don't have a CA handy, you can create a simple CA and a signed certificate and key pair using standard certificate generation tools. #### Using kubectl ##### Option 1 - OIDC authenticator The first option is to use the kubectl `oidc` authenticator, which sets the `id_token` as a bearer token for all requests and refreshes the token once it expires. After you've logged into your provider, use kubectl to add your `id_token`, `refresh_token`, `client_id`, and `client_secret` to configure the plugin. Providers that don't return an `id_token` as part of their refresh token response aren't supported by this plugin and should use [Option 2](#option-2-use-the-token-option) (specifying `--token`). ```bash kubectl config set-credentials USER_NAME \ --auth-provider=oidc \ --auth-provider-arg=idp-issuer-url=( issuer url ) \ --auth-provider-arg=client-id=( your client id ) \ --auth-provider-arg=client-secret=( your client secret ) \ --auth-provider-arg=refresh-token=( your refresh token ) \ --auth-provider-arg=idp-certificate-authority=( path to your ca certificate ) \ --auth-provider-arg=id-token=( your id_token ) ``` As an example, running the below command after authenticating to your identity provider: ```bash kubectl config set-credentials mmosley \ --auth-provider=oidc \ --auth-provider-arg=idp-issuer-url=https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP \ --auth-provider-arg=client-id=kubernetes \ --auth-provider-arg=client-secret=1db158f6-177d-4d9c-8a8b-d36869918ec5 \ --auth-provider-arg=refresh-token=q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXqHega4GAXlF+ma+vmYpFcHe5eZR+slBFpZKtQA= \ --auth-provider-arg=idp-certificate-authority=/root/ca.pem \ --auth-provider-arg=id-token=eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw ``` Which would produce the below configuration: ```yaml users: - name: mmosley user: auth-provider: config: client-id: kubernetes client-secret: 1db158f6-177d-4d9c-8a8b-d36869918ec5 id-token: eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw idp-certificate-authority: /root/ca.pem idp-issuer-url: https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP refresh-token: q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXq name: oidc ``` Once your `id_token` expires, `kubectl` will attempt to refresh your `id_token` using your `refresh_token` and `client_secret` storing the new values for the `refresh_token` and `id_token` in your `.kube/config`. ##### Option 2 - Use the `--token` command line argument {#option-2-use-the-token-option} The `kubectl` command lets you pass in a token using the `--token` command line argument. Copy and paste the `id_token` into this option: ```bash kubectl --token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL21sYi50cmVtb2xvLmxhbjo4MDQzL2F1dGgvaWRwL29pZGMiLCJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNDc0NTk2NjY5LCJqdGkiOiI2RDUzNXoxUEpFNjJOR3QxaWVyYm9RIiwiaWF0IjoxNDc0NTk2MzY5LCJuYmYiOjE0NzQ1OTYyNDksInN1YiI6Im13aW5kdSIsInVzZXJfcm9sZSI6WyJ1c2VycyIsIm5ldy1uYW1lc3BhY2Utdmlld2VyIl0sImVtYWlsIjoibXdpbmR1QG5vbW9yZWplZGkuY29tIn0.f2As579n9VNoaKzoF-dOQGmXkFKf1FMyNV0-va_B63jn-_n9LGSCca_6IVMP8pO-Zb4KvRqGyTP0r3HkHxYy5c81AnIh8ijarruczl-TK_yF5akjSTHFZD-0gRzlevBDiH8Q79NAr-ky0P4iIXS8lY9Vnjch5MF74Zx0c3alKJHJUnnpjIACByfF2SCaYzbWFMUNat-K1PaUk5-ujMBG7yYnr95xD-63n8CO8teGUAAEMx6zRjzfhnhbzX-ajwZLGwGUBT4WqjMs70-6a7_8gZmLZb2az1cZynkFRj2BaCkVT3A2RrjeEwZEtGXlMqKJ1_I2ulrOVsYx01_yD35-rw get nodes ``` ### Webhook token authentication Kubernetes _webhook authentication_ is a mechanism to make an HTTP callout for verifying bearer tokens. In terms of how you configure the API server: * `--authentication-token-webhook-config-file` a configuration file describing how to access the remote webhook service. * `--authentication-token-webhook-cache-ttl` how long to cache authentication decisions. Defaults to two minutes. * `--authentication-token-webhook-version` determines whether to use `authentication.k8s.io/v1beta1` or `authentication.k8s.io/v1` `TokenReview` objects to send/receive information from the webhook. Defaults to `v1beta1`. The configuration file uses the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file format. Within the file, `clusters` refers to the remote service and `users` refers to the API server webhook. An example would be: ```yaml # Kubernetes API version apiVersion: v1 # kind of the API object kind: Config # clusters refers to the remote service. clusters: - name: name-of-remote-authn-service cluster: certificate-authority: /path/to/ca.pem # CA for verifying the remote service. server: https://authn.example.com/authenticate # URL of remote service to query. 'https' recommended for production. # users refers to the API server's webhook configuration. users: - name: name-of-api-server user: client-certificate: /path/to/cert.pem # cert for the webhook plugin to use client-key: /path/to/key.pem # key matching the cert # kubeconfig files require a context. Provide one for the API server. current-context: webhook contexts: - context: cluster: name-of-remote-authn-service user: name-of-api-server name: webhook ``` When a client attempts to authenticate with the API server using a bearer token as discussed [above](#putting-a-bearer-token-in-a-request), the authentication webhook POSTs a JSON-serialized `TokenReview` object containing the token to the remote service. Note that webhook API objects are subject to the same [versioning compatibility rules](/docs/concepts/overview/kubernetes-api/) as other Kubernetes API objects. Implementers should check the `apiVersion` field of the request to ensure correct deserialization, and **must** respond with a `TokenReview` object of the same version as the request. {{< tabs name="TokenReview_request" >}} {{% tab name="authentication.k8s.io/v1" %}} {{< note >}} The Kubernetes API server defaults to sending `authentication.k8s.io/v1beta1` token reviews for backwards compatibility. To opt into receiving `authentication.k8s.io/v1` token reviews, the API server must be started with `--authentication-token-webhook-version=v1`. {{< /note >}} ```yaml { "apiVersion": "authentication.k8s.io/v1", "kind": "TokenReview", "spec": { # Opaque bearer token sent to the API server "token": "014fbff9a07c...", # Optional list of the audience identifiers for the server the token was presented to. # Audience-aware token authenticators (for example, OIDC token authenticators) # should verify the token was intended for at least one of the audiences in this list, # and return the intersection of this list and the valid audiences for the token in the response status. # This ensures the token is valid to authenticate to the server it was presented to. # If no audiences are provided, the token should be validated to authenticate to the Kubernetes API server. "audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"] } } ``` {{% /tab %}} {{% tab name="authentication.k8s.io/v1beta1" %}} ```yaml { "apiVersion": "authentication.k8s.io/v1beta1", "kind": "TokenReview", "spec": { # Opaque bearer token sent to the API server "token": "014fbff9a07c...", # Optional list of the audience identifiers for the server the token was presented to. # Audience-aware token authenticators (for example, OIDC token authenticators) # should verify the token was intended for at least one of the audiences in this list, # and return the intersection of this list and the valid audiences for the token in the response status. # This ensures the token is valid to authenticate to the server it was presented to. # If no audiences are provided, the token should be validated to authenticate to the Kubernetes API server. "audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"] } } ``` {{% /tab %}} {{< /tabs >}} The remote service is expected to fill the `status` field of the request to indicate the success of the login. The response body's `spec` field is ignored and may be omitted. The remote service must return a response using the same `TokenReview` API version that it received. A successful validation of the bearer token would return: {{< tabs name="TokenReview_response_success" >}} {{% tab name="authentication.k8s.io/v1" %}} ```yaml { "apiVersion": "authentication.k8s.io/v1", "kind": "TokenReview", "status": { "authenticated": true, "user": { # Required "username": "janedoe@example.com", # Optional "uid": "42", # Optional group memberships "groups": ["developers", "qa"], # Optional additional information provided by the authenticator. # This should not contain confidential data, as it can be recorded in logs # or API objects, and is made available to admission webhooks. "extra": { "extrafield1": [ "extravalue1", "extravalue2" ] } }, # Optional list audience-aware token authenticators can return, # containing the audiences from the `spec.audiences` list for which the provided token was valid. # If this is omitted, the token is considered to be valid to authenticate to the Kubernetes API server. "audiences": ["https://myserver.example.com"] } } ``` {{% /tab %}} {{% tab name="authentication.k8s.io/v1beta1" %}} ```yaml { "apiVersion": "authentication.k8s.io/v1beta1", "kind": "TokenReview", "status": { "authenticated": true, "user": { # Required "username": "janedoe@example.com", # Optional "uid": "42", # Optional group memberships "groups": ["developers", "qa"], # Optional additional information provided by the authenticator. # This should not contain confidential data, as it can be recorded in logs # or API objects, and is made available to admission webhooks. "extra": { "extrafield1": [ "extravalue1", "extravalue2" ] } }, # Optional list audience-aware token authenticators can return, # containing the audiences from the `spec.audiences` list for which the provided token was valid. # If this is omitted, the token is considered to be valid to authenticate to the Kubernetes API server. "audiences": ["https://myserver.example.com"] } } ``` {{% /tab %}} {{< /tabs >}} An unsuccessful request would return: {{< tabs name="TokenReview_response_error" >}} {{% tab name="authentication.k8s.io/v1" %}} ```yaml { "apiVersion": "authentication.k8s.io/v1", "kind": "TokenReview", "status": { "authenticated": false, # Optionally include details about why authentication failed. # If no error is provided, the API will return a generic Unauthorized message. # The error field is ignored when authenticated=true. "error": "Credentials are expired" } } ``` {{% /tab %}} {{% tab name="authentication.k8s.io/v1beta1" %}} ```yaml { "apiVersion": "authentication.k8s.io/v1beta1", "kind": "TokenReview", "status": { "authenticated": false, # Optionally include details about why authentication failed. # If no error is provided, the API will return a generic Unauthorized message. # The error field is ignored when authenticated=true. "error": "Credentials are expired" } } ``` {{% /tab %}} {{< /tabs >}} ### Authenticating reverse proxy {#authenticating-proxy} {{< warning >}} If you have a certificate authority (CA) that is also used in a different context, **do not** trust that certificate authority to identify authenticating proxy clients, unless you understand the risks and the mechanisms to protect that CA's usage. {{< /warning >}} The API server can be configured to identify users from request header values, such as `X-Remote-User`. It is designed for use in combination with an _authenticating proxy_ that sets these headers. Using an authenticating reverse proxy is different from [user impersonation](/docs/reference/access-authn-authz/user-impersonation/). With user impersonation, one user requests the API server to treat the request as if it were being made by a different user. With an authenticating reverse proxy, the API server trusts its direct client to provide information about the identity of the principal making the original request. See [web request header configuration](#api-server-authn-config-cli-reverse-proxy) to learn about configuring this using command line arguments. #### Example {#authenticating-proxy-example} For example, with this configuration: ``` --requestheader-username-headers=X-Remote-User --requestheader-group-headers=X-Remote-Group --requestheader-extra-headers-prefix=X-Remote-Extra- ``` this request: ```http GET / HTTP/1.1 X-Remote-User: fido X-Remote-Group: dogs X-Remote-Group: dachshunds X-Remote-Extra-Acme.com%2Fproject: some-project X-Remote-Extra-Scopes: openid X-Remote-Extra-Scopes: profile ``` would result in this user info: ```yaml name: fido groups: - dogs - dachshunds extra: acme.com/project: - some-project scopes: - openid - profile ``` #### Client certificate {#reverse-proxy-client-certificate} In order to prevent header spoofing, the authenticating proxy is required to present a valid client certificate to the API server for validation against the specified CA before the request headers are checked. See the [command line option](#api-server-authn-config-cli-reverse-proxy) reference for request header authentication mode. Do **not** reuse a CA that is used in a different context unless you understand the risks and the mechanisms to protect the CA's usage. ### Static token file integration {#static-token-file} The API server reads static bearer tokens from a file when given the `--token-auth-file=` option on the command line. In Kubernetes {{< skew currentVersion >}}, tokens last indefinitely, and the token list cannot be changed without restarting the API server. The token file is a CSV file with a minimum of 3 columns: token, user name, user uid, followed by a comma-separated list of optional group names. {{< note >}} If you have more than one group, the column must be double quoted e.g. ```conf token,user,uid,"group1,group2,group3" ``` {{< /note >}} Using a static token file is appropriate for tokens that by their nature are long-lived, static, and perhaps may never be rotated. It is also useful when the client is local to a particular API server within the control plane, such as a monitoring agent. If you use this method during cluster provisioning, and then transition to a different authentication method that will be used longer term, you should deactivate the token that was used for bootstrapping (this requires a restart of each API server. For other circumstances, and especially where very prompt token rotation is important, the Kubernetes project recommends using a [webhook token authenticator](#webhook-token-authentication) instead of this mechanism. ## User impersonation [User impersonation](/docs/reference/access-authn-authz/user-impersonation/) provides a method that a user can act as another user through impersonation headers ## Authentication configuration {#api-server-authn-config} You can configure Kubernetes authentication either using [command line arguments](#api-server-authn-config-cli), or using a [configuration file](#api-server-authn-config-file). Typically, you use a mix of these approaches. ### Configuration via command line arguments {#api-server-authn-config-cli} You can use the following command line arguments to configure how your cluster's control plane authenticates clients. The [command line reference](/docs/reference/command-line-tools-reference/kube-apiserver/) for the API server describes all of the relevant command line arguments in more detail. #### Anonymous authentication configuration {#api-server-authn-config-cli-anonymous} `--anonymous-auth` : Controls whether clients who have not authenticated can make request via the API server's secure port. Anonymous requests have a username of `system:anonymous`, and a group name of `system:unauthenticated`. Also see [anonymous requests](#anonymous-requests). #### Bootstrap token configuration {#api-server-authn-config-cli-bootstrap} `--enable-bootstrap-token-auth` : When this flag is set, you can use [bootstrap tokens](#bootstrap-tokens) to authenticate. #### Certificate authentication configuration {#api-server-authn-config-cli-x-509} `--client-ca-file` : The path to the trust anchor(s) for validating client identity, when clients use X.509 certificate authentication. #### OIDC configuration {#api-server-authn-config-cli-oidc} `--oidc-ca-file` : The path to the trust anchor(s) for validating client identity, when clients use OIDC. `--oidc-client-id` : The client ID for the OpenID Connect client. `--oidc-username-claim` : The name of a JWT claim for specifying the username. claim to use as the user name. Default claim name is `sub`, as this should be a unique identifier of the end user. You can choose other claims, such as `email` or `name`. For claims other than `sub` or `email`, the kube-apiserver adds a prefix to the group name (to prevent naming clashes). `--oidc-username-prefix` : Prefix prepended to username claims to prevent clashes with existing names (such as `system:` users). For example, the value `oidc:` will create usernames like `oidc:jane.doe`. If this argument isn't provided and `--oidc-username-claim` is a value other than `email` the prefix defaults to `( Issuer URL )#` where `( Issuer URL )` is the value of `--oidc-issuer-url`. You can specify the prefix value as `-` to disable username prefixing. `--oidc-groups-claim` : The name of a custom OpenID Connect claim for specifying user groups. The claim in the token must be an array of strings. No default. `--oidc-groups-prefix` : Prefix prepended to group claims to prevent clashes with existing names (such as `system:` groups). For example, the value `oidc:` will create group names like `oidc:engineering` and `oidc:infra`. The default prefix is `oidc:` `--oidc-issuer-url` : The URL of the OpenID issuer. The URL scheme **must** be `https`. If the issuer's OIDC discovery URL is `https://accounts.provider.example/.well-known/openid-configuration`, the value should be `https://accounts.provider.example`. `--oidc-required-claim` : A claim that must be present in a token before Kubernetes authenticates a client. Format is `key=value`. You can specify this argument more than once. `--oidc-signing-algs` : The signing algorithms accepted. Allowed values are: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Values are defined by [RFC 7518](https://tools.ietf.org/html/rfc7518#section-3.1). Default is `RS512`. #### ServiceAccount configuration {#api-server-authn-config-cli-sa} `--api-audiences` : Defines the authentication audience for service account tokens. `--service-account-extend-token-expiration` : This flag turns on projected service account expiration extension during token generation, which helps safe transition from legacy tokens to bound service account token feature. See [authenticating service account credentials](/docs/concepts/security/service-accounts/#authenticating-credentials). `--service-account-issuer` : Identifier of the service account token issuer. The issuer asserts this identifier in `iss` claim of each issued token. The Kubernetes project recommends using a URL here, with the scheme set to `https`. `--service-account-jwks-uri` : Overrides the URI for the [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517) in the discovery document that is served at `/.well-known/openid-configuration` `--service-account-key-file` : Path to a file containing PEM-encoded X.509 public or private keys (RSA or ECDSA), used to verify ServiceAccount tokens. The specified file can contain multiple keys, and you can specify the argument multiple times with different paths. `--service-account-lookup` : If true, the API server validates that ServiceAccount tokens exist in etcd as part of authentication. `--service-account-max-token-expiration` : The maximum validity duration of a token created by the service account token issuer, as a Kubernetes duration string. `--service-account-signing-endpoint` : Path to socket where an external JWT signer is listening. You can use this to integrate with an external token signer. `--service-account-signing-key-file` : Path to the file that contains the current private key of the service account token issuer. Changes made to this file while the API server is running are **not** re-read. #### Static token configuration {#api-server-authn-config-cli-bearer} `--token-auth-file` : Path to the configuration file for [static bearer tokens](#static-token-file). Changes made to this file while the API server is running are **not** re-read. #### Webhook authentication configuration {#api-server-authn-config-cli-webhook} `--authentication-token-webhook-cache-ttl` : How long (as a Kubernetes duration specification) the API server should cache the outcome of HTTP callouts to validate tokens. `--authentication-token-webhook-config-file` : The path to a kubeconfig format client configuration, that specifies how the API server authenticates when making HTTP callouts. Changes made to this file while the API server is running are **not** re-read. `--authentication-token-webhook-version` : The API version of TokenReview to use when making HTTP callouts to check tokens. #### Web request authentication configuration {#api-server-authn-config-cli-reverse-proxy} {{< caution >}} You should read the documentation about configuring an [authenticating proxy](#authenticating-proxy) before you specify these command line arguments, as there is important information security advice that you must follow. {{< /caution >}} `--requestheader-client-ca-file` : _Required._ Path to a PEM-encoded certificate bundle containing trust anchor(s) for validating authenticating proxy identity. A valid [client certificate](#reverse-proxy-client-certificate) must be presented and validated against the certificate authorities in the specified file before the request headers are checked for user names. `--requestheader-allowed-names` : _Optional._ Comma-separated list of Common Name values (CNs). If set, a valid client certificate with a CN in the specified list must be presented before the request headers are checked for user names. If empty, any CN is allowed. `--requestheader-username-headers` : _Required; case-insensitive._ Header names to check, in order, for the user identity. The first header containing a value is used as the username. `--requestheader-group-headers` : _Optional; case-insensitive._ Header names to check, in order, for the user's groups. `X-Remote-Group` is suggested. All values in all specified headers are used as group names. `--requestheader-extra-headers-prefix` : _Optional; case-insensitive._ Header prefixes to look for to determine extra information about the user. `X-Remote-Extra-` is suggested. Extra data is typically used by the configured authorization plugin(s). Any headers beginning with any of the specified prefixes have the prefix removed. The remainder of the header name is lowercased and [percent-decoded](https://tools.ietf.org/html/rfc3986#section-2.1) and becomes the extra key, and the header value is the extra value. ### Configuration via configuration file {#api-server-authn-config-file} {{< feature-state feature_gate_name="StructuredAuthenticationConfiguration" >}} When you specify the `--authentication-config` command line argument to the kube-apiserver, the API server loads a file at the path you specify, and uses the contents of that file to configure authentication. The contents of that file can be changed while the API server is running and, if you do that, the API server re-reads the file afterwards. {{< note >}} Modifications to this file should be done in an atomic way (for example: writing to a peer temporary file, then renaming the temporary file to replace this file). {{< /note >}} #### Configuration file path {#api-server-authn-config-cli-general} `--authentication-config` : This special command line argument specifies that you want to [configure authentication using a configuration file](#api-server-authn-config-file). #### Example {#api-server-authn-config-file-example} Here is an example of a Kubernetes (structured) authentication configuration file: {{< highlight yaml "linenos=false,hl_lines=2-5" >}} --- # # CAUTION: this is an example configuration. # Check and amend this before you use it in your own cluster! # apiVersion: apiserver.config.k8s.io/v1 kind: AuthenticationConfiguration anonymous: enabled: false {{< /highlight >}} ## client-go credential plugins {{< feature-state for_k8s_version="v1.22" state="stable" >}} `k8s.io/client-go` and tools using it such as `kubectl` and `kubelet` are able to execute an external command to receive user credentials. This feature is intended for client side integrations with authentication protocols not natively supported by `k8s.io/client-go` (LDAP, Kerberos, OAuth2, SAML, etc.). The plugin implements the protocol specific logic, then returns opaque credentials to use. Almost all credential plugin use cases require a server side component with support for the [webhook token authenticator](#webhook-token-authentication) to interpret the credential format produced by the client plugin. {{< note >}} Earlier versions of `kubectl` included built-in support for authenticating to AKS and GKE, but this is no longer present. {{< /note >}} ### Example use case In a hypothetical use case, an organization would run an external service that exchanges LDAP credentials for user specific, signed tokens. The service would also be capable of responding to [webhook token authenticator](#webhook-token-authentication) requests to validate the tokens. Users would be required to install a credential plugin on their workstation. To authenticate against the API: * The user issues a `kubectl` command. * Credential plugin prompts the user for LDAP credentials, exchanges credentials with external service for a token. * Credential plugin returns token to client-go, which uses it as a bearer token against the API server. * API server uses the [webhook token authenticator](#webhook-token-authentication) to submit a `TokenReview` to the external service. * External service verifies the signature on the token and returns the user's username and groups. ### Configuration Credential plugins are configured through [kubectl config files](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) as part of the user fields. {{< tabs name="exec_plugin_kubeconfig_example_1" >}} {{% tab name="client.authentication.k8s.io/v1" %}} ```yaml apiVersion: v1 kind: Config users: - name: my-user user: exec: # Command to execute. Required. command: "example-client-go-exec-plugin" # API version to use when decoding the ExecCredentials resource. Required. # # The API version returned by the plugin MUST match the version listed here. # # To integrate with tools that support multiple versions (such as client.authentication.k8s.io/v1beta1), # set an environment variable, pass an argument to the tool that indicates which version the exec plugin expects, # or read the version from the ExecCredential object in the KUBERNETES_EXEC_INFO environment variable. apiVersion: "client.authentication.k8s.io/v1" # Environment variables to set when executing the plugin. Optional. env: - name: "FOO" value: "bar" # Arguments to pass when executing the plugin. Optional. args: - "arg1" - "arg2" # Text shown to the user when the executable doesn't seem to be present. Optional. installHint: | example-client-go-exec-plugin is required to authenticate to the current cluster. It can be installed: On macOS: brew install example-client-go-exec-plugin On Ubuntu: apt-get install example-client-go-exec-plugin On Fedora: dnf install example-client-go-exec-plugin ... # Whether or not to provide cluster information, which could potentially contain # very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO # environment variable. provideClusterInfo: true # The contract between the exec plugin and the standard input I/O stream. If the # contract cannot be satisfied, this plugin will not be run and an error will be # returned. Valid values are "Never" (this exec plugin never uses standard input), # "IfAvailable" (this exec plugin wants to use standard input if it is available), # or "Always" (this exec plugin requires standard input to function). Required. interactiveMode: Never clusters: - name: my-cluster cluster: server: "https://172.17.4.100:6443" certificate-authority: "/etc/kubernetes/ca.pem" extensions: - name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config extension: arbitrary: config this: can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo you: ["can", "put", "anything", "here"] contexts: - name: my-cluster context: cluster: my-cluster user: my-user current-context: my-cluster ``` {{% /tab %}} {{% tab name="client.authentication.k8s.io/v1beta1" %}} ```yaml apiVersion: v1 kind: Config users: - name: my-user user: exec: # Command to execute. Required. command: "example-client-go-exec-plugin" # API version to use when decoding the ExecCredentials resource. Required. # # The API version returned by the plugin MUST match the version listed here. # # To integrate with tools that support multiple versions (such as client.authentication.k8s.io/v1), # set an environment variable, pass an argument to the tool that indicates which version the exec plugin expects, # or read the version from the ExecCredential object in the KUBERNETES_EXEC_INFO environment variable. apiVersion: "client.authentication.k8s.io/v1beta1" # Environment variables to set when executing the plugin. Optional. env: - name: "FOO" value: "bar" # Arguments to pass when executing the plugin. Optional. args: - "arg1" - "arg2" # Text shown to the user when the executable doesn't seem to be present. Optional. installHint: | example-client-go-exec-plugin is required to authenticate to the current cluster. It can be installed: On macOS: brew install example-client-go-exec-plugin On Ubuntu: apt-get install example-client-go-exec-plugin On Fedora: dnf install example-client-go-exec-plugin ... # Whether or not to provide cluster information, which could potentially contain # very large CA data, to this exec plugin as a part of the KUBERNETES_EXEC_INFO # environment variable. provideClusterInfo: true # The contract between the exec plugin and the standard input I/O stream. If the # contract cannot be satisfied, this plugin will not be run and an error will be # returned. Valid values are "Never" (this exec plugin never uses standard input), # "IfAvailable" (this exec plugin wants to use standard input if it is available), # or "Always" (this exec plugin requires standard input to function). Optional. # Defaults to "IfAvailable". interactiveMode: Never clusters: - name: my-cluster cluster: server: "https://172.17.4.100:6443" certificate-authority: "/etc/kubernetes/ca.pem" extensions: - name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config extension: arbitrary: config this: can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo you: ["can", "put", "anything", "here"] contexts: - name: my-cluster context: cluster: my-cluster user: my-user current-context: my-cluster ``` {{% /tab %}} {{< /tabs >}} Relative command paths are interpreted as relative to the directory of the config file. If KUBECONFIG is set to `/home/jane/kubeconfig` and the exec command is `./bin/example-client-go-exec-plugin`, the binary `/home/jane/bin/example-client-go-exec-plugin` is executed. ```yaml - name: my-user user: exec: # Path relative to the directory of the kubeconfig command: "./bin/example-client-go-exec-plugin" apiVersion: "client.authentication.k8s.io/v1" interactiveMode: Never ``` ### Input and output formats The executed command prints an `ExecCredential` object to `stdout`. `k8s.io/client-go` authenticates against the Kubernetes API using the returned credentials in the `status`. The executed command is passed an `ExecCredential` object as input via the `KUBERNETES_EXEC_INFO` environment variable. This input contains helpful information like the expected API version of the returned `ExecCredential` object and whether or not the plugin can use `stdin` to interact with the user. When run from an interactive session (i.e., a terminal), `stdin` can be exposed directly to the plugin. Plugins should use the `spec.interactive` field of the input `ExecCredential` object from the `KUBERNETES_EXEC_INFO` environment variable in order to determine if `stdin` has been provided. A plugin's `stdin` requirements (i.e., whether `stdin` is optional, strictly required, or never used in order for the plugin to run successfully) is declared via the `user.exec.interactiveMode` field in the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) (see table below for valid values). The `user.exec.interactiveMode` field is optional in `client.authentication.k8s.io/v1beta1` and required in `client.authentication.k8s.io/v1`. {{< table caption="interactiveMode values" >}} | `interactiveMode` Value | Meaning | | ----------------------- | ------- | | `Never` | This exec plugin never needs to use standard input, and therefore the exec plugin will be run regardless of whether standard input is available for user input. | | `IfAvailable` | This exec plugin would like to use standard input if it is available, but can still operate if standard input is not available. Therefore, the exec plugin will be run regardless of whether stdin is available for user input. If standard input is available for user input, then it will be provided to this exec plugin. | | `Always` | This exec plugin requires standard input in order to run, and therefore the exec plugin will only be run if standard input is available for user input. If standard input is not available for user input, then the exec plugin will not be run and an error will be returned by the exec plugin runner. | {{< /table >}} To use bearer token credentials, the plugin returns a token in the status of the [`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential) {{< tabs name="exec_plugin_ExecCredential_example_1" >}} {{% tab name="client.authentication.k8s.io/v1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1", "kind": "ExecCredential", "status": { "token": "my-bearer-token" } } ``` {{% /tab %}} {{% tab name="client.authentication.k8s.io/v1beta1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1beta1", "kind": "ExecCredential", "status": { "token": "my-bearer-token" } } ``` {{% /tab %}} {{< /tabs >}} Alternatively, a PEM-encoded client certificate and key can be returned to use TLS client auth. If the plugin returns a different certificate and key on a subsequent call, `k8s.io/client-go` will close existing connections with the server to force a new TLS handshake. If specified, `clientKeyData` and `clientCertificateData` must both must be present. `clientCertificateData` may contain additional intermediate certificates to send to the server. {{< tabs name="exec_plugin_ExecCredential_example_2" >}} {{% tab name="client.authentication.k8s.io/v1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1", "kind": "ExecCredential", "status": { "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" } } ``` {{% /tab %}} {{% tab name="client.authentication.k8s.io/v1beta1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1beta1", "kind": "ExecCredential", "status": { "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" } } ``` {{% /tab %}} {{< /tabs >}} Optionally, the response can include the expiry of the credential formatted as a [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp. Presence or absence of an expiry has the following impact: - If an expiry is included, the bearer token and TLS credentials are cached until the expiry time is reached, or if the server responds with a 401 HTTP status code, or when the process exits. - If an expiry is omitted, the bearer token and TLS credentials are cached until the server responds with a 401 HTTP status code or until the process exits. {{< tabs name="exec_plugin_ExecCredential_example_3" >}} {{% tab name="client.authentication.k8s.io/v1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1", "kind": "ExecCredential", "status": { "token": "my-bearer-token", "expirationTimestamp": "2018-03-05T17:30:20-08:00" } } ``` {{% /tab %}} {{% tab name="client.authentication.k8s.io/v1beta1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1beta1", "kind": "ExecCredential", "status": { "token": "my-bearer-token", "expirationTimestamp": "2018-03-05T17:30:20-08:00" } } ``` {{% /tab %}} {{< /tabs >}} To enable the exec plugin to obtain cluster-specific information, set `provideClusterInfo` on the `user.exec` field in the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/). The plugin will then be supplied this cluster-specific information in the `KUBERNETES_EXEC_INFO` environment variable. Information from this environment variable can be used to perform cluster-specific credential acquisition logic. The following `ExecCredential` manifest describes a cluster information sample. {{< tabs name="exec_plugin_ExecCredential_example_4" >}} {{% tab name="client.authentication.k8s.io/v1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1", "kind": "ExecCredential", "spec": { "cluster": { "server": "https://172.17.4.100:6443", "certificate-authority-data": "LS0t...", "config": { "arbitrary": "config", "this": "can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo", "you": ["can", "put", "anything", "here"] } }, "interactive": true } } ``` {{% /tab %}} {{% tab name="client.authentication.k8s.io/v1beta1" %}} ```json { "apiVersion": "client.authentication.k8s.io/v1beta1", "kind": "ExecCredential", "spec": { "cluster": { "server": "https://172.17.4.100:6443", "certificate-authority-data": "LS0t...", "config": { "arbitrary": "config", "this": "can be provided via the KUBERNETES_EXEC_INFO environment variable upon setting provideClusterInfo", "you": ["can", "put", "anything", "here"] } }, "interactive": true } } ``` {{% /tab %}} {{< /tabs >}} ## API access to authentication information for a client {#self-subject-review} {{< feature-state for_k8s_version="v1.28" state="stable" >}} You can use the SelfSubjectReview API to find out how your Kubernetes cluster maps your authentication information to identify you as a client. This works whether you are authenticating as a user (typically representing a real person) or as a ServiceAccount. In a typical Kubernetes cluster, all authenticated users can create SelfSubjectReviews. Access to do this is allowed by the built-in `system:basic-user` [ClusterRole](/docs/reference/access-authn-authz/rbac/#role-and-clusterrole). The ability for a client to learn its own identity is extremely useful when troubleshooting a complicated authentication flow that is used in a Kubernetes cluster; for example, if you use [webhook token authentication](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) or an [authenticating proxy](/docs/reference/access-authn-authz/authentication/#authenticating-proxy). If you want to query this on the command line, see [CLI access to authentication information](#self-subject-review-cli). ### HTTP access to authentication information {#self-subject-review-http-api} SelfSubjectReviews do not have any configurable fields. On receiving a request, the Kubernetes API server fills the status with the user attributes and returns it to the user. This does **not** persist a named resource into your cluster: you cannot fetch the SelfSubjectReview, and it is discarded once your `POST` request has completed. Request example (the body would be a SelfSubjectReview): ```http POST /apis/authentication.k8s.io/v1/selfsubjectreviews ``` ```json { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview" } ``` Response example: ```json { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview", "status": { "userInfo": { "username": "janedoe@example.com", "groups": [ "viewers", "editors", "system:authenticated" ] } } } ``` {{< note >}} The Kubernetes API server fills `userInfo` after all authentication mechanisms are applied, including [impersonation](/docs/reference/access-authn-authz/authentication/#user-impersonation). If you, or an authentication proxy, make a SelfSubjectReview using impersonation, you see the user details and properties for the user that was impersonated. {{< /note >}} This example response did not show all the available fields; not all authentication mechanisms fill in every available field. See the [SelfSubjectReview API reference](/docs/reference/kubernetes-api/authentication-resources/self-subject-review-v1/) to see which fields are available. Here is another example that also includes the `uid` and `extra` fields: ```yaml { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview", "status": { "userInfo": { "username": "janedoe@example.com", "groups": [ "viewers", "editors", "system:authenticated" ], "uid": "000042", "extra": { "firstName": [ "Jane" ], "familyName": [ "Doe" ], "projectAssignments": [ "web-frontend", "ai-training-proof-of-concept" ], } } } } ``` The data in these optional fields come from your authentication integration or from the user database that it uses. The username, UID, extra information, and all groups with names that don't start `system:` are all sourced from outside of Kubernetes. When querying the Kubernetes API via HTTP, you can request a response in either JSON or YAML using the `Accept:` HTTP header; for example: {{< tabs name="self_subject_attributes_review_Example_1" >}} {{% tab name="JSON" %}} ```http POST /apis/authentication.k8s.io/v1/selfsubjectreviews HTTP/1.1 Accept: application/json;q=1.0 Content-Type: application/json …other request headers { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview" } ``` --- ```json { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview", "status": { "userInfo": { "username": "jane.doe", "uid": "b79dbf30-0c6a-11ed-861d-0242ac120002", "groups": [ "students", "teachers", "system:authenticated" ], "extra": { "skills": [ "reading", "learning" ], "subjects": [ "math", "sports" ] } } } } ``` {{% /tab %}} {{% tab name="YAML" %}} ```http POST /apis/authentication.k8s.io/v1/selfsubjectreviews HTTP/1.1 Accept: application/yaml;q=1.0 Content-Type: application/json …other request headers { "apiVersion": "authentication.k8s.io/v1", "kind": "SelfSubjectReview" } ``` --- ```yaml apiVersion: authentication.k8s.io/v1 kind: SelfSubjectReview status: userInfo: username: jane.doe uid: b79dbf30-0c6a-11ed-861d-0242ac120002 groups: - students - teachers - system:authenticated extra: skills: - reading - learning subjects: - math - sports ``` {{% /tab %}} {{< /tabs >}} ### CLI access to authentication information {#self-subject-review-cli} For convenience, the `kubectl auth whoami` subcommand is also available: ```shell kubectl auth whoami ``` The output is similar to: ```console ATTRIBUTE VALUE Username george.boole Groups [system:authenticated] ``` See [`kubectl auth whoami`](/docs/reference/kubectl/generated/kubectl_auth/kubectl_auth_whoami/) for more details. ## {{% heading "whatsnext" %}} * To learn about issuing certificates for users, read [Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest](/docs/tasks/tls/certificate-issue-client-csr/) * Read the [client authentication reference (v1)](/docs/reference/config-api/client-authentication.v1/) * Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)