Files

tegwick 1c1b5c9bc6 Complete IDENTITY-WP-0003 corpus backfill and model refinement

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.

2026-06-21 20:22:20 +02:00

6.0 KiB

Raw Blame History

Keycloak Organizations

Source Type

Product documentation and implementation reference for Keycloak 26+ organization features and core realm/user/group/role model.

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 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

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

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

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

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

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

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

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

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

6.0 KiB Raw Blame History