Skip to content

What OpenBao must grant

The plane cannot write its own policies. That takes an OpenBao administrator, a root token or one allowed to write sys/policies/acl and the auth roles, which the plane never is. So an administrator runs the lines below once, and again for a grant an upgrade adds; nothing else here is done by hand.

The plane checks them. When it starts, and on the console's Overview, the plane asks OpenBao what its own token may do at each path below, look-only (sys/capabilities-self, which the default policy allows), and says in one sentence for each grant it lacks what fails without it, with the lines that grant it, written with the deployment's own mounts, key names, role and the policies its token already carries. admin.overview answers the same as openbao.

The names are the defaults: mounts secret (KV v2) and transit, the Kubernetes auth mount kubernetes, the role troupe-plane (the chart's bao.authPath and bao.planeRole), and the release namespace troupe-system.

1. Before the plane starts

The engines, the session-token key, Kubernetes auth with a reviewer (integrations.md §2), and the plane's role, carrying the policy of every grant the plane needs:

bao secrets enable -path=transit transit
bao secrets enable -path=secret -version=2 kv
bao write -f transit/keys/troupe-session-tokens type=ecdsa-p256
bao auth enable kubernetes
bao write auth/kubernetes/config kubernetes_host=https://kubernetes.default.svc:443   # and the reviewer's JWT and CA
bao write auth/kubernetes/role/troupe-plane bound_service_account_names=troupe-plane bound_service_account_namespaces=troupe-system audience=troupe-kms token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane ttl=1h

Then write each policy in section 2. A plane whose role is missing or refuses its ServiceAccount token says so at start, and on the Overview, with the role line above.

2. What the plane's role carries

grant policy what it is for without it
session-tokens troupe-plane-session-tokens sign session tokens, and read the key's public half that workers check them with no session opens, and no pod or person's daemon can check a token
plane-signing troupe-plane-signing make, rotate and sign with the plane's own key, which signs what it tells people's machines the client versions and defaults go out unsigned, and every client that pinned this plane's key refuses them
erasure troupe-plane destroy an erased session's key, a team's or a person's, and see which credentials a person has connected erasing a session cannot destroy its key, and the console cannot say who has connected what
invites (only for inviting people into private sessions) troupe-plane-invites destroy the copy of a private session's key its owner's daemon put in an invitee's own slot, when the invitation is taken back or the session erased an erasure of a private session somebody was invited into stays pending, and taking an invitation back leaves the copy it gave in the invitee's slot
github-app (only with a GitHub App) troupe-plane-github import, sign with and delete the GitHub App's key and webhook secret a GitHub App cannot be set up, and one set up before stops signing

token_policies replaces the role's whole list, so each section below ends with the same line, naming every policy in the table, the optional ones too: OpenBao grants nothing for a name it holds no policy under, and the plane checks what its token can do, not what the role names. Run the sections in any order, one alone or again after an upgrade, and the role still carries every policy written.

troupe-plane-session-tokens

To sign session tokens, and read the key's public half that workers check them with.

bao policy write troupe-plane-session-tokens - <<'POLICY'
path "transit/sign/troupe-session-tokens" {
  capabilities = ["create", "update"]
}

path "transit/keys/troupe-session-tokens" {
  capabilities = ["read"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github

troupe-plane-signing

To make, rotate and sign with the plane's own key, which signs what it tells people's machines.

bao policy write troupe-plane-signing - <<'POLICY'
path "transit/keys/troupe-plane-signing" {
  capabilities = ["create", "read", "update"]
}

path "transit/keys/troupe-plane-signing/rotate" {
  capabilities = ["update"]
}

path "transit/sign/troupe-plane-signing" {
  capabilities = ["create", "update"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github

troupe-plane

To destroy an erased session's key, a team's or a person's, and see which credentials a person has connected.

bao policy write troupe-plane - <<'POLICY'
path "secret/metadata/troupe/teams/+/sessions/*" {
  capabilities = ["delete", "list", "read"]
}

path "secret/metadata/troupe/people/+/sessions/*" {
  capabilities = ["delete", "list", "read"]
}

path "secret/metadata/troupe/people/+/mcp/*" {
  capabilities = ["list", "read"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github

troupe-plane-invites

To destroy the copy of a private session's key its owner's daemon put in an invitee's own slot, when the invitation is taken back or the session erased. Only where people are invited into private sessions.

bao policy write troupe-plane-invites - <<'POLICY'
path "secret/metadata/troupe/people/+/invited/*" {
  capabilities = ["delete"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github

troupe-plane-github

To import, sign with and delete the GitHub App's key and webhook secret. Only where the plane has a GitHub App.

bao policy write troupe-plane-github - <<'POLICY'
path "transit/wrapping_key" {
  capabilities = ["read"]
}

path "transit/keys/troupe-github-app" {
  capabilities = ["read", "delete"]
}

path "transit/keys/troupe-github-app/config" {
  capabilities = ["update"]
}

path "transit/keys/troupe-github-app/import" {
  capabilities = ["create", "update"]
}

path "transit/keys/troupe-github-app/import_version" {
  capabilities = ["create", "update"]
}

path "transit/sign/troupe-github-app" {
  capabilities = ["create", "update"]
}

path "transit/keys/troupe-github-webhook" {
  capabilities = ["read", "delete"]
}

path "transit/keys/troupe-github-webhook/config" {
  capabilities = ["update"]
}

path "transit/keys/troupe-github-webhook/import" {
  capabilities = ["create", "update"]
}

path "transit/keys/troupe-github-webhook/import_version" {
  capabilities = ["create", "update"]
}

path "transit/hmac/troupe-github-webhook/sha2-256" {
  capabilities = ["create", "update"]
}
POLICY
bao write auth/kubernetes/role/troupe-plane token_policies=troupe-plane-session-tokens,troupe-plane-signing,troupe-plane,troupe-plane-invites,troupe-plane-github

3. Workers and people

Their roles are not the plane's, and the plane cannot check them: a worker pod logs in as troupe-worker (or a role per profile), and a person's daemon at the jwt auth mount as troupe-person. Their policies and roles are in roles-and-permissions.md §8, rendered by the same module.