341 lines
13 KiB
Plaintext
341 lines
13 KiB
Plaintext
---
|
|
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
|
|
|
|
## Code Example
|
|
|
|
The following code snippet demonstrates the Kubernetes auth method to authenticate
|
|
with Vault.
|
|
|
|
<CodeTabs heading="kubernetes auth example">
|
|
|
|
<CodeBlockConfig lineNumbers>
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"os"
|
|
|
|
vault "github.com/hashicorp/vault/api"
|
|
)
|
|
|
|
// Fetches a key-value secret (kv-v2) after authenticating to Vault with a Kubernetes service account.
|
|
//
|
|
// As the client, all we need to do is pass along the JWT token representing our application's Kubernetes Service Account in our login request to Vault.
|
|
//
|
|
// For a more in-depth setup explanation, please see the full version of this code in the hashicorp/vault-examples repo.
|
|
func getSecretWithKubernetesAuth() (string, error) {
|
|
// If set, the VAULT_ADDR environment variable will be the address that your pod uses to communicate with Vault.
|
|
config := vault.DefaultConfig() // modify for more granular configuration
|
|
|
|
client, err := vault.NewClient(config)
|
|
if err != nil {
|
|
return "", fmt.Errorf("unable to initialize Vault client: %w", err)
|
|
}
|
|
|
|
// Read the service-account token from the path where the token's Kubernetes Secret is mounted.
|
|
// By default, Kubernetes will mount this to /var/run/secrets/kubernetes.io/serviceaccount/token
|
|
// but an administrator may have configured it to be mounted elsewhere.
|
|
jwt, err := os.ReadFile("path/to/service-account-token")
|
|
if err != nil {
|
|
return "", fmt.Errorf("unable to read file containing service account token: %w", err)
|
|
}
|
|
|
|
params := map[string]interface{}{
|
|
"jwt": string(jwt),
|
|
"role": "dev-role-k8s", // the name of the role in Vault that was created with this app's Kubernetes service account bound to it
|
|
}
|
|
|
|
// log in to Vault's Kubernetes auth method
|
|
resp, err := client.Logical().Write("auth/kubernetes/login", params)
|
|
if err != nil {
|
|
return "", fmt.Errorf("unable to log in with Kubernetes auth: %w", err)
|
|
}
|
|
if resp == nil || resp.Auth == nil || resp.Auth.ClientToken == "" {
|
|
return "", fmt.Errorf("login response did not return client token")
|
|
}
|
|
|
|
// now you will use the resulting Vault token for making all future calls to Vault
|
|
client.SetToken(resp.Auth.ClientToken)
|
|
|
|
// get secret from Vault
|
|
secret, err := client.Logical().Read("kv-v2/data/creds")
|
|
if err != nil {
|
|
return "", fmt.Errorf("unable to read secret: %w", err)
|
|
}
|
|
|
|
data, ok := secret.Data["data"].(map[string]interface{})
|
|
if !ok {
|
|
return "", fmt.Errorf("data type assertion failed: %T %#v", secret.Data["data"], secret.Data["data"])
|
|
}
|
|
|
|
// data map can contain more than one key-value pair, in this case we're just grabbing one of them
|
|
key := "password"
|
|
value, ok := data[key].(string)
|
|
if !ok {
|
|
return "", fmt.Errorf("value type assertion failed: %T %#v", data[key], data[key])
|
|
}
|
|
|
|
return value, nil
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
<CodeBlockConfig lineNumbers>
|
|
|
|
```cs
|
|
using System;
|
|
using System.IO;
|
|
using VaultSharp;
|
|
using VaultSharp.V1.AuthMethods;
|
|
using VaultSharp.V1.AuthMethods.Kubernetes;
|
|
using VaultSharp.V1.Commons;
|
|
|
|
namespace Examples
|
|
{
|
|
public class KubernetesAuthExample
|
|
{
|
|
const string DefaultTokenPath = "path/to/service-account-token";
|
|
|
|
// Fetches a key-value secret (kv-v2) after authenticating to Vault with a Kubernetes service account.
|
|
//
|
|
// As the client, all we need to do is pass along the JWT token representing our application's Kubernetes Service Account in our login request to Vault.
|
|
// This token is automatically mounted to your application's container by Kubernetes. Read more at https://www.vaultproject.io/docs/auth/kubernetes
|
|
//
|
|
// SETUP NOTES: If an operator has not already set up Kubernetes auth in Vault for you, then you must also first configure the Vault server with its own Service Account token to be able to communicate with the Kubernetes API
|
|
// so it can verify that the client's service-account token is valid. The service account that will be performing that verification needs the ClusterRole system:auth-delegator.
|
|
//
|
|
// export TOKEN_REVIEW_JWT=$(kubectl get secret $TOKEN_REVIEWER_SECRET --output='go-template={{ .data.token }}' | base64 --decode)
|
|
// export KUBE_HOST=$(kubectl config view --raw --minify --flatten --output='jsonpath={.clusters[].cluster.server}')
|
|
// kubectl config view --raw --minify --flatten --output='jsonpath={.clusters[].cluster.certificate-authority-data}' | base64 --decode > path/to/kube_ca_cert
|
|
//
|
|
// vault write auth/kubernetes/config \
|
|
// token_reviewer_jwt=${TOKEN_REVIEW_JWT} \
|
|
// kubernetes_host=${KUBE_HOST} \
|
|
// kubernetes_ca_cert=@path/to/kube_ca_cert \
|
|
// issuer="kubernetes/serviceaccount"
|
|
//
|
|
// The "issuer" field is normally only required when running Kubernetes 1.21 or above, and may differ from the default value above:
|
|
// https://www.vaultproject.io/docs/auth/kubernetes#discovering-the-service-account-issuer.
|
|
//
|
|
// Finally, make sure to create a role in Vault bound to your pod's service account:
|
|
//
|
|
// vault write auth/kubernetes/role/dev-role-k8s \
|
|
// policies="dev-policy" \
|
|
// bound_service_account_names="my-app" \
|
|
// bound_service_account_namespaces="default"
|
|
public string GetSecretWithK8s()
|
|
{
|
|
var vaultAddr = Environment.GetEnvironmentVariable("VAULT_ADDR");
|
|
if(String.IsNullOrEmpty(vaultAddr))
|
|
{
|
|
throw new System.ArgumentNullException("Vault Address");
|
|
}
|
|
|
|
var roleName = Environment.GetEnvironmentVariable("VAULT_ROLE");
|
|
if(String.IsNullOrEmpty(roleName))
|
|
{
|
|
throw new System.ArgumentNullException("Vault Role Name");
|
|
}
|
|
|
|
// Get the path to service account token or fall back on default path
|
|
string pathToToken = String.IsNullOrEmpty(Environment.GetEnvironmentVariable("SA_TOKEN_PATH")) ? DefaultTokenPath : Environment.GetEnvironmentVariable("SA_TOKEN_PATH");
|
|
string jwt = File.ReadAllText(pathToToken);
|
|
|
|
IAuthMethodInfo authMethod = new KubernetesAuthMethodInfo(roleName, jwt);
|
|
var vaultClientSettings = new VaultClientSettings(vaultAddr, authMethod);
|
|
|
|
IVaultClient vaultClient = new VaultClient(vaultClientSettings);
|
|
|
|
// We can retrieve the secret after creating our VaultClient object
|
|
Secret<SecretData> kv2Secret = null;
|
|
kv2Secret = vaultClient.V1.Secrets.KeyValue.V2.ReadSecretAsync(path: "/creds").Result;
|
|
|
|
var password = kv2Secret.Data.Data["password"];
|
|
|
|
return password.ToString();
|
|
}
|
|
}
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
</CodeTabs>
|