Skip to main content

03 — Identity and access

Identity flow

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​

PrincipalWhereAuthUsed for
Employeetenant orgZitadel login (local, passkey, or federated IdP)go-meet, chat, console
Tenant admintenant org, role tenant_adminsame + MFA enforcedtenant self-service
Operatorplatform orglogin + MFAadmin console
Guestnonego-meet guest session (link/PIN), no Zitadel accountjoining a call
Tenant stack service accounttenant orgJWT profile (private key)token exchange, event callbacks
Control-plane service accountplatform orgJWT profileZitadel management API
Provisionerplatform orgJWT profile, narrow IAM rolescreating 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)​

  1. Browser opens https://meet.acme.<platform-domain>; go-meet redirects to /api/v1.0/oidc/authenticate/.
  2. go-meet builds the authorization request with scopes openid email profile urn:zitadel:iam:org:id:<acme-org-id> and urn:zitadel:iam:org:project:id:<project-id>:aud plus role scope. The org:id scope forces membership in that org; without it Zitadel would fall back to default-org behavior.
  3. If the org has a federated IdP, Zitadel's login redirects to Entra/Okta (org-domain scope can pre-route by domain).
  4. Zitadel returns a code; go-meet exchanges it (PKCE) and calls userinfo.
  5. go-meet validates: issuer, audience (its client id), exp, and that the resource-owner org id equals ZITADEL_ORG_ID configured for this stack, and that the user holds a Fortspace project role. Email domain is never used for authorization.
  6. go-meet creates its own Redis-backed sessionid cookie (HttpOnly, Secure, SameSite=Lax) — unchanged from the prototype.

Claims go-meet expects​

ClaimSourceUse
substandarduser key (meet_user.sub)
email, namestandardprofile
urn:zitadel:iam:user:resourceowner:idrequested scopetenant check (must equal stack's org id)
urn:zitadel:iam:org:project:<pid>:rolesrole scopemap roles → permissions
team idsmapped 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 in internal/domain/identity must 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​

LayerDecisionEnforced by
Who is the user and which tenant?org id + roles in verified tokengo-meet / Tuwunel / console
May this user do X in this room?room/team access tables, owner/admin rolesgo-meet (access domain)
May this stack act on LiveKit room R?R starts with <slug>__ for the caller's verified tenanttoken broker
May this stack touch bucket B?scoped S3 key limited to tenant-<slug>RustFS policy
May this operator do Y?platform-org role + auditcontrol plane + console

Logout and session lifecycle​

  • RP-initiated logout and back-channel logout are implemented in go-meet (logout_token typ logout+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.