commerce-canon/research/identity-provisioning/keycloak-organizations.md

# 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