Skip to content

Roles and permissions

Who a caller is, what each role may do, and how each surface decides.

1. Identity comes from the provider

The plane is a plain OIDC relying party and authenticates nobody itself. From a verified token it reads the subject (the claim subject_claim names: sub by default, oid on Entra ID; configuration.md), email, name (else preferred_username), and the groups claim named by groups_claim (a list, or a comma- or space-separated string). Every group named in a token is created on sight and the person's memberships are replaced with the token's list. A token with no groups claim says nothing about groups and leaves memberships alone. A group is not access: access is a team, which a platform admin enables from a group, plus grants on top.

A person signs in at the provider, never at the plane, and the plane turns what comes back into a token of its own:

sequenceDiagram
  participant C as Client
  participant IdP as Identity provider
  participant P as Plane
  participant B as OpenBao
  C->>P: GET /.well-known/troupe
  P-->>C: the issuer, the client id, the endpoints, the scopes
  C->>IdP: device grant (a terminal), or code and PKCE (a browser)
  IdP-->>C: id_token, refresh_token
  C->>P: POST /auth/exchange {id_token}
  Note over P: verify against the provider's keys, read<br/>sub, email, name and the groups claim,<br/>replace the person's memberships
  P->>B: transit sign
  P-->>C: plane token: 15 minutes, the person's teams and scopes
  C->>P: POST /rpc, Bearer plane token
  Note over C: before it runs out: refresh at the provider,<br/>and exchange the new id_token again

The provider's refresh token stays on the client's machine; the plane keeps no credential of the person's. A session's pod gets a token of its own, minted per pod (§5).

SCIM writes the same rows, keyed on externalId (else userName), which must be what later appears as the subject (integrations.md §8). Membership is never edited in Troupe.

2. The admin roles

Role How it is obtained Teams it sees
platform admin the platform_admin_group setting names a group in the person's provider groups — so a fresh plane can have one before any team exists every team
team admin a team_admins row, written by admin.team.admin.add only the teams administered, and only the profiles those are granted
none authenticated, neither of the above; every service principal none

Asking about a team you may not see is not_found, not forbidden, so existence is not leaked; a refusal on role carries data.required_role. No role can read session content: no admin method returns events.

A team admin changes their team's settings with admin.team.update: budget and period, idle timeout, cache eviction, retention (erase_after_days), whether members may control and pin sessions, and the volume's size and class, within the platform's ceilings. Whether a team may be granted a profile nothing enforces (allow_unenforced_workers) is a platform admin's. Neither role renames a team or changes the group it was enabled from: the method takes the settings it declares and leaves anything else it is sent.

3. Service principals

A credential a team owns, subject svc:<team>/<name>, for work nobody starts by hand.

  • Created by a team or platform admin with a subset of the team's granted profiles and a sponsoring person. The 256-bit secret is returned once; only a salted hash is kept.
  • Exchanges {client_id, client_secret} at POST /auth/exchange for the same 15-minute plane token a person gets. Grants, budgets, visibility and retention apply as to a person; it may create and steer sessions on its profiles and fire the triggers that run as it, and call no admin.* method.
  • rotate replaces the secret at once. disable is refused at the next exchange and the next /rpc call. Disabled principals are kept, because their sessions name them.

4. Break-glass

A way in when the identity provider cannot let you in: a misconfigured registration, a tenant outage, a fresh installation with no admin group yet. One token, held in a Secret, is exchanged for a short-lived plane token; the console's sign-in screen does the exchange (Break glass, console.md) and a terminal does it by hand. There is no page of the plane's own behind it.

  • POST /auth/breakglass with {"token": "<the break-glass token>"} answers 200 with token (a plane token), expires_at and subject. The token offered is compared in constant time, and a wrong one is 403 {"error": "refused"}. Unset, the route answers 404 like a path that does not exist, and /.well-known/troupe says "breakglass": false.
  • The plane token carries the claim breakglass, and every /rpc and /mcp call made with it is the platform admin with no teams, marked so in me so a client can say it on every screen. It cannot read a session, as no administrator can.
  • Lives TROUPE_BREAKGLASS_LIFETIME_SECONDS from the exchange, at most the fifteen minutes any plane token may last, which is the default; the expiry is the token's, and nothing refreshes it. When it runs out the console is back at sign-in, and the token is typed again.
  • Administers and no more: admin.* and me answer it, and every other method at /rpc and the agent's door at /mcp/session are forbidden.
  • Audited as admin.breakglass on success and on refusal, with the remote address, under the actor TROUPE_BREAKGLASS_SUBJECT (breakglass), which is the actor its changes are recorded under too.
  • On: a Secret with key token, plane.breakglass.secretName naming it, helm upgrade. Off: secretName: "" and upgrade. Both are rollouts.

