Templated policies¶
OpenBao fills in identity templates in an ACL policy for each request, from the entity behind the
token. One policy can then give every workload its own path. The operator stores the policy text
as you write it: Policy passes {{...}} through unchanged. The access kinds write the templates
for you.
The YAML on this page is in examples/policies/templated/, and an integration test runs every pattern end to end (How these patterns are tested).
Before you begin¶
A Ready connection openbao in the Kubernetes namespace openbao-config, whose OpenBao policy
may manage auth and secrets mounts, policies, Kubernetes auth roles and identity objects
(OpenBao policy: platform operator).
The auth method¶
OpenBao checks each login with the Kubernetes TokenReview API. The token it uses for that review
belongs to a ServiceAccount bound to system:auth-delegator:
# 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
The file also creates the reviewer token Secret and the KV v2 engine apps that the next sections use.
A path per ServiceAccount¶
At login, the Kubernetes auth method writes the ServiceAccount's namespace and name to the entity
alias metadata as service_account_namespace and service_account_name. A template reads alias
metadata through the accessor of the auth mount. The AuthMount shows that accessor in
status.id. The example below writes the accessor literally, so replace
auth_kubernetes_1a2b3c4d with yours. Policy can also put it into the text for you: name the
mount in accessorRefs and write ${accessor:<name>} where the accessor goes, as
examples/sys/policy.yaml does. OpenBao's own {{identity...}}
templates are sent unchanged.
# Every ServiceAccount named "app" in team-a or team-b gets its own folder apps/sa/<namespace>/<name>/.
# Replace auth_kubernetes_1a2b3c4d with the accessor of the auth mount:
# kubectl get authmount kubernetes -n openbao-config -o jsonpath='{.status.id}'
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
name: sa-own-folder
namespace: openbao-config
spec:
connectionRef:
name: openbao
policy: |
path "apps/data/sa/{{identity.entity.aliases.auth_kubernetes_1a2b3c4d.metadata.service_account_namespace}}/{{identity.entity.aliases.auth_kubernetes_1a2b3c4d.metadata.service_account_name}}/*" {
capabilities = ["create", "read", "update"]
}
path "apps/metadata/sa/{{identity.entity.aliases.auth_kubernetes_1a2b3c4d.metadata.service_account_namespace}}/{{identity.entity.aliases.auth_kubernetes_1a2b3c4d.metadata.service_account_name}}/*" {
capabilities = ["read", "list"]
}
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
name: apps
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: kubernetes
boundServiceAccountNames:
- app
boundServiceAccountNamespaces:
- team-a
- team-b
tokenTTL: 15m
tokenPolicies:
- sa-own-folder
- entity-own-folder
- group-folder
team-a/app can now use apps/data/sa/team-a/app/*, and team-b/app can use
apps/data/sa/team-b/app/*. Neither can use the other's path. The role also attaches the two
policies of the next section.
The accessor changes when the auth method is disabled and enabled again. A literal accessor, as in
the example, then no longer matches. A Policy that uses accessorRefs follows the AuthMount
and rewrites the policy with the new accessor. In accessorRefs, use mountPath: kubernetes
instead of authMountRef for a mount that no AuthMount manages; the operator then reads the
accessor from sys/auth at every drift check. A name in ${accessor:...} that accessorRefs does not list is an
invalid spec, and the policy waits while the mount does not exist. AccessGrant resolves the
accessor too (see below).
Entity and group templates¶
A Kubernetes login creates an entity named entity_<random>, unless an alias already links the
ServiceAccount to a named entity. With the default alias name source (serviceaccount_uid), the
alias name is the ServiceAccount UID:
# Identity templates: a folder per entity name, per entity ID and per group membership.
# A Kubernetes login creates an entity named entity_<random> unless an alias already points at a named
# entity. The EntityAlias below binds team-a/app (by ServiceAccount UID, the default alias name source)
# to the entity "billing", which is a member of the group "developers".
# kubectl get serviceaccount app -n team-a -o jsonpath='{.metadata.uid}'
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Entity
metadata:
name: billing
namespace: openbao-config
spec:
connectionRef:
name: openbao
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: EntityAlias
metadata:
name: billing-kubernetes
namespace: openbao-config
spec:
connectionRef:
name: openbao
aliasName: 6f1e3c2a-0000-4000-8000-000000000001
mountRef:
name: kubernetes
entityRef:
name: billing
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: Group
metadata:
name: developers
namespace: openbao-config
spec:
connectionRef:
name: openbao
---
apiVersion: identity.openbaoconfig.io/v1alpha1
kind: GroupMembership
metadata:
name: developers-billing
namespace: openbao-config
spec:
connectionRef:
name: openbao
groupRef:
name: developers
entityRef:
name: billing
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
name: entity-own-folder
namespace: openbao-config
spec:
connectionRef:
name: openbao
policy: |
path "apps/data/entity/{{identity.entity.name}}/*" {
capabilities = ["create", "read", "update"]
}
path "apps/data/entity-id/{{identity.entity.id}}/*" {
capabilities = ["create", "read", "update"]
}
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
name: group-folder
namespace: openbao-config
spec:
connectionRef:
name: openbao
policy: |
path "apps/data/group/{{identity.groups.names.developers.id}}/*" {
capabilities = ["create", "read", "update"]
}
- Apply the
EntityAliasbefore the ServiceAccount logs in for the first time. Otherwise the first login creates its own alias with the same name, and theEntityAliasconflicts with it. {{identity.groups.names.developers.id}}resolves only for members, so a non-member gets403. The group ID is in theGroup'sstatus.id.
AccessGrant renders the templates¶
In an AccessGrant path, {sa.namespace} and {sa.name} become the alias-metadata templates of
the auth mount the grant uses. The grant looks the accessor up on every reconcile, so you never
copy it by hand:
# The access kinds render the identity templates for you: {sa.namespace} and {sa.name} become
# {{identity.entity.aliases.<accessor>.metadata.service_account_namespace}} and ..._name, with the
# accessor of the AuthMount named by authMountRef. Log in with the role in status.roles.
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessLevel
metadata:
name: read-write
namespace: openbao-config
spec:
data:
- create
- read
- update
metadata:
- read
- list
---
apiVersion: access.openbaoconfig.io/v1alpha1
kind: AccessGrant
metadata:
name: team-apps
namespace: openbao-config
spec:
connectionRef:
name: openbao
authMountRef:
name: kubernetes
subjects:
- name: app
namespace: team-*
rules:
- mount: apps
path: grant/{sa.namespace}/{sa.name}/*
metadataPath: grant/{sa.namespace}/{sa.name}/*
level: read-write
tokenTTL: 15m
The grant writes the policy grant_<namespace>_<name> and one Kubernetes auth role per subject.
A workload logs in with the role in status.roles:
Child namespaces¶
Each OpenBao namespace has its own auth mounts, so the accessor in a template has to be the one of the auth mount inside that namespace. An object reaches a child namespace in one of two ways:
- through a connection whose
spec.namespaceis the child namespace (openbao-teambelow), or - through the root connection, with
spec.namespaceon the object.
# Templated policies in the child OpenBao namespace "team". Objects reach the child namespace in two ways:
# through a connection based in it (openbao-team), or through the root connection with spec.namespace.
# The accessor is the one of the Kubernetes auth mount inside "team", not the root one:
# kubectl get authmount team-kubernetes -n openbao-config -o jsonpath='{.status.id}'
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: OpenBaoNamespace
metadata:
name: team
namespace: openbao-config
spec:
connectionRef:
name: openbao
---
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
name: openbao-team
namespace: openbao-config
spec:
serverRef:
name: openbao
namespace: team
authNamespace: ""
auth:
kubernetes:
role: openbao-config-operator
serviceAccountRef:
name: openbao-config-operator
audiences:
- openbao
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: AuthMount
metadata:
name: team-kubernetes
namespace: openbao-config
spec:
connectionRef:
name: openbao-team
path: kubernetes
type: kubernetes
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
name: team-apps
namespace: openbao-config
spec:
connectionRef:
name: openbao-team
path: apps
type: kv-v2
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthConfig
metadata:
name: team-kubernetes
namespace: openbao-config
spec:
connectionRef:
name: openbao-team
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
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
name: team-sa-own-folder
namespace: openbao-config
spec:
connectionRef:
name: openbao-team
name: sa-own-folder
policy: |
path "apps/data/sa/{{identity.entity.aliases.auth_kubernetes_5e6f7a8b.metadata.service_account_namespace}}/{{identity.entity.aliases.auth_kubernetes_5e6f7a8b.metadata.service_account_name}}/*" {
capabilities = ["create", "read", "update"]
}
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
name: team-entity-id-folder
namespace: openbao-config
spec:
connectionRef:
name: openbao
namespace: team
name: entity-id-folder
policy: |
path "apps/data/entity-id/{{identity.entity.id}}/*" {
capabilities = ["create", "read", "update"]
}
---
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
name: team-apps
namespace: openbao-config
spec:
connectionRef:
name: openbao-team
mountPath: kubernetes
name: apps
boundServiceAccountNames:
- app
boundServiceAccountNamespaces:
- team-a
- team-b
tokenTTL: 15m
tokenPolicies:
- sa-own-folder
- entity-id-folder
The file holds the full set: the namespace, the connection, the auth mount, the KV engine, the
auth config, both policies and the role in team. Workloads log in to the child namespace with the X-Vault-Namespace: team header
(BAO_NAMESPACE=team).
Changing a policy¶
OpenBao looks a policy up by name on every request. Edit the Policy, wait until it is Ready,
and the next token uses the new text. The test adds delete to a policy, waits for the write,
logs in again, and the new token can delete.
Ordering¶
EntityAlias and GroupMembership resolve their references (mountRef, entityRef, groupRef)
when they reconcile. If a reference is not Ready yet, the object reports ReferenceNotReady and
tries again with a backoff from 2 seconds up to 30 seconds; a change of the referent does not
trigger an earlier retry. If you apply everything at once, expect up to 30 seconds per level of
references before everything is Ready.
How these patterns are tested¶
test/integration/templated_acl_test.go runs the operator against an envtest API server and
bao server -dev. Real ServiceAccounts from two Kubernetes namespaces log in with TokenRequest
tokens, then the test reads and writes secrets with the tokens they get. The same test applies the
files of examples/policies/templated/ with a server-side dry run. It proves that:
- A ServiceAccount can read and write only its own templated path. It gets
403on the path of the other ServiceAccount, on another name in its own namespace, and on paths without a template. {{identity.entity.name}}and{{identity.entity.id}}work both for a named entity (bound withEntityandEntityAlias) and for theentity_<random>entity that a login creates.- A
{{identity.groups.names.<group>.id}}path works only for members of the group. Membership comes fromGroupandGroupMembership. - An
AccessGrantwith{sa.namespace}/{sa.name}gives the same isolation, for data and for metadatalist. - A capability added to a
Policyapplies to the next token of that ServiceAccount. - In a child OpenBao namespace, a policy written through a connection based in that namespace
works, and so does one written with
spec.namespacethrough the root connection. Neither policy appears in the root namespace.
CI runs it with the other integration tests. To run it alone from a clone of the repository, with
bao on your PATH or in BAO_BIN: