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}atPOST /auth/exchangefor 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 noadmin.*method. rotatereplaces the secret at once.disableis refused at the next exchange and the next/rpccall. 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/breakglasswith{"token": "<the break-glass token>"}answers200withtoken(a plane token),expires_atandsubject. The token offered is compared in constant time, and a wrong one is403 {"error": "refused"}. Unset, the route answers 404 like a path that does not exist, and/.well-known/troupesays"breakglass": false.- The plane token carries the claim
breakglass, and every/rpcand/mcpcall made with it is the platform admin with no teams, marked so inmeso a client can say it on every screen. It cannot read a session, as no administrator can. - Lives
TROUPE_BREAKGLASS_LIFETIME_SECONDSfrom 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.*andmeanswer it, and every other method at/rpcand the agent's door at/mcp/sessionareforbidden. - Audited as
admin.breakglasson success and on refusal, with the remote address, under the actorTROUPE_BREAKGLASS_SUBJECT(breakglass), which is the actor its changes are recorded under too. - On: a Secret with key
token,plane.breakglass.secretNamenaming 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.