5. Session roles and scopes

Session access is separate from administration. A session token's scopes follow the caller's role on the session:

Role Scope May
owner admin everything, including pin, unpin and erase
collaborator control steer: input.send, approval.respond, turn.cancel, …
viewer observe subscribe and read

The owner's admin comes from owning the session (owner_subject), not from a row, so an access-list row naming the owner with a narrower role does not narrow them. Anyone else's role is their ACL row's; failing one, a team-visible session gives a team member control when the team's members_may_control is set, else observe. session.grant is for the owner or a team admin. Revoking a team's grant on a profile freezes its sessions read-only: a running one is put to sleep on its pod, and one still waiting for a worker is never started. Workers re-check the ACL on every command, so a revoked collaborator, or a role narrowed with session.grant, holds at their next command on the pod, whatever the token they hold still says (Decision 859). Widening a role takes effect with their next token, at most 15 minutes later.

Invitations by name (Decision 949, sessions-shared.md):

Method Who What it does
session.invite a pod session's owner or an admin of its team; a private session's owner, from the daemon that seals it observe is a viewer row, control a collaborator row, with who invited whom and when; the invitee is told over their watch, and the log gets session_invited
session.uninvite the same the row goes, the pod refuses their next command, and a private session's copy of its key in their slot is destroyed and what follows is sealed under a new key
session.invites anybody who may see the session, or is invited into it whom it is shared with, at which role
invites.list, people.search anybody signed in the invitations to them; people who share a team with them, or whom a session's profile covers

Only a person the session's profile covers may be invited into a pod session (a member of a team granted that profile, whose rules they then act under), and into a private one, which has no profile, only somebody who shares a team with its owner; a platform admin may be invited into either by anybody. Everybody else is refused with the reason, and a service principal is never invited.

Offering a session one's own signed-in tools (tools.register) takes control. A profile with personalTools: forbid refuses it on its pods, and the platform's managed_mcp_servers_only everywhere (profile-options.md).

6. How each surface authenticates

