diff --git a/content/en/docs/concepts/security/service-accounts.md b/content/en/docs/concepts/security/service-accounts.md new file mode 100644 index 0000000000..5a5d973bac --- /dev/null +++ b/content/en/docs/concepts/security/service-accounts.md @@ -0,0 +1,256 @@ +--- +title: Service Accounts +description: > + Learn about the Kubernetes ServiceAccount object. +content_type: concept +weight: 10 +--- + + + +This page introduces the ServiceAccount object in Kubernetes, providing +information about how service accounts work, use cases, limitations, +alternatives, and links to resources for additional guidance. + + + +## What are service accounts? {#what-are-service-accounts} + +A service account is a type of non-human account that, in Kubernetes, provides +a distinct identity in a Kubernetes cluster. Application Pods, system +components, and entities inside and outside the cluster can use a specific +ServiceAccount's credentials to identify as that ServiceAccount. This identity +is useful in various situations, including authenticating to the API server or +implementing identity-based security policies. + +Service accounts exist as ServiceAccount objects in the API server. Service +accounts have the following properties: + +* **Namespaced:** Each service account is bound to a Kubernetes + {{}}. Every namespace + gets a [`default` ServiceAccount](#default-service-accounts) upon creation. + +* **Lightweight:** Service accounts exist in the cluster and are + defined in the Kubernetes API. You can quickly create service accounts to + enable specific tasks. + +* **Portable:** A configuration bundle for a complex containerized workload + might include service account definitions for the system's components. The + lightweight nature of service accounts and the namespaced identities make + the configurations portable. + +Service accounts are different from user accounts, which are authenticated +human users in the cluster. By default, user accounts don't exist in the Kubernetes API server; instead, the API server treats user identities as opaque +data. You can authenticate as a user account using multiple methods. Some +Kubernetes distributions might add custom extension APIs to represent user +accounts in the API server. + +{{< table caption="Comparison between service accounts and users" >}} + +| Description | ServiceAccount | User or group | +| --- | --- | --- | +| Location | Kubernetes API (ServiceAccount object) | External | +| Access control | Kubernetes RBAC or other [authorization mechanisms](/docs/reference/access-authn-authz/authorization/#authorization-modules) | Kubernetes RBAC or other identity and access management mechanisms | +| Intended use | Workloads, automation | People | + +{{< /table >}} + +### Default service accounts {#default-service-accounts} + +When you create a cluster, Kubernetes automatically creates a ServiceAccount +object named `default` for every namespace in your cluster. The `default` +service accounts in each namespace get no permissions by default other than the +[default API discovery permissions](/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings) +that Kubernetes grants to all authenticated principals if role-based access control (RBAC) is enabled. If you delete the +`default` ServiceAccount object in a namespace, the +{{}} +replaces it with a new one. + +If you deploy a Pod in a namespace, and you don't +[manually assign a ServiceAccount to the Pod](#assign-to-pod), Kubernetes +assigns the `default` ServiceAccount for that namespace to the Pod. + +## Use cases for Kubernetes service accounts {#use-cases} + +As a general guideline, you can use service accounts to provide identities in +the following scenarios: + +* Your Pods need to communicate with the Kubernetes API server, for example in + situations such as the following: + * Providing read-only access to sensitive information stored in Secrets. + * Granting [cross-namespace access](#cross-namespace), such as allowing a + Pod in namespace `example` to read, list, and watch for Lease objects in + the `kube-node-lease` namespace. +* Your Pods need to communicate with an external service. For example, a + workload Pod requires an identity for a commercially available cloud API, + and the commercial provider allows configuring a suitable trust relationship. +* [Authenticating to a private image registry using an `imagePullSecret`](/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account). +* An external service needs to communicate with the Kubernetes API server. For + example, authenticating to the cluster as part of a CI/CD pipeline. +* You use third-party security software in your cluster that relies on the + ServiceAccount identity of different Pods to group those Pods into different + contexts. + + +## How to use service accounts {#how-to-use} + +To use a Kubernetes service account, you do the following: + +1. Create a ServiceAccount object using a Kubernetes + client like `kubectl` or a manifest that defines the object. +1. Grant permissions to the ServiceAccount object using an authorization + mechanism such as + [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). +1. Assign the ServiceAccount object to Pods during Pod creation. + + If you're using the identity from an external service, + [retrieve the ServiceAccount token](#get-a-token) and use it from that + service instead. + +For instructions, refer to +[Configure Service Accounts for Pods](/docs/tasks/configure-pod-container/configure-service-account/). + +### Grant permissions to a ServiceAccount {#grant-permissions} + +You can use the built-in Kubernetes +[role-based access control (RBAC)](/docs/reference/access-authn-authz/rbac/) +mechanism to grant the minimum permissions required by each service account. +You create a *role*, which grants access, and then *bind* the role to your +ServiceAccount. RBAC lets you define a minimum set of permissions so that the +service account permissions follow the principle of least privilege. Pods that +use that service account don't get more permissions than are required to +function correctly. + +For instructions, refer to +[ServiceAccount permissions](/docs/reference/access-authn-authz/rbac/#service-account-permissions). + +#### Cross-namespace access using a ServiceAccount {#cross-namespace} + +You can use RBAC to allow service accounts in one namespace to perform actions +on resources in a different namespace in the cluster. For example, consider a +scenario where you have a service account and Pod in the `dev` namespace and +you want your Pod to see Jobs running in the `maintenance` namespace. You could +create a Role object that grants permissions to list Job objects. Then, +you'd create a RoleBinding object in the `maintenance` namespace to bind the +Role to the ServiceAccount object. Now, Pods in the `dev` namespace can list +Job objects in the `maintenance` namespace using that service account. + +### Assign a ServiceAccount to a Pod {#assign-to-pod} + +To assign a ServiceAccount to a Pod, you set the `spec.serviceAccountName` +field in the Pod specification. Kubernetes then automatically provides the +credentials for that ServiceAccount to the Pod. In v1.22 and later, Kubernetes +gets a short-lived, **automatically rotating** token using the `TokenRequest` +API and mounts the token as a +[projected volume](/docs/concepts/storage/projected-volumes/#serviceaccounttoken). + +By default, Kubernetes provides the Pod +with the credentials for an assigned ServiceAccount, whether that is the +`default` ServiceAccount or a custom ServiceAccount that you specify. + +To prevent Kubernetes from automatically injecting +credentials for a specified ServiceAccount or the `default` ServiceAccount, set the +`automountServiceAccountToken` field in your Pod specification to `false`. + + + +In versions earlier than 1.22, Kubernetes provides a long-lived, static token +to the Pod as a Secret. + +#### Manually retrieve ServiceAccount credentials {#get-a-token} + +If you need the credentials for a ServiceAccount to mount in a non-standard +location, or for an audience that isn't the API server, use one of the +following methods: + +* [TokenRequest API](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) + (recommended): Request a short-lived service account token using your + *application code*. The token expires automatically and can rotate upon + expiration. +* [Token Volume Projection](/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection) + (recommended): In Kubernetes v1.20 and later, use the Pod specification to + tell the kubelet to add the service account token to the Pod as a + *projected volume*. Projected tokens expire automatically, and the kubelet + rotates the token before it expires. +* [Service Account Token Secrets](/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-service-account-api-token) + (not recommended): You can mount service account tokens as Kubernetes + Secrets in Pods. These tokens don't expire and don't rotate. This method + is not recommended, especially at scale, because of the risks associated + with static, long-lived credentials. In Kubernetes v1.24 and later, the + [LegacyServiceAccountTokenNoAutoGeneration feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-graduated-or-deprecated-features) + prevents Kubernetes from automatically creating these tokens for + ServiceAccounts. + +## Authenticating service account credentials {#authenticating-credentials} + +ServiceAccounts use signed +{{}} (JWTs) +to authenticate to the Kubernetes API server, and to any other system where a +trust relationship exists. Depending on how the token was issued +(either time-limited using a `TokenRequest` or using a legacy mechanism with +a Secret), a ServiceAccount token might also have an expiry time, an audience, +and a time after which the token *starts* being valid. When a process running +in a Pod attempts to communicate with the Kubernetes API server, it adds an +`Authorization: Bearer ` header to the HTTP request. The API server +checks the validity of the bearer token as follows: + +1. Check the token signature. +1. Check whether the token has expired. +1. Checks whether object references in the token claims are currently valid +1. Check whether the token is currently valid. +1. Check the audience claims. + +For tokens issued using the `TokenRequest` API, the API server also checks that +the specific object reference that is using the ServiceAccount still exists, +matching by the {{< glossary_tooltip term_id="uid" text="unique ID" >}} of that +object. For legacy tokens that are mounted as Secrets in Pods, the API server +checks the token against the Secret. + +For more information about the authentication process, refer to +[Authentication](/docs/reference/access-authn-authz/authentication/#service-account-tokens). + +### Authenticating service account credentials in your own code {authenticating-in-code} + +If you have services of your own that need to validate Kubernetes service +account credentials, you can use the following methods: + +* [TokenReview API](/docs/reference/kubernetes-api/authentication-resources/token-review-v1/) + (recommended) +* OIDC discovery + +The Kubernetes project recommends that you use the TokenReview API, because +this method invalidates tokens that are bound to API objects such as Secrets, +ServiceAccounts, and Pods when those objects are deleted. For example, if you +delete the Pod that contains a projected ServiceAccount token, the TokenReview +API invalidates that token immediately. If you use OIDC validation instead, your clients continue to treat the token as valid until the token reaches its +expiration timestamp. + +Your application should always define the audience that it accepts, and should +check that the token's audiences match the audiences that the application +expects. This helps to minimize the scope of the token so that it can only be +used in your appplication and nowhere else. + +## Alternatives + +* Issue your own tokens using another mechanism, and then use + [Webhook Token Authentication](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) + to validate bearer tokens using your own validation service. +* Provide your own identities to Pods. + * [Use the SPIFFE CSI driver plugin to provide SPIFFE SVIDs as X.509 certificate pairs to Pods](https://cert-manager.io/docs/projects/csi-driver-spiffe/). + {{% thirdparty-content single="true" %}} + * [Use a service mesh such as Istio to provide certificates to Pods](https://istio.io/latest/docs/tasks/security/cert-management/plugin-ca-cert/). +* Authenticate from outside the cluster to the API server without using service account tokens: + * [Configure the API server to accept OpenID Connect (OIDC) tokens from your identity provider](/docs/reference/access-authn-authz/authentication/#openid-connect-tokens). + * Use service accounts or user accounts created using an external Identity + and Access Management (IAM) service, such as from a cloud provider, to + authenticate to your cluster. + * [Use the CertificateSigningRequest API with client certificates](/docs/tasks/tls/managing-tls-in-a-cluster/). +* [Configure the kubelet to retrieve credentials from an image registry](/docs/tasks/administer-cluster/kubelet-credential-provider/). +* Use a Device Plugin to access a virtual Trusted Platform Module (TPM), which + then allows authentication using a private key. + +## {{% heading "whatsnext" %}} + +* Learn how to [manage your ServiceAccounts as a cluster administrator](/docs/reference/access-authn-authz/service-accounts-admin/). +* Learn how to [assign a ServiceAccount to a Pod](/docs/tasks/configure-pod-container/configure-service-account/). +* Read the [ServiceAccount API reference](/docs/reference/kubernetes-api/authentication-resources/service-account-v1/). \ No newline at end of file diff --git a/content/en/docs/reference/glossary/jwt.md b/content/en/docs/reference/glossary/jwt.md new file mode 100644 index 0000000000..906c941dd3 --- /dev/null +++ b/content/en/docs/reference/glossary/jwt.md @@ -0,0 +1,20 @@ +--- +title: JSON Web Token (JWT) +id: jwt +date: 2023-01-17 +full_link: https://www.rfc-editor.org/rfc/rfc7519 +short_description: > + A means of representing claims to be transferred between two parties. + +aka: +tags: +- security +- architecture +--- + A means of representing claims to be transferred between two parties. + + + +JWTs can be digitally signed and encrypted. Kubernetes uses JWTs as +authentication tokens to verify the identity of entities that want to perform +actions in a cluster.