1---
2layout: docs
3page_title: Kubernetes - Auth Methods
4sidebar_title: Kubernetes
5description: |-
6  The Kubernetes auth method allows automated authentication of Kubernetes
7  Service Accounts.
8---
9
10# Kubernetes Auth Method
11
12The `kubernetes` auth method can be used to authenticate with Vault using a
13Kubernetes Service Account Token. This method of authentication makes it easy to
14introduce a Vault token into a Kubernetes Pod.
15
16## Authentication
17
18### Via the CLI
19
20The default path is `/kubernetes`. If this auth method was enabled at a
21different path, specify `-path=/my-path` in the CLI.
22
23```text
24$ vault write auth/kubernetes/login role=demo jwt=...
25```
26
27### Via the API
28
29The default endpoint is `auth/kubernetes/login`. If this auth method was enabled
30at a different path, use that value instead of `kubernetes`.
31
32```shell
33$ curl \
34    --request POST \
35    --data '{"jwt": "your_service_account_jwt", "role": "demo"}' \
36    http://127.0.0.1:8200/v1/auth/kubernetes/login
37```
38
39The response will contain a token at `auth.client_token`:
40
41```json
42{
43  "auth": {
44    "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
45    "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
46    "policies": ["default"],
47    "metadata": {
48      "role": "demo",
49      "service_account_name": "vault-auth",
50      "service_account_namespace": "default",
51      "service_account_secret_name": "vault-auth-token-pd21c",
52      "service_account_uid": "aa9aa8ff-98d0-11e7-9bb7-0800276d99bf"
53    },
54    "lease_duration": 2764800,
55    "renewable": true
56  }
57}
58```
59
60## Configuration
61
62Auth methods must be configured in advance before users or machines can
63authenticate. These steps are usually completed by an operator or configuration
64management tool.
65
661.  Enable the Kubernetes auth method:
67
68    ```text
69    $ vault auth enable kubernetes
70    ```
71
721.  Use the `/config` endpoint to configure Vault to talk to Kubernetes. For the
73    list of available configuration options, please see the API documentation.
74
75    ```text
76    $ vault write auth/kubernetes/config \
77        token_reviewer_jwt="reviewer_service_account_jwt" \
78        kubernetes_host=https://192.168.99.100:8443 \
79        kubernetes_ca_cert=@ca.crt
80    ```
81
82    !> **NOTE:** The pattern Vault uses to authenticate Pods depends on sharing
83    the JWT token over the network. Given the [security model of
84    Vault](/docs/internals/security), this is allowable because Vault is
85    part of the trusted compute base. In general, Kubernetes applications should
86    **not** share this JWT with other applications, as it allows API calls to be
87    made on behalf of the Pod and can result in unintended access being granted
88    to 3rd parties.
89
901.  Create a named role:
91
92    ```text
93    vault write auth/kubernetes/role/demo \
94        bound_service_account_names=vault-auth \
95        bound_service_account_namespaces=default \
96        policies=default \
97        ttl=1h
98    ```
99
100    This role authorizes the "vault-auth" service account in the default
101    namespace and it gives it the default policy.
102
103    For the complete list of configuration options, please see the API
104    documentation.
105
106## Configuring Kubernetes
107
108This auth method accesses the [Kubernetes TokenReview API][k8s-tokenreview] to
109validate the provided JWT is still valid. Kubernetes should be running with
110`--service-account-lookup`. This is defaulted to true in Kubernetes 1.7, but any
111versions prior should ensure the Kubernetes API server is started with this
112setting. Otherwise deleted tokens in Kubernetes will not be properly revoked and
113will be able to authenticate to this auth method.
114
115Service Accounts used in this auth method will need to have access to the
116TokenReview API. If Kubernetes is configured to use RBAC roles, the Service
117Account should be granted permissions to access this API. The following
118example ClusterRoleBinding could be used to grant these permissions:
119
120```yaml
121apiVersion: rbac.authorization.k8s.io/v1beta1
122kind: ClusterRoleBinding
123metadata:
124  name: role-tokenreview-binding
125  namespace: default
126roleRef:
127  apiGroup: rbac.authorization.k8s.io
128  kind: ClusterRole
129  name: system:auth-delegator
130subjects:
131  - kind: ServiceAccount
132    name: vault-auth
133    namespace: default
134```
135
136## API
137
138The Kubernetes Auth Plugin has a full HTTP API. Please see the
139[API docs](/api/auth/kubernetes) for more details.
140
141[k8s-tokenreview]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#tokenreview-v1-authentication-k8s-io
142