Surface Credential Actor
Console /console (console.md) the plane token below, from the provider's authorization code with PKCE in the page and /auth/exchange, or from the break-glass door; kept for the browser tab as POST /rpc: the role is worked out on every admin.* call, so no token says "administrator"; anybody the plane knows signs in, and a person with no administrative role is a member, shown only Mine
POST /auth/breakglass (§4) the break-glass token, in the body the platform admin with no teams, as a plane token marked breakglass that lasts the configured lifetime and is not refreshed
/admin, /admin/<page> none nothing is served: a redirect to the console, or on a plane without one a page saying the plane is administered over the admin API
GET /v1/relay/watch a plane token, in initialize; renewed with auth.refresh the person: told the laptop sessions offered to them (remote.changed) as that changes, and nobody else's
POST /rpc Bearer <plane token>, aud = TROUPE_PLANE_AUDIENCE, JWKS from OpenBao subject resolved per request; admin.* to the admin API, everything else to the harness as the person
POST /mcp a plane token, or the provider's own token with aud in client_id, api://<client_id>, <base_url>/mcp a 401 carries WWW-Authenticate … resource_metadata= for OAuth-capable clients
Control channel (TLS on TCP 4001; plaintext too where plane.controlTls.requireTls is off) a projected ServiceAccount token (audience troupe-plane), or a registered machine's secret, over TLS only TokenReview: ServiceAccount troupe-worker, and the namespace decides the profile; a machine's secret in plaintext is refused before it is looked at
POST /mcp/session a plane token the caller, offered four harness tools: session_create, session_get, sessions_list, trigger_fire
POST /trigger/<id> that trigger's own key fires that one trigger as its principal, and nothing else
/scim/v2/* the SCIM bearer (console-minted or TROUPE_SCIM_TOKEN) no person
Worker WebSocket a session token with aud = the pod's worker id token scopes, then the ACL per command
A2A facade Bearer svc:<team>/<name>:<secret>, Basic, or a person's id_token exchanged at /auth/exchange; the facade holds no credential

Nothing a pod says about itself is trusted for its identity.

7. Kubernetes RBAC the chart grants

Subject Rules
plane (Role in troupe-system) workerprofiles, teamvolumes: all verbs, and triggers read (in gitops mode workerprofiles only read and patch, workerprofiles/status patch, and triggers and githubapps read); endpoints, pods: read (libcluster)
plane (ClusterRoles) troupepolicies: read; system:auth-delegator for TokenReview
operator (ClusterRole) troupe.dev resources read and status write; namespaces, service accounts, services, PVCs, PVs, ConfigMaps (a profile's mcpIdentities, none of it secret), Secrets by name only (get, create, patch, delete: the ones a worker namespace mounts, copied from troupe-system; no list or watch), StatefulSets, Ingresses, NetworkPolicies, PDBs, CiliumNetworkPolicies: CRUD; pods: read and delete; events; leases
A2A none; no token mounted

Neither the plane nor A2A has any verb on secrets: the plane never holds a secret value. The plane cannot write TroupePolicy, so a compromised plane can only submit profiles that must still pass admission and the operator.

8. OpenBao policies

Rendered by Troupe.KMS.Policy, so the tested string and the installed one are the same. What the plane's own role must carry, with the lines that write it, is openbao.md, generated from the same module; the workers' and people's policies, which the plane cannot check, are these:

Policy Grants
troupe-worker-<profile> create, read, update on <mount>/data/troupe/teams/<team>/sessions/* and read, list on the metadata path, per granted team; never delete
troupe-person create, read, update on <mount>/data/troupe/people/<name>/* and read, list on its metadata, templated on the name OpenBao's JWT auth vouched for: a person's own daemon, logging in at the jwt auth path with an assertion the plane signs (audience troupe-kms), for their private sessions' keys and their own MCP credentials; and create, nothing else, on <mount>/data/troupe/people/+/invited/*, where the owner of a private session puts its key for a person invited into it, and which only that person reads (Decision 949). Rewrite it when upgrading: a policy written before has no such rule, and inviting anybody into a private session is refused by OpenBao
troupe-worker-mcp-identity update on transit/sign/<the pod's namespace>.*, templated on the namespace Kubernetes auth vouched for (Policy.mcp_identity/2, Decision 747): a pod signs its profile's MCP assertions with the keys named after its own namespace and with no other, never the session-token key

The Kubernetes-auth roles in dev/kind/dependencies.yaml (troupe-worker for the ServiceAccount of that name in any namespace, audience troupe-kms; troupe-plane in troupe-system) are the shape production needs. A worker role whose profiles call an MCP server as themselves also needs troupe-worker-mcp-identity, written once with the Kubernetes auth mount's accessor (bao read -field=accessor sys/auth/kubernetes), as the dev manifest writes it.

One worker role, or one per profile. By default every worker pod logs in as troupe-worker, so whatever policy that role carries is every profile's: the dev manifest gives it one wide policy over every team, troupe-shared-worker, named so that no profile's own policy is called the same. For a pod of one profile to be refused another's session keys, make a role per profile, named as its policy, and turn on bao.workerRolePerProfile. The operator then gives each profile's pods TROUPE_BAO_ROLE=troupe-worker-<profile> and they log in under it (Decision 753):

bao policy write troupe-worker-dev policy-dev.hcl   # Policy.worker/2 for dev's granted teams
bao write auth/kubernetes/role/troupe-worker-dev \
  bound_service_account_names=troupe-worker \
  bound_service_account_namespaces=troupe-w-dev \
  audience=troupe-kms \
  policies=troupe-worker-dev,troupe-worker-mcp-identity \
  ttl=1h

Each role is bound to its profile's namespace alone (<namespacePrefix><profile>), so a pod cannot log in as another profile. Once every pod is on its own role, delete the shared troupe-worker role or take the wide policy off it: a pod names the role it asks for, and a role every namespace may use is one any pod can ask for. troupe-worker-mcp-identity does not change: it is templated on the namespace Kubernetes auth vouched for, not on the role, so the same policy goes on every per-profile role that needs it.

Nothing writes these roles and policies for you, and a profile's policy names its granted teams, so it is written again when they change. Make every profile's role before turning the setting on: a pod given a role OpenBao doesn't have logs no OpenBao token with the role's name and can open no session. The setting changes every profile's pod template, so each profile reports UpgradePending until its pods are replaced. A pod keeps its OpenBao token until shortly before its lease ends, and logs in again once when OpenBao answers 403.

9. The admin methods

apps/troupe_plane/lib/troupe/plane/admin/api.ex is the table: every admin.* method with its arguments, their descriptions and its risk; the role each requires is checked in Troupe.Plane.Admin. The console is built on the same calls, /rpc takes them as JSON-RPC, and /mcp exposes each as a tool named with underscores for dots (admin.team.grant → admin_team_grant). A destructive method takes a confirm argument that must repeat the identifier on /mcp; the console asks in a dialog. Every write is an audit_events row with a diff; a refused change writes nothing.