open-vault/website/content/docs/auth/kubernetes.mdx

---
layout: docs
page_title: Kubernetes - Auth Methods
description: |-
  The Kubernetes auth method allows automated authentication of Kubernetes
  Service Accounts.
---

# Kubernetes Auth Method

The `kubernetes` auth method can be used to authenticate with Vault using a
Kubernetes Service Account Token. This method of authentication makes it easy to
introduce a Vault token into a Kubernetes Pod.

## Authentication

### Via the CLI

The default path is `/kubernetes`. If this auth method was enabled at a
different path, specify `-path=/my-path` in the CLI.

```shell-session
$ vault write auth/kubernetes/login role=demo jwt=...
```

### Via the API

The default endpoint is `auth/kubernetes/login`. If this auth method was enabled
at a different path, use that value instead of `kubernetes`.

```shell-session
$ curl \
    --request POST \
    --data '{"jwt": "<your service account jwt>", "role": "demo"}' \
    http://127.0.0.1:8200/v1/auth/kubernetes/login
```

The response will contain a token at `auth.client_token`:

```json
{
  "auth": {
    "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
    "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
    "policies": ["default"],
    "metadata": {
      "role": "demo",
      "service_account_name": "vault-auth",
      "service_account_namespace": "default",
      "service_account_secret_name": "vault-auth-token-pd21c",
      "service_account_uid": "aa9aa8ff-98d0-11e7-9bb7-0800276d99bf"
    },
    "lease_duration": 2764800,
    "renewable": true
  }
}
```

## Configuration

Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.

1.  Enable the Kubernetes auth method:

    ```text
    $ vault auth enable kubernetes
    ```

1.  Use the `/config` endpoint to configure Vault to talk to Kubernetes. Use `kubectl cluster-info` to validate the Kubernetes host address and TCP port. Kubernetes 1.21+ clusters may require setting the service account `issuer`, [as described here](/docs/auth/kubernetes#discovering-the-service-account-issuer). For the list of available configuration options, please see the [API documentation](/api/auth/kubernetes).

    ```text
    $ vault write auth/kubernetes/config \
        token_reviewer_jwt="<your reviewer service account JWT>" \
        kubernetes_host=https://192.168.99.100:<your TCP port or blank for 443> \
        kubernetes_ca_cert=@ca.crt
    ```

    !> **NOTE:** The pattern Vault uses to authenticate Pods depends on sharing
    the JWT token over the network. Given the [security model of
    Vault](/docs/internals/security), this is allowable because Vault is
    part of the trusted compute base. In general, Kubernetes applications should
    **not** share this JWT with other applications, as it allows API calls to be
    made on behalf of the Pod and can result in unintended access being granted
    to 3rd parties.

1.  Create a named role:

    ```text
    vault write auth/kubernetes/role/demo \
        bound_service_account_names=vault-auth \
        bound_service_account_namespaces=default \
        policies=default \
        ttl=1h
    ```

    This role authorizes the "vault-auth" service account in the default
    namespace and it gives it the default policy.

    For the complete list of configuration options, please see the [API
    documentation](/api/auth/kubernetes).

### Discovering the service account `issuer`

Kubernetes 1.21+ clusters may require setting the service account
[`issuer`](/api-docs/auth/kubernetes#issuer) to the same value as
`kube-apiserver`'s `--service-account-issuer` flag. This is because the service
account JWTs for these clusters may have an issuer specific to the cluster
itself, instead of the old default of `kubernetes/serviceaccount`. If you are
unable to check this value directly, you can run the following and look for the
`"iss"` field to find the required value:

```bash
kubectl proxy &
curl --silent http://127.0.0.1:8001/api/v1/namespaces/default/serviceaccounts/default/token \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"apiVersion": "authentication.k8s.io/v1", "kind": "TokenRequest"}' \
  | jq -r '.status.token' \
  | cut -d. -f2 \
  | base64 -D
```

Most clusters will also have that information available at the
`.well-known/openid-configuration` endpoint:

```bash
kubectl proxy &
curl --silent http://127.0.0.1:8001/.well-known/openid-configuration | jq -r .issuer
```

This value is then used when configuring Kubernetes auth, e.g.:

```bash
vault write auth/kubernetes/config \
  token_reviewer_jwt="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
  kubernetes_host="https://$KUBERNETES_PORT_443_TCP_ADDR:443" \
  kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
  issuer="\"test-aks-cluster-dns-d6cbb78e.hcp.uksouth.azmk8s.io\""
```

## Configuring Kubernetes

This auth method accesses the [Kubernetes TokenReview API][k8s-tokenreview] to
validate the provided JWT is still valid. 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. Otherwise deleted tokens in Kubernetes will not be properly revoked and
will be able to authenticate to this auth method.

Service Accounts used in this auth method will need to have access to the
TokenReview API. If Kubernetes is configured to use RBAC roles, the Service
Account should be granted permissions to access this API. The following
example ClusterRoleBinding could be used to grant these permissions:

```yaml
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: role-tokenreview-binding
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
  - kind: ServiceAccount
    name: vault-auth
    namespace: default
```

## API

The Kubernetes Auth Plugin has a full HTTP API. Please see the
[API docs](/api/auth/kubernetes) for more details.

[k8s-tokenreview]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#tokenreview-v1beta1-authentication-k8s-io