Configure OpenBao Kubernetes authentication¶
This guide sets up OpenBao's Kubernetes auth method from Kubernetes resources, so that workloads log in with their ServiceAccount token and get exactly the policies their role grants.
Before you begin¶
- A
Readyconnection whose OpenBao policy allows the paths below (OpenBao policy for the operator):sys/auth(read), andsys/auth/<mount>andsys/auth/<mount>/tune(create,read,update,delete,sudo) to manage the mount itself;auth/<mount>/configandauth/<mount>/role/*to manage its configuration and roles;sys/policies/acl/guide-app-readto manage the example ACL policy;sys/mountsandsys/mounts/appsto inspect and enable the example KV mount.
- If the auth method already exists and someone else manages it, skip step 1 and set only the roles.
1. Enable the auth method and configure it¶
An AuthMount enables the method, and a KubernetesAuthConfig tells it how to review tokens. This
example also creates the ServiceAccount whose token OpenBao uses for the TokenReview API, binds it
to system:auth-delegator, and enables the KV engine that the role's policy grants:
# The Kubernetes auth method and the KV v2 engine that the templated policies in this directory use.
# OpenBao calls the TokenReview API with the token of openbao-token-reviewer, which needs
# system:auth-delegator.
apiVersion: v1
kind: ServiceAccount
metadata:
name: openbao-token-reviewer
namespace: openbao-config
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: openbao-token-reviewer
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: system:auth-delegator
subjects:
- kind: ServiceAccount
name: openbao-token-reviewer
namespace: openbao-config
---
apiVersion: v1
kind: Secret
metadata:
name: openbao-token-reviewer
namespace: openbao-config
annotations:
kubernetes.io/service-account.name: openbao-token-reviewer
type: kubernetes.io/service-account-token
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
name: kubernetes
namespace: openbao-config
spec:
connectionRef:
name: openbao
type: kubernetes
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
name: apps
namespace: openbao-config
spec:
connectionRef:
name: openbao
type: kv-v2
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthConfig
metadata:
name: kubernetes
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: kubernetes
kubernetesHost: https://kubernetes.default.svc
kubernetesCACert: |
-----BEGIN CERTIFICATE-----
REPLACE-WITH-THE-CLUSTER-CA
-----END CERTIFICATE-----
tokenReviewerJWTSecretRef:
name: openbao-token-reviewer
key: token
disableLocalCAJWT: true
Replace kubernetesCACert with the cluster CA (kubectl config view --raw --minify -o
jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d).
If OpenBao runs as a pod in the same cluster, it can review tokens with its own ServiceAccount
instead: set only kubernetesHost: https://kubernetes.default.svc:443, leave out
kubernetesCACert, tokenReviewerJWTSecretRef and disableLocalCAJWT, and bind OpenBao's
ServiceAccount to system:auth-delegator. The quickstart works
that way.
kubectl apply -f examples/policies/templated/00-kubernetes-auth.yaml
kubectl -n openbao-config wait authmount/kubernetes kubernetesauthconfig/kubernetes \
--for=condition=Ready --timeout=2m
2. Create a policy and a role¶
First create Policy/guide-app-read by following Manage OpenBao policies.
It grants read access to apps/data/app/* and uses the same openbao connection in
openbao-config as step 1.
Create the workload's namespace and ServiceAccount:
kubectl create namespace apps --dry-run=client -o yaml | kubectl apply -f -
kubectl -n apps create serviceaccount app --dry-run=client -o yaml | kubectl apply -f -
The role binds that ServiceAccount name and namespace to the policy. policyRefs makes the role
wait until the managed policy exists in OpenBao. Save this as app-role.yaml:
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
name: guide-app
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: kubernetes
name: guide-app
boundServiceAccountNames:
- app
boundServiceAccountNamespaces:
- apps
audience: openbao
tokenTTL: 15m
policyRefs:
- name: guide-app-read
Every field of the kind, including token limits and bound CIDRs:
examples/auth/kubernetesauthrole.yaml
# Lets pods of ServiceAccount app or app-worker in namespace team-a (or in a namespace selected by labels) log in
# with the openbao audience and get the app-reader policy plus the policy of a Policy resource.
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
name: app-reader
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: kubernetes
name: app-reader
boundServiceAccountNames:
- app
- app-worker
boundServiceAccountNamespaces:
- team-a
boundServiceAccountNamespaceSelector:
matchLabels:
tenant: team-a
environment: dev
audience: openbao
aliasNameSource: serviceaccount_name
tokenTTL: 1h
tokenMaxTTL: 4h
tokenExplicitMaxTTL: 8h
tokenPeriod: 30m
tokenPolicies:
- app-reader
policyRefs:
- name: obco-team-a-reader
tokenBoundCIDRs:
- 10.42.0.0/16
- 10.43.0.10
tokenNumUses: 0
tokenType: service
tokenNoDefaultPolicy: false
tokenStrictlyBindIP: false
Set audience and have the workload request a token for it. A role without an audience accepts
any token the API server signed for the ServiceAccount, including the automounted one, which is
also a Kubernetes API credential.
Bind one ServiceAccount name per role where you can. "*" in boundServiceAccountNames or
boundServiceAccountNamespaces lets every matching ServiceAccount use the role's policies.
Tenants writing their own roles
A tenant connection that may write roles could bind ServiceAccounts of another Kubernetes
namespace. Pin bound_service_account_namespaces with allowed_parameters in the tenant's
OpenBao policy: OpenBao policy: tenant operator.
3. Check that it worked¶
The role is managed in Kubernetes namespace openbao-config; the workload ServiceAccount lives
in namespace apps. Set the CLI to the same OpenBao namespace as the connection.
kubectl -n openbao-config wait kubernetesauthrole/guide-app --for=condition=Ready --timeout=2m
bao read auth/kubernetes/role/guide-app
Log in as the workload with a token for the role's audience:
bao write auth/kubernetes/login role=guide-app \
jwt="$(kubectl -n apps create token app --audience openbao)"
The response lists the token's policies.
Troubleshooting¶
| symptom | check |
|---|---|
AuthMount reports PermissionDenied |
enabling and tuning an auth method needs sudo on sys/auth/<mount> |
role reports ReferenceNotReady |
a Policy in policyRefs is missing, not Ready, or uses another connectionRef or spec.namespace than the role |
login fails with permission denied and service account name not authorized |
boundServiceAccountNames and boundServiceAccountNamespaces |
login fails with invalid audience |
the token was requested without --audience, or for another audience than the role's audience |
| login fails with a TokenReview error | the reviewer ServiceAccount's system:auth-delegator binding, kubernetesHost and the CA certificate |
Related¶
- API reference: AuthMount, KubernetesAuthConfig, KubernetesAuthRole, Policy.
- Access model:
AccessGrantwrites the policy and one role per subject for you. - Manage policies: declare and verify the ACL before attaching it to a role.
- Templated policies: one policy for many ServiceAccounts.