coulomb/identity-canon
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete IDENTITY-WP-0003 corpus backfill and model refinement

Browse Source 
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.
This commit is contained in:
Bernd Worsch
2026-06-21 20:22:20 +02:00
parent 790a2f2041
commit 1c1b5c9bc6
32 changed files with 2676 additions and 623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
research/identity-provisioning/keycloak-organizations.md
View File

@@ -2,49 +2,137 @@
## Source Type
TODO: Identify whether this is a standard, specification, product documentation, academic concept, architecture pattern, or implementation reference.
Product documentation and implementation reference for Keycloak 26+ organization
features and core realm/user/group/role model.
## Domain
TODO: Classify the source domain.
Multi-tenant IAM, B2B/B2B2C organization management, and OIDC/SAML federation.
## Why This Source Matters
Keycloak organizations, realms, groups, roles, clients, and B2B/B2B2C organization management terminology.
Keycloak organizations, realms, groups, roles, clients, and B2B/B2B2C
organization management terminology.
Keycloak is a widely deployed open-source IAM product. Its newer Organizations
feature adds first-class B2B org semantics on top of the classic realm model,
making it a live vocabulary source for tenant/org/customer overlap.
## Key Concepts
TODO:
- concept 1
- concept 2
- concept 3
- **Realm**: top-level administrative and security namespace; owns users,
clients, identity providers, roles, groups, and authentication flows.
- **User**: realm-local account with credentials, attributes, group/role
mappings, and federation links.
- **Organization** (26+): B2B entity with members, domains, identity providers,
and invited users; supports multi-org membership per user.
- **Organization member**: user linked to an organization with membership
metadata (roles within the org context).
- **Group**: realm-level hierarchical collection for user grouping and role
mapping.
- **Role**: realm role or client role; assigned directly, via group, or via
composite roles.
- **Client**: OIDC/SAML application registered in a realm; may represent a
tenant application or service.
- **Identity Provider (IdP)**: federated authentication source brokering
external identities into realm users.
- **User federation**: LDAP/AD/Kerberos bridge supplying or syncing users.
- **Attribute**: key-value metadata on users, clients, or organizations.
## Relevant Terminology
TODO: Extract terms used by the source and note their source-specific meaning.
| Term | Source meaning |
| --- | --- |
| Realm | Hard identity/admin boundary; separate user namespace per realm. |
| User | Realm-local login account with credentials and profile attributes. |
| Organization | B2B org actor within a realm; has domains, members, and IdP config. |
| Member | User belonging to an organization. |
| Group | Realm hierarchy node; users inherit roles through group membership. |
| Role | Named permission bundle at realm or client scope. |
| Client | Application or service consuming tokens from the realm. |
| Identity Provider | External auth source; may assert identities into realm users. |
| Domain (org) | Email domain associated with an organization for discovery/broker routing. |
| Federated identity | Link between realm user and external IdP identity. |
## Modeling Assumptions
TODO: Capture assumptions made by the source about users, accounts, organizations, tenants, groups, roles, identities, relationships, or credentials.
- **Realm is the primary isolation boundary** for users, credentials, and
admin policy.
- **User means account** in product vocabulary; one realm user per login
identity within that realm.
- **Organization is a B2B overlay** within a realm, not a replacement for
realm or tenant infrastructure boundaries.
- **Groups carry authorization semantics** through role mapping, not just
social grouping.
- **Roles are permission bundles**, assignable directly or transitively via
groups and composites.
- **Federation links** connect external IdP identities to local users via
brokered login.
- **Multi-org membership** is supported: one user can belong to multiple
organizations in the same realm.
## Identity-Canon Implications
TODO: Explain what this source suggests for the canonical identity model.
- Keycloak **Realm** maps to **Realm** (Scope specialization) with hard
namespace boundaries.
- Keycloak **User** maps to **Account** in a realm Scope; not **Natural
Person**.
- Keycloak **Organization** maps to **Organization** collective actor with
**Membership Relationship** to member Accounts.
- **Group** maps to **Group** with Membership edges; role inheritance is
authorization projection.
- **Role** maps to **Role** (authorization projection), not membership.
- **Client** maps to application **Scope** or registered resource in
authorization domain.
- **Federated identity** link maps to **Synonymity Assertion** or
**Identifier Binding** between external IdP identifier and local Account.
- **Domain** on organization is an **Identifier** used for discovery routing.
- Supports scenarios S03 (enterprise orgs), S04 (vendor/customer B2B), S05
(delegated admins via roles/groups).
## Terminology Conflicts
TODO: Record where this source uses terms differently from other sources.
- **Realm vs. Tenant**: Keycloak realm is both issuer namespace and admin
partition; products often call this "tenant."
- **User vs. Member**: org member is still a realm User; membership is a
relationship overlay.
- **Organization vs. Group**: both exist; org has B2B semantics (domains, IdP),
group is generic hierarchy.
- **Role vs. Membership**: group membership implies role inheritance;
conflates relationship types.
- **Client vs. Tenant**: clients are applications, not customer isolation
boundaries.
## Candidate Canonical Mappings
TODO: Map source-specific concepts to identity-canon candidate concepts.
| Keycloak concept | Candidate canonical concept |
| --- | --- |
| Realm | Realm (Scope) |
| User | Account |
| Organization | Organization |
| Organization membership | Membership Relationship |
| Group | Group |
| Group membership | Membership Relationship |
| Role (realm/client) | Role (authorization projection) |
| Client | Application Scope / registered client |
| Identity Provider | Trust Relationship + external issuer Scope |
| Federated identity link | Synonymity Assertion / Identifier Binding |
| User attribute | Profile attribute or Claim |
| Organization domain | Identifier (email domain) |
## Open Questions
TODO:
- Question 1
- Question 2
- Should Keycloak Realm remain a **Realm** specialization or absorb **Tenant**
semantics when used as SaaS isolation?
- How should multi-org user membership be modeled when the same Account holds
Membership edges to multiple Organizations?
- Does Keycloak Organization domain verification warrant a **Claim** or
**Evidence Source** in canon?
- Should composite roles be modeled as Role aggregation or as derived
authorization projection only?
## References
TODO: Add canonical URLs, RFC/spec identifiers, documentation links, and citation notes.
- Keycloak Organizations documentation — https://www.keycloak.org/docs/latest/server_admin/#_organizations
- Keycloak Server Administration Guide — https://www.keycloak.org/docs/latest/server_admin/
- Keycloak Realm concepts — https://www.keycloak.org/docs/latest/server_admin/#_create-realm

114
research/identity-provisioning/ldap-rfc4519-inetorgperson-rfc2798.md
View File

@@ -1,50 +1,130 @@
# Ldap Rfc4519 Inetorgperson Rfc2798
# LDAP RFC 4519 and inetOrgPerson RFC 2798
## Source Type
TODO: Identify whether this is a standard, specification, product documentation, academic concept, architecture pattern, or implementation reference.
Standard. RFC 4519 defines LDAP attribute types and object classes; RFC 2798
defines the `inetOrgPerson` auxiliary object class for Internet person entries.
## Domain
TODO: Classify the source domain.
Directory services, enterprise identity records, and hierarchical naming.
## Why This Source Matters
LDAP directory schema, RFC 4519 attribute/object class vocabulary, and inetOrgPerson RFC 2798.
LDAP directory schema, RFC 4519 attribute/object class vocabulary, and
inetOrgPerson RFC 2798.
LDAP remains the structural backbone of many enterprise directories. Its
distinguished names, organizational units, and groupOfNames semantics
precede and often underpin SCIM and IAM product models.
## Key Concepts
TODO:
- concept 1
- concept 2
- concept 3
- **Directory Information Tree (DIT)**: hierarchical namespace of entries
identified by Distinguished Names (DNs).
- **Entry**: a collection of attribute type/value pairs with one structural
object class and optional auxiliary object classes.
- **Distinguished Name (DN)**: unique identifier within a directory; composed
of Relative Distinguished Names (RDNs) such as `cn`, `ou`, `dc`.
- **inetOrgPerson**: auxiliary object class for person entries with `cn`,
`sn`, `mail`, `uid`, `employeeNumber`, and related attributes.
- **organizationalUnit (ou)**: container for organizational structure.
- **groupOfNames / groupOfUniqueNames**: group entries with `member` or
`uniqueMember` attributes referencing member DNs.
- **posixAccount / posixGroup**: UNIX-oriented account and group semantics
with `uid`, `gid`, `homeDirectory`, and `memberUid`.
- **Attribute syntax and matching rules**: typed attributes (DirectoryString,
IA5String, JPEG) with defined comparison semantics.
- **Referrals and aliases**: indirection for distributed or aliased entries.
## Relevant Terminology
TODO: Extract terms used by the source and note their source-specific meaning.
| Term | Source meaning |
| --- | --- |
| person / inetOrgPerson | Directory entry representing a human; attributes, not a login session. |
| uid | User identifier string; often login name in POSIX contexts. |
| cn (commonName) | Display or legal name component of DN. |
| mail | Email address attribute; may be multi-valued. |
| employeeNumber | Workforce identifier assigned by employer. |
| ou (organizationalUnit) | Structural container in the DIT; department or division. |
| dc (domainComponent) | DNS-domain component in DN; defines directory partition. |
| member / uniqueMember | DN reference from a group entry to a member entry. |
| groupOfNames | Group requiring at least one member; membership by DN reference. |
| account (posixAccount) | UNIX account attributes bound to a person entry. |
## Modeling Assumptions
TODO: Capture assumptions made by the source about users, accounts, organizations, tenants, groups, roles, identities, relationships, or credentials.
- **Identity is entry-centric**: a person is a directory entry located in a
hierarchical tree, not a free-floating actor.
- **Naming implies structure**: DN path encodes organizational placement
(`ou=Engineering,ou=People,dc=example,dc=com`).
- **Groups are entries**, not relationships; membership is an attribute on the
group entry pointing to member DNs.
- **Person and account can co-reside** on one entry (inetOrgPerson +
posixAccount auxiliary class).
- **Uniqueness** is per-directory-partition; `uid` or DN must be unique within
scope.
- **No standard org-entity object class** for corporations; org structure is
implied by `ou` containers.
- **Authorization** is external; groups are conventionally mapped to permission
sets by consuming applications.
## Identity-Canon Implications
TODO: Explain what this source suggests for the canonical identity model.
- LDAP **inetOrgPerson entry** maps to **Identity Record** with optional
**Account** when posixAccount or login-binding attributes are present.
- **DN** and **uid** are **Identifiers** within the directory **Scope**
(namespace).
- **organizationalUnit** maps to a structural container, candidate
**Organization Unit** or scope partition — not automatically an
**Organization** actor.
- **groupOfNames** maps to **Group** with **Membership Relationship** via
member DN references.
- DN hierarchy suggests **Affiliation** or structural relationships but LDAP
does not type them explicitly.
- LDAP reinforces that **Identifier** (DN) carries locational semantics
beyond bare value identity.
## Terminology Conflicts
TODO: Record where this source uses terms differently from other sources.
- **Account**: posixAccount is attribute bundle on a person entry; conflicts
with IAM Account as a distinct operational record.
- **User**: directory "user" means entry or uid; conflicts with application
session user.
- **Organization**: `ou` is a container, not a legal or commercial org actor.
- **Group**: LDAP group is an entry with member attributes; conflicts with
SCIM Group resource and social community.
- **Person**: inetOrgPerson is a schema label, not a legal natural-person
assertion.
## Candidate Canonical Mappings
TODO: Map source-specific concepts to identity-canon candidate concepts.
| LDAP concept | Candidate canonical concept |
| --- | --- |
| inetOrgPerson entry | Identity Record |
| posixAccount attributes | Account (co-located on same entry) |
| DN | Identifier (locator + namespace) |
| uid, mail, employeeNumber | Identifier |
| organizationalUnit (ou) | Scope partition or org-unit container |
| groupOfNames entry | Group |
| member / uniqueMember | Membership Relationship |
| dc partition | Scope / Namespace |
| attribute values | Profile attributes or Claims on Identity Record |
## Open Questions
TODO:
- Question 1
- Question 2
- Should DN be modeled as a compound Identifier (locator + value) or split
into Namespace Scope plus local Identifier?
- How should multi-valued `mail` attributes interact with synonymity assertions
when matching across systems?
- Does `ou` hierarchy warrant a canonical **Organizational Structure**
relationship type, or remain a naming convention?
- When inetOrgPerson and posixAccount coexist, is one Identity Record with
Account facet sufficient?
## References
TODO: Add canonical URLs, RFC/spec identifiers, documentation links, and citation notes.
- RFC 4519: LDAP Attribute Types and Object Classes — https://datatracker.ietf.org/doc/html/rfc4519
- RFC 2798: Definition of the inetOrgPerson Object Class — https://datatracker.ietf.org/doc/html/rfc2798
- RFC 4511: LDAP Protocol — https://datatracker.ietf.org/doc/html/rfc4511
- RFC 2307: POSIX account/group schema — https://datatracker.ietf.org/doc/html/rfc2307

