03 — Identity and access

One Zitadel instance (v4.x, deployed per deployment/compose.zitadel.yaml)
serves all tenants. It replaces the Keycloak draft.
Zitadel structure
Instance (single issuer: https://id.<platform-domain>)
├─ Org: fortspace-platform operators, control-plane + admin-console apps, service accounts
├─ Org: acme users, service accounts, optional Entra/Okta IdP, MFA policy
├─ Org: globex ...
└─ Project: Fortspace (owned by platform org)
├─ roles: tenant_admin, member, team_lead (extensible)
├─ Applications: meet-web (PKCE), chat (OIDC), admin-console, ...
└─ Project grant → each tenant org, restricted to the roles the tenant may delegate
Facts that shape the design (verified against Zitadel docs):
- A user belongs to exactly one org and cannot be moved. The same email may exist in two orgs as two accounts.
- One domain can be verified on only one org. Domain → org routing is an
application responsibility — the control plane keeps
tenant_domains. - Orgs are not separate issuers; branding/policies are overridable per org, the issuer is shared.
- Do not reuse Zitadel's default project; create a provider-owned one and grant it to orgs. "Require project grant / role on authentication" is a deliberate setting and is on for Fortspace apps.
- External IdPs (Entra ID, Okta, SAML) are configured on the tenant org; auto-create/auto-link policies are separate and default to off.
Principals
| Principal | Where | Auth | Used for |
|---|---|---|---|
| Employee | tenant org | Zitadel login (local, passkey, or federated IdP) | go-meet, chat, console |
| Tenant admin | tenant org, role tenant_admin | same + MFA enforced | tenant self-service |
| Operator | platform org | login + MFA | admin console |
| Guest | none | go-meet guest session (link/PIN), no Zitadel account | joining a call |
| Tenant stack service account | tenant org | JWT profile (private key) | token exchange, event callbacks |
| Control-plane service account | platform org | JWT profile | Zitadel management API |
| Provisioner | platform org | JWT profile, narrow IAM roles | creating orgs/projects/grants |
No resource-owner-password grant exists in Zitadel; interactive clients use
authorization code + PKCE. go-meet already supports this as a public client
(OIDC_USE_PKCE=true, no client_secret; production startup refuses a public
client without PKCE — see go-meet/AUTH.md).
Login flow (browser)
- Browser opens
https://meet.acme.<platform-domain>; go-meet redirects to/api/v1.0/oidc/authenticate/. - go-meet builds the authorization request with scopes
openid email profile urn:zitadel:iam:org:id:<acme-org-id>andurn:zitadel:iam:org:project:id:<project-id>:audplus role scope. Theorg:idscope forces membership in that org; without it Zitadel would fall back to default-org behavior. - If the org has a federated IdP, Zitadel's login redirects to Entra/Okta (org-domain scope can pre-route by domain).
- Zitadel returns a code; go-meet exchanges it (PKCE) and calls userinfo.
- go-meet validates: issuer, audience (its client id),
exp, and that the resource-owner org id equalsZITADEL_ORG_IDconfigured for this stack, and that the user holds a Fortspace project role. Email domain is never used for authorization. - go-meet creates its own Redis-backed
sessionidcookie (HttpOnly, Secure, SameSite=Lax) — unchanged from the prototype.
Claims go-meet expects
| Claim | Source | Use |
|---|---|---|
sub | standard | user key (meet_user.sub) |
email, name | standard | profile |
urn:zitadel:iam:user:resourceowner:id | requested scope | tenant check (must equal stack's org id) |
urn:zitadel:iam:org:project:<pid>:roles | role scope | map roles → permissions |
| team ids | mapped from groups/roles → OIDC_TEAM_IDS_CLAIM (default team_ids) | team-based access rows |
The prototype's claim handling targets Keycloak naming (
team_ids). A small adapter ininternal/domain/identitymust map Zitadel role claims into the team claim (tracked in 11, Q-04).
Machine-to-machine auth
tenant go-meet ── JWT profile (aud=Zitadel issuer, sub=svc-account) ─▶ Zitadel token endpoint
◀── access token (resource owner = acme org) ──
tenant go-meet ── Bearer ───────────────────────────────────────────▶ Control plane
control plane verifies: issuer, audience, signature (JWKS),
resource-owner org id == tenants.zitadel_org_id, slug matches
the requested room prefix, service-account role.
Each tenant stack gets one service account in its own org (key stored in
Infisical /tenants/<slug>/meet/zitadel_sa_key, injected as a file). Rotating
the key = new Zitadel key + Infisical update + redeploy; old key deleted last.
Authorization layers
| Layer | Decision | Enforced by |
|---|---|---|
| Who is the user and which tenant? | org id + roles in verified token | go-meet / Tuwunel / console |
| May this user do X in this room? | room/team access tables, owner/admin roles | go-meet (access domain) |
| May this stack act on LiveKit room R? | R starts with <slug>__ for the caller's verified tenant | token broker |
| May this stack touch bucket B? | scoped S3 key limited to tenant-<slug> | RustFS policy |
| May this operator do Y? | platform-org role + audit | control plane + console |
Logout and session lifecycle
- RP-initiated logout and back-channel logout are implemented in go-meet
(
logout_tokentyplogout+jwt, replay cache). Zitadel must be configured to send back-channel logout per application. - Suspending a tenant: control plane deactivates the org (Zitadel blocks new logins), and instructs go-meet to flush sessions; existing LiveKit tokens die within their TTL.
Customer SSO onboarding (self-service)
Tenant admin (console) → "Connect Entra ID / SAML" → control plane calls
Zitadel to add the IdP on the org, verifies the domain, stores the domain in
tenant_domains, and enables login routing. Failures are surfaced; the IdP is
only activated after a test login by the admin.