coulomb/info-tech-canon
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
info-tech-canon/infospace/assimilation/canon-federation/source/research/identity-provisioning/zitadel-organizations-projects.md
tegwick 372f671eef
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
Distribute frozen federation corpus by concept destination 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a070b5-4994-7271-bd8b-7c3dbcedec4b
2026-09-06 00:44:37 +02:00

5.4 KiB
Raw Blame History

ZITADEL Organizations and Projects

Source Type

Product documentation and implementation reference for ZITADEL's multi-instance organization, project, and grant model.

Domain

Cloud-native IAM, multi-tenancy, B2B SaaS identity, and fine-grained authorization grants.

Why This Source Matters

ZITADEL organizations, projects, roles, grants, and multi-tenancy concepts.

ZITADEL is designed for multi-tenant SaaS from the ground up. Its org → project → grant hierarchy provides a live product vocabulary for separating customer organizations, application projects, and role grants.

Key Concepts

  • Instance: ZITADEL deployment; top-level operational boundary.
  • Organization: primary tenant/customer entity; owns users, projects, policies, and branding.
  • Project: application or service scope within an organization; owns roles, applications, and grants.
  • Application: OIDC/SAML/API client registered under a project.
  • User: human identity within an organization with authentication methods and profile.
  • Machine user / service user: non-human identity for API access.
  • Grant: assignment of project roles to a user or organization (including cross-org grants for B2B).
  • Role: project-scoped permission label granted via grants.
  • Organization domain: verified domain for org discovery and policy.
  • User grant vs. org grant: direct user-to-project role vs. org-wide project access.
  • Actions / Flows: customizable authentication and provisioning pipelines.

Relevant Terminology

Term Source meaning
Organization Customer or business entity; primary multi-tenant partition.
Project Application or product scope within an org.
Grant Role assignment linking user or org to a project.
Role Named capability within a project.
User Human identity record within an organization.
Machine user Service identity for programmatic access.
Application Registered client (OIDC/SAML/API) under a project.
Instance ZITADEL deployment boundary.
Org grant Organization-level access to a project's roles.
Domain verification Proof that an org controls an email domain.

Modeling Assumptions

  • Organization is the primary customer/tenant boundary for users and admin delegation.
  • Project separates applications within an org; roles are project-scoped.
  • Grants are the authorization assignment mechanism, not group membership.
  • Users belong to exactly one organization (per current product model); cross-org access is via grants to shared projects.
  • Machine users are first-class identities distinct from human users.
  • B2B is modeled by granting one organization's project roles to another organization's users or to the org itself.
  • Branding and login policy are org-scoped configuration.

Identity-Canon Implications

  • ZITADEL Organization maps to Organization actor and/or Tenant Scope depending on deployment (often both: org as actor, org as tenant boundary).
  • Project maps to Application Scope or child Scope under tenant.
  • User maps to Account (human); Machine user maps to Service Account.
  • Grant maps to Role assignment via Delegation or Membership-like relationship with authorization implication.
  • Role maps to Role (authorization projection).
  • Application maps to registered client within Application Scope.
  • Domain verification maps to Claim or Evidence Source for org domain ownership.
  • Product vocabulary strongly supports S04 (vendor/customer) and S05 (delegated admin via grants).

Terminology Conflicts

  • Organization vs. Tenant: ZITADEL uses "organization" for what SaaS products often call "tenant."
  • Grant vs. Membership: grants assign roles; no generic group concept at project level.
  • User vs. Account: product says "user" but means org-local identity record with credentials.
  • Project vs. Application: project is container; application is client; both compete with "tenant" in other products.
  • Role vs. Grant: role is definition; grant is assignment; IAM products often collapse these.

Candidate Canonical Mappings

ZITADEL concept Candidate canonical concept
Instance Scope (deployment boundary)
Organization Organization + Tenant Scope
Project Application Scope
User Account
Machine user Service Account
Application Registered client / Application Scope
Role Role (authorization projection)
Grant Role assignment relationship (Delegation-like)
Org grant Membership or Delegation at org level
Domain verification Claim + Evidence Source
User profile Profile

Open Questions

  • When ZITADEL Organization serves as both commercial actor and isolation boundary, should canon use one node with dual typing or separate Organization
    • Tenant linked by Ownership?
  • How should cross-org project grants map: Delegation, Trust, or a vendor-specific Grant Relationship?
  • Does single-org-per-user constraint affect canon modeling of multi-org persons (S02)?
  • Should Machine user always map to Service Account, or sometimes to Artificial Agent?

References