122
research/identity-provisioning/ory-kratos-keto.md
View File

@@ -1,50 +1,138 @@
# Ory Kratos Keto
# Ory Kratos and Keto
## Source Type
TODO: Identify whether this is a standard, specification, product documentation, academic concept, architecture pattern, or implementation reference.
Product documentation and open-source implementation reference for Ory Kratos
(identity management) and Ory Keto (relationship-based authorization).
## Domain
TODO: Classify the source domain.
Cloud-native identity management, self-service flows, and ReBAC authorization
separation.
## Why This Source Matters
Ory Kratos identity/user management and Ory Keto relationship-based authorization separation.
Ory Kratos identity/user management and Ory Keto relationship-based
authorization separation.
Ory explicitly separates identity management (Kratos) from authorization
(Keto). This architectural split is a strong reference for identity-canon's
P6 principle (authorization projections separate from identity model).
## Key Concepts
TODO:
- concept 1
- concept 2
- concept 3
- **Identity (Kratos)**: core identity record with traits (schema-defined
attributes), credentials, verifiable addresses, and recovery settings.
- **Traits**: JSON attributes on an identity (email, name, etc.) governed by
identity schema.
- **Credential**: password, OIDC link, TOTP, WebAuthn, or lookup secret
attached to an identity.
- **Identity schema**: JSON Schema defining allowed traits and validation.
- **Session**: authenticated session bound to an identity after credential
verification.
- **Recovery / Verification flow**: self-service processes for account
recovery and address verification.
- **Relation tuple (Keto)**: `namespace:object#relation@subject` assertion
for ReBAC checks.
- **Namespace (Keto)**: typed object class in the authorization model with
defined relations and permissions.
- **Subject (Keto)**: entity in a relation tuple; may reference a Kratos
identity or arbitrary identifier.
- **Permission check**: evaluate whether a subject has a relation to an
object in a namespace.
## Relevant Terminology
TODO: Extract terms used by the source and note their source-specific meaning.
| Term | Source meaning |
| --- | --- |
| Identity | Kratos record with traits and credentials; not authorization entity. |
| Traits | Schema-validated attributes on an identity. |
| Credential | Authentication factor bound to identity. |
| Session | Active authenticated state for an identity. |
| Schema | JSON Schema defining identity trait structure per use case. |
| Relation tuple | Subject-relation-object fact in Keto. |
| Namespace | Authorization object type with relation definitions. |
| Subject | Authorization participant in a tuple. |
| Object | Resource or entity being authorized in a tuple. |
| Relation | Named edge type between subject and object. |
## Modeling Assumptions
TODO: Capture assumptions made by the source about users, accounts, organizations, tenants, groups, roles, identities, relationships, or credentials.
- **Identity and authorization are separate services** with distinct storage
and APIs.
- **Identity means traits + credentials**, not permissions.
- **Traits are schema-driven**, allowing multiple identity schemas per
deployment (consumer vs. admin personas).
- **Sessions are ephemeral** authentication state, not identity records.
- **Authorization uses Zanzibar-style tuples** in Keto, not Kratos groups or
roles.
- **Subjects in Keto may not map 1:1** to Kratos identities; integration is
application-level.
- **No first-class organization or tenant** in Kratos core; multi-tenancy is
application concern.
## Identity-Canon Implications
TODO: Explain what this source suggests for the canonical identity model.
- Kratos **Identity** maps to **Identity Record** with **Profile** (traits)
and **Credential** attachments.
- Kratos does not use "account" explicitly; Identity is closer to Account +
Profile combined.
- **Session** is ephemeral auth state, not a canonical entity; maps to
downstream session projection.
- **Identity schema** maps to schema governance for Profile/Identity Record
attributes in a Scope.
- Keto **relation tuple** maps to **Relationship Tuple** (authorization
projection) or typed **Relationship** with authz implication.
- Keto **namespace** maps to **Authorization Domain** Scope.
- Keto **subject** maps to **Authorization Principal** projection.
- Strong evidence for **P6**: identity store and authorization graph are
orthogonal.
- Supports S01 (single local identity), S10 (service identity via traits +
credentials), S11 (agent via separate Keto tuples).
## Terminology Conflicts
TODO: Record where this source uses terms differently from other sources.
- **Identity**: Kratos Identity is a record with credentials; conflicts with
bare "identity" meaning personhood or issuer subject.
- **Subject**: Keto subject is authorization participant; OIDC subject is
issuer identifier; different layers.
- **Traits vs. Profile**: traits are stored attributes; profile is
presentation — often conflated in Kratos.
- **Namespace**: Keto namespace is authorization object type; DNS/LDAP
namespace is naming scope.
- **No user term**: Kratos avoids "user" in API, but docs sometimes use it
informally.
## Candidate Canonical Mappings
TODO: Map source-specific concepts to identity-canon candidate concepts.
| Ory concept | Candidate canonical concept |
| --- | --- |
| Kratos Identity | Identity Record + Account facet |
| Traits | Profile attributes |
| Credential | Credential |
| Session | Ephemeral auth projection (non-canonical) |
| Identity schema | Profile/record schema in Scope |
| Keto relation tuple | Relationship Tuple (authorization projection) |
| Keto namespace | Authorization Domain Scope |
| Keto subject | Authorization Principal |
| Keto object | Authorization Resource |
| Keto relation | Relationship type (authz) |
| Verification flow | Evidence Source event |
## Open Questions
TODO:
- Question 1
- Question 2
- Should Kratos Identity be split into Account + Profile in canon, or kept
as unified Identity Record?
- How should Keto subjects that reference non-Kratos identifiers (e.g.,
`group:engineering#member`) map to canonical Group + Membership?
- Does Kratos multi-schema support (consumer vs. admin) map to Persona or
separate Identity Records?
- Should session be documented as a projection type in canon or remain
explicitly out of scope?
## References
TODO: Add canonical URLs, RFC/spec identifiers, documentation links, and citation notes.
- Ory Kratos documentation — https://www.ory.sh/docs/kratos/
- Ory Keto documentation — https://www.ory.sh/docs/keto/
- Ory Kratos identity model — https://www.ory.sh/docs/kratos/manage-user-identities/identity-schema
- Ory Keto relation tuples — https://www.ory.sh/docs/keto/concepts/relation-tuples

