170 lines
4.8 KiB
Markdown
170 lines
4.8 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Auth Plugin Backend: Kubernetes"
|
|
sidebar_current: "docs-auth-kubernetes"
|
|
description: |-
|
|
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.
|
|
|
|
```shell
|
|
$ curl $VAULT_ADDR/v1/auth/kubernetes/login \
|
|
-d '{ "jwt": "your_service_account_jwt", "role": "demo" }'
|
|
```
|
|
|
|
The response will be in JSON. For example:
|
|
|
|
```javascript
|
|
{
|
|
"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](https://kubernetes.io/docs/api-reference/v1.7/#tokenreview-v1-authentication)
|
|
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](/api/auth/kubernetes/index.html) for more details.
|
|
|
|
|