# Authenticating

AuthenticatingThis page provides an overview of authentication in Kubernetes, with a focus on authentication to the Kubernetes API.Users in KubernetesAll 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 keysa user store like Keystone or Google Accountsa file with a list of usernames and passwordsIn 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. 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.Authentication strategiesKubernetes 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.Authentication methodsYou can enable multiple authentication methods at once. You should usually use at least two methods:service account tokens for service accountsat least one other method for user authentication.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.The system:authenticated group is included in the list of groups for all authenticated users.Integrations with other authentication protocols (LDAP, SAML, Kerberos, alternate x509 schemes, etc) are available; for example using an authenticating proxy or the authentication webhook.X.509 client certificatesClient certificate authentication is enabled by passing the --client-ca-file=SOMEFILE option to API server. The referenced file must contain one or more certificate authorities to use to validate client certificates presented to the API server. If a client certificate is presented and verified, the common name of the subject is used as the user name for the request. As of Kubernetes 1.4, 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.For example, using the openssl command line tool to generate a certificate signing request:openssl req -new -key jbeda.pem -out jbeda-csr.pem -subj "/CN=jbeda/O=app1/O=app2" This would create a CSR for the username "jbeda", belonging to two groups, "app1" and "app2".See Managing Certificates for how to generate a client cert.Putting a bearer token in a requestWhen using bearer token authentication from an http client, the API server expects an Authorization header with a value of Bearer <token>. 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.Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269 Bootstrap tokensFEATURE STATE: Kubernetes v1.18 [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: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:<Token ID>. 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 for in depth documentation on the Bootstrap Token authenticator and controllers along with how to manage these tokens with kubeadm.Service account tokensA 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. 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.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.kubectl create serviceaccount jenkins serviceaccount/jenkins created You can manually create an associated token:kubectl create token jenkins eyJhbGciOiJSUzI1NiIsImtp... The created token is a signed JSON Web Token (JWT).The signed JWT can be used as a bearer token to authenticate as the given service account. See above 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.External integrationsKubernetes has native support for OpenID Connect (OIDC); see OpenID Connect tokens.Integrations with other authentication protocols (for example: LDAP, SAML, Kerberos, alternate X.509 schemes) can be accomplished using an authenticating proxy or by integrating with an authentication webhook.You can also use any custom method that issues client X.509 certificates to clients, provided that the API server will trust the valid certificates. Read X.509 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.OpenID Connect tokensOpenID 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. 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 as a bearer token. See above for how the token is included in a request.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 kubectlwith --token being the id_tokenOR 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: Performaction and return result deactivate api activate kube kube --x user: 9. Return result deactivate kubeJavaScript must be enabled to view this contentLog in to your identity providerYour identity provider will provide you with an access_token, id_token and a refresh_tokenWhen using kubectl, use your id_token with the --token command line argument or add it directly to your kubeconfigkubectl sends your id_token in a header called Authorization to the API serverThe API server will make sure the JWT signature is validCheck to make sure the id_token hasn't expiredPerform claim and/or user validation if CEL expressions are configured with AuthenticationConfiguration.Make sure the user is authorizedOnce authorized the API server returns a response to kubectlkubectl provides