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.
130 lines
5.4 KiB
Markdown
130 lines
5.4 KiB
Markdown
# 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 |