open-vault/website/source/docs/auth/kubernetes.html.md

layout	page_title	sidebar_current	description
docs	Auth Plugin Backend: Kubernetes	docs-auth-kubernetes	The Kubernetes auth backend allows automated authentication of Kubernetes Service Accounts.

Auth Backend: Kubernetes

Name: kubernetes

The Kubernetes auth backend 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

$ vault write auth/kubernetes/login role=demo jwt=...

Key                                   	Value
---                                   	-----
token                                 	1a445c6a-1ff5-7085-18f7-eca12210981d
token_accessor                        	fa82afb3-298b-41b0-6593-8b861bd3dc12
token_duration                        	768h0m0s
token_renewable                       	true
token_policies                        	[default]
token_meta_service_account_secret_name	"vault-auth-token-pd21c"
token_meta_service_account_uid        	"aa9aa8ff-98d0-11e7-9bb7-0800276d99bf"
token_meta_role                       	"demo"
token_meta_service_account_name       	"vault-auth"
token_meta_service_account_namespace  	"default"

Via the API

The endpoint for the kubernetes login is auth/kubernetes/login.

The kubernetes mountpoint value in the url is the default mountpoint value. If you have mounted the kubernetes backend with a different mountpoint, use that value.

$ curl $VAULT_ADDR/v1/auth/kubernetes/login \
    -d '{ "jwt": "your_service_account_jwt", "role": "demo" }'

The response will be in JSON. For example:

{
	"request_id": "e344f8c2-fffc-c3e0-d118-e3a2e5de2d0d",
	"lease_id": "",
	"lease_duration": 0,
	"renewable": false,
	"data": null,
	"warnings": null,
	"auth": {
		"client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
		"accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
		"policies": [
			"default"
		],
		"metadata": {
			"role": "test",
			"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

First, you must enable the Kubernetes auth backend:

$ vault auth-enable kubernetes
Successfully enabled 'kubernetes' at 'kubernetes'!

Now when you run vault auth -methods, the Kubernetes backend is available:

Path         Type        Description
kubernetes/  kubernetes
token/       token       token based credentials

Prior to using the Kubernetes auth backend, it must be configured. To configure it, use the /config endpoint.

$ vault write auth/kubernetes/config \
    token_reviewer_jwt="reviewer_service_account_jwt" \
    kubernetes_host=https://192.168.99.100:8443 \
    kubernetes_ca_cert=@ca.crt

Creating a Role

Authentication with this backend is role based. Before a token can be used to login it first must be configured in a role.

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.

Configuring Kubernetes

Token Review Lookup

This backend accesses the Kubernetes TokenReview API 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 with this setting. Otherwise deleted tokens in Kubernetes will not be properly revoked and will be able to authenticate to this backend.

RBAC Configuration

The Service Account used to lookup Tokens in this backend will need to have access to the TokenReview API. If Kubernetes is configured to use Role Based Access Control the Service Account should be granted permissions to access this API. The following example ClusterRoleBinding could be used to grant these permissions:

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

GKE

Currently the Token Review API endpoint is only available in alpha clusters on Google Container Engine. This means on GKE this backend can only be used with an alpha cluster.

API

The Kubernetes Auth Plugin has a full HTTP API. Please see the API docs for more details.