generated from coulomb/repo-seed
tegwick
1c1b5c9bc6
Backfill all 23 research source notes with terminology extracts, modeling assumptions, conflicts, canonical mappings, and references. Refresh terminology artifacts, refine the conceptual model with explicit scenario paths, reconcile canon surfaces and open questions, and mark the workplan finished.
5.4 KiB
5.4 KiB
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
- ZITADEL documentation — https://zitadel.com/docs
- ZITADEL Organizations — https://zitadel.com/docs/guides/manage/console/organizations
- ZITADEL Projects and roles — https://zitadel.com/docs/guides/manage/console/projects