--- layout: docs page_title: Kubernetes Auth Method description: >- Use the Kubernetes auth method type to authenticate to Consul with a Kubernetes service account token and receive an ACL token with privileges based on JWT identity attributes. Learn how to configure auth method parameters using this reference page and example configuration. --- # Kubernetes Auth Method -> **1.5.0+:** This feature is available in Consul versions 1.5.0 and newer. The `kubernetes` auth method type allows for a Kubernetes service account token to be used to authenticate to Consul. This method of authentication makes it easy to introduce a Consul token into a Kubernetes pod. This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and the concepts described in the main [auth method documentation](/consul/docs/security/acl/auth-methods). ## Config Parameters The following auth method [`Config`](/consul/api-docs/acl/auth-methods#config) parameters are required to properly configure an auth method of type `kubernetes`: - `Host` `(string: )` - Must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server. - `CACert` `(string: )` - PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. NOTE: Every line must end with a newline (`\n`). If not set, system certificates are used. - `ServiceAccountJWT` `(string: )` - A Service Account Token ([JWT](https://jwt.io/ 'JSON Web Token')) used by the Consul leader to validate application JWTs during login. - `MapNamespaces` `(bool: )` - **Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).** Indicates whether the auth method should attempt to map the Kubernetes namespace to a Consul namespace instead of creating tokens in the auth methods own namespace. Note that mapping namespaces requires the auth method to reside within the `default` namespace. Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules). - `ConsulNamespacePrefix` `(string: )` - **Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).** When `MapNamespaces` is enabled, this value will be prefixed to the Kubernetes namespace to determine the Consul namespace to create the new token within. Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules). - `ConsulNamespaceOverrides` `(map: )` - **Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules).** This field is a mapping of Kubernetes namespace names to Consul namespace names. If a Kubernetes namespace is present within this map, the value will be used without adding the `ConsulNamespacePrefix`. If the value in the map is `""` then the auth methods namespace will be used instead of attempting to determine an alternate namespace. Deprecated in Consul 1.8.0 in favor of [namespace rules](/consul/api-docs/acl/auth-methods#namespacerules). ### Sample Config ```json { "Name": "example-k8s-auth", "Type": "kubernetes", "Description": "Example JWT auth method", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." } } ``` ## RBAC The Kubernetes service account corresponding to the configured [`ServiceAccountJWT`](/consul/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt) needs to have access to two Kubernetes APIs: - [**TokenReview**](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/) -> Kubernetes should be running with `--service-account-lookup`. This is defaulted to true in Kubernetes 1.7, but any versions prior should ensure the Kubernetes API server is started with this setting. - [**ServiceAccount**](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens) The following is an example [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) configuration snippet to grant the necessary permissions to a service account named `consul-auth-method-example`: ```yaml --- kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: review-tokens namespace: default subjects: - kind: ServiceAccount name: consul-auth-method-example namespace: default roleRef: kind: ClusterRole name: system:auth-delegator apiGroup: rbac.authorization.k8s.io --- kind: ClusterRole apiVersion: rbac.authorization.k8s.io/v1 metadata: name: service-account-getter namespace: default rules: - apiGroups: [''] resources: ['serviceaccounts'] verbs: ['get'] --- kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: get-service-accounts namespace: default subjects: - kind: ServiceAccount name: consul-auth-method-example namespace: default roleRef: kind: ClusterRole name: service-account-getter apiGroup: rbac.authorization.k8s.io ``` ## Kubernetes Authentication Details Initially the [`ServiceAccountJWT`](/consul/docs/security/acl/auth-methods/kubernetes#serviceaccountjwt) given to the Consul leader uses the TokenReview API to validate the provided JWT. The trusted attributes of `serviceaccount.namespace`, `serviceaccount.name`, and `serviceaccount.uid` are populated directly from the Service Account metadata. The Consul leader makes an additional query, this time to the ServiceAccount API to check for the existence of an annotation of `consul.hashicorp.com/service-name` on the ServiceAccount object. If one is found its value will override the trusted attribute of `serviceaccount.name` for the purposes of evaluating any binding rules. ## Trusted Identity Attributes The authentication step returns the following trusted identity attributes for use in binding rule selectors and bind name interpolation. | Attributes | Supported Selector Operations | Can be Interpolated | | -------------------------- | -------------------------------------------------- | ------------------- | | `serviceaccount.namespace` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | `serviceaccount.name` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | `serviceaccount.uid` | Equal, Not Equal, In, Not In, Matches, Not Matches | yes |