115
research/identity-provisioning/scim-rfc7643-rfc7644.md
View File

@@ -1,50 +1,133 @@
# Scim Rfc7643 Rfc7644
# SCIM RFC 7643 and RFC 7644
## Source Type
TODO: Identify whether this is a standard, specification, product documentation, academic concept, architecture pattern, or implementation reference.
Standard. RFC 7643 defines the SCIM 2.0 core schema; RFC 7644 defines the
SCIM 2.0 protocol for provisioning.
## Domain
TODO: Classify the source domain.
Identity provisioning and directory synchronization.
## Why This Source Matters
SCIM 2.0: RFC 7643 schema and RFC 7644 protocol.
SCIM is the dominant platform-neutral provisioning baseline. It defines
resource types, attribute schemas, and CRUD/search operations for users and
groups without prescribing authentication or authorization semantics.
## Key Concepts
TODO:
- concept 1
- concept 2
- concept 3
- **Resource**: a provisionable object with a `schemas` array, `id`, `meta`,
and typed attributes.
- **User resource**: a person-oriented identity record with `userName`,
`name`, `emails`, `phoneNumbers`, `addresses`, `groups`, `roles`, and
`active` lifecycle state.
- **Group resource**: a named collection with `displayName`, `members`, and
optional `type` (direct or indirect membership).
- **Enterprise User extension** (RFC 7643 §4.3): adds `employeeNumber`,
`costCenter`, `organization`, `division`, `department`, and `manager` for
workforce semantics.
- **Service Provider Config**: exposes supported features, authentication
schemes, and bulk limits.
- **Meta block**: `resourceType`, `created`, `lastModified`, `version`,
`location` — lifecycle and versioning metadata on every resource.
- **Operations**: Create, Read, Update, Delete, Search (POST /Users/.search),
and Bulk (RFC 7644 §3.7).
- **PatchOp**: partial updates via `add`, `remove`, `replace` on paths.
- **ExternalId**: cross-system correlation identifier supplied by the client.
## Relevant Terminology
TODO: Extract terms used by the source and note their source-specific meaning.
| Term | Source meaning |
| --- | --- |
| User | A provisionable identity record; not necessarily a login account in the consuming system. |
| Group | A named collection of members; may represent authorization, organizational, or mailing-list grouping. |
| userName | Unique identifier within the service provider's namespace; often used as login handle. |
| externalId | Client-supplied correlation key for linking to an upstream system of record. |
| active | Boolean lifecycle flag; inactive users retain the record but should lose access. |
| member | Reference (`value`, `display`, `$ref`) to a User or Group in a Group's membership list. |
| organization (extension) | Free-text employer or org name on a user; not a structured org resource. |
| manager | Reference to another User who manages this user. |
| roles | Application-specific role strings on the User resource; not RBAC policy. |
| Service Provider | The system receiving provisioned resources. |
| Client | The system sending provisioning requests. |
## Modeling Assumptions
TODO: Capture assumptions made by the source about users, accounts, organizations, tenants, groups, roles, identities, relationships, or credentials.
- A **User** is the primary provisionable identity record; there is no separate
Account or Person resource type in core SCIM.
- **Groups** absorb membership semantics; there is no first-class relationship
tuple beyond group membership references.
- **Organization structure** is flattened into user attributes (department,
division, organization) rather than modeled as org entities.
- **Lifecycle** is binary (`active` true/false) with soft-disable semantics;
deletion is a separate operation.
- **Uniqueness** is scoped to the service provider; `userName` must be unique
within the SP namespace.
- **Authorization** is out of scope; `roles` and group membership are hints
that downstream systems may map to policies.
- **Multi-tenancy** is not defined; tenant isolation is an implementation
concern of the service provider.
## Identity-Canon Implications
TODO: Explain what this source suggests for the canonical identity model.
- SCIM **User** maps to **Identity Record** (and often **Account** when the
SP uses it for login), not to **Natural Person**.
- SCIM **Group** maps to **Group** collective actor with **Membership
Relationship** edges to member records.
- `userName` and `externalId` are **Identifiers** within the SP **Scope**.
- `active` maps to **Lifecycle State** on the Identity Record.
- Enterprise extension `manager` suggests a **Representation** or reporting
relationship, but SCIM does not type it beyond a User reference.
- `organization`, `department`, `division` are attribute-level hints, not
**Organization** actors; canon should not treat them as structured org graphs.
- SCIM reinforces **P2** (person ≠ account) and **P5** (membership explicit)
but lacks actor-layer primitives.
## Terminology Conflicts
TODO: Record where this source uses terms differently from other sources.
- **User**: SCIM User is a record, not a human being. Conflicts with
application "user" meaning login session holder.
- **Group**: SCIM Group may mean LDAP security group, mailing list, or org
unit depending on deployment; conflicts with social **Community**.
- **Role**: SCIM `roles` are opaque strings; conflicts with Cedar/OpenFGA
relationship-based roles and IAM permission bundles.
- **Organization**: SCIM extension `organization` is a string attribute;
conflicts with **Organization** collective actor in IAM products.
- **Active**: boolean disable vs. full lifecycle states (suspended, archived)
used in enterprise directories.
## Candidate Canonical Mappings
TODO: Map source-specific concepts to identity-canon candidate concepts.
| SCIM concept | Candidate canonical concept |
| --- | --- |
| User resource | Identity Record (+ Account when login-enabled) |
| Group resource | Group |
| member reference | Membership Relationship |
| userName | Identifier |
| externalId | Identifier (cross-system correlation) |
| active | Lifecycle State |
| manager (extension) | Representation Relationship (weakly typed) |
| organization/department/division | Affiliation hints; not Organization actors |
| roles (extension) | Role labels; authorization projection input |
| meta.created/lastModified | Evidence timestamps for record provenance |
| Service Provider namespace | Scope |
## Open Questions
TODO:
- Question 1
- Question 2
- Should SCIM `externalId` be modeled as a dedicated **Identifier Binding**
or a generic Identifier with source metadata?
- How should indirect group membership (`type: indirect`) map to canon
membership vs. inherited authorization projection?
- Does the Enterprise User `manager` reference warrant a canonical
**Reporting Relationship** distinct from Representation?
- Should a SCIM-only deployment without login map User exclusively to
Identity Record, skipping Account?
## References
TODO: Add canonical URLs, RFC/spec identifiers, documentation links, and citation notes.
- RFC 7643: SCIM 2.0 Core Schema — https://datatracker.ietf.org/doc/html/rfc7643
- RFC 7644: SCIM 2.0 Protocol — https://datatracker.ietf.org/doc/html/rfc7644
- IETF SCIM working group overview — https://datatracker.ietf.org/wg/scim/about/

112
research/identity-provisioning/zitadel-organizations-projects.md
View File

@@ -1,50 +1,130 @@
# Zitadel Organizations Projects
# ZITADEL Organizations and Projects
## Source Type
TODO: Identify whether this is a standard, specification, product documentation, academic concept, architecture pattern, or implementation reference.
Product documentation and implementation reference for ZITADEL's multi-instance
organization, project, and grant model.
## Domain
TODO: Classify the source 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
TODO:
- concept 1
- concept 2
- concept 3
- **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
TODO: Extract terms used by the source and note their source-specific meaning.
| 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
TODO: Capture assumptions made by the source about users, accounts, organizations, tenants, groups, roles, identities, relationships, or credentials.
- **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
TODO: Explain what this source suggests for the canonical identity model.
- 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
TODO: Record where this source uses terms differently from other sources.
- **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
TODO: Map source-specific concepts to identity-canon candidate concepts.
| 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
TODO:
- Question 1
- Question 2
- 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
TODO: Add canonical URLs, RFC/spec identifiers, documentation links, and citation notes.
- 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