Organization Behavior Specification: Multi-Domain + Multi-IdP (M:N Domains) #49091

vramik · 2026-05-19T10:09:31Z

vramik
May 19, 2026
Collaborator

Context

This is a behavioral specification for Keycloak Organizations when three enhancements are implemented together:

Support multiple mail domains for linked IDPs per organization #47554 — Per-domain IdP routing (with DOMAIN.IDP_ID foreign key)
Organizations: Assign Identity Provider to more than one organization. #31705 — Shared IdPs across orgs (using ORG_IDENTITY_PROVIDER join table with auto_membership and membership_type)
Domain as a first-class entity with domain-level settings (auto-redirect, IdP routing), each domain belonging to exactly one org

Two core design principles:

Domain tells you HOW to authenticate (which IdP), not WHICH ORG you're in. IdP routing and org context are decoupled.
Auto-membership requires domain affinity. A shared IdP alone does not create org membership — the user's email domain must also be claimed by the org (unless the org has no domains).

Updated 2026-08-26 — incorporated feedback from @wschomburg, @bcmedeiros, and @jthimonier. See changelog comment for details.

Updated 2026-09-10 — V4: incorporated feedback from @pedroigor — each domain belongs to exactly one org (1:1), removing M:N domain sharing. Domain remains a first-class entity with domain-level settings. See comment and V4 diff summary.

Legend

Symbol	Meaning
Org-A, Org-B	Organizations
IdP-X, IdP-Y	Identity Providers
AM=T/F	auto_membership true/false on org-IdP association
MT=M/U	membership_type MANAGED/UNMANAGED on association
AR=T/F	auto_redirect true/false on domain (controls automatic IdP redirect)
d1, d2	Email domains (e.g., acme.com, globex.com)

Data Model

  ORG_DOMAIN (first-class entity — one row per domain name per realm)
  - ID              VARCHAR(36)  PK
  - NAME            VARCHAR(255) NOT NULL
  - VERIFIED        BOOLEAN      DEFAULT FALSE
  - REALM_ID        VARCHAR(255) NOT NULL
  - ORG_ID          VARCHAR(255) NOT NULL, FK → ORG.ID, ON DELETE CASCADE
  - IDP_ID          VARCHAR(36)  nullable, FK → IDENTITY_PROVIDER.INTERNAL_ID, ON DELETE SET NULL
  - AUTO_REDIRECT   BOOLEAN      DEFAULT FALSE
  - UNIQUE(REALM_ID, NAME)
  
    Each domain belongs to exactly one org (1:1 via ORG_ID FK).
    IDP_ID is an optional routing overlay — NULL means no federated IdP
    (password form shown). ON DELETE SET NULL clears routing when an IdP
    is deleted without losing the domain itself.
    AUTO_REDIRECT controls whether users matching this domain are automatically
    redirected to the IdP (true) or shown the login page with the IdP as an
    option (false). Replaces the old per-IdP kc.org.broker.redirect.mode.email-matches config.

ORG_IDENTITY_PROVIDER (M:N join table — from #31705)
  - ORGANIZATION_ID       VARCHAR(36)  FK → ORG.ID, ON DELETE CASCADE
  - IDENTITY_PROVIDER_ID  VARCHAR(255) FK → IDENTITY_PROVIDER.INTERNAL_ID, ON DELETE CASCADE
  - AUTO_MEMBERSHIP       BOOLEAN      DEFAULT TRUE
  - MEMBERSHIP_TYPE       VARCHAR(255) DEFAULT 'UNMANAGED'
  - PK(ORGANIZATION_ID, IDENTITY_PROVIDER_ID)

IDENTITY_PROVIDER
  - ORGANIZATION_ID column REMOVED (replaced by join table)

Constraints:

C1: At most one org per IdP can have MT=MANAGED (prevents dual lifecycle ownership)
C2: AM=false + MT=MANAGED is invalid (MANAGED requires auto-membership)
C3: DOMAIN.IDP_ID must reference a valid IDENTITY_PROVIDER (FK constraint, ON DELETE SET NULL)
C4: Domain name is unique per realm — UNIQUE(REALM_ID, NAME) — each domain belongs to exactly one org

Two Decoupled Concerns

Concern	Question answered	Source of truth	Ambiguity possible?
IdP routing	"How does this user authenticate?"	`DOMAIN.IDP_ID` (domain → IdP)	No — one IDP_ID per domain by design
Org context	"Which org is this login for?"	Membership, `organization:alias` scope, user selection	Yes — user may belong to multiple orgs

IdP Routing (domain → IdP)

Lookup for a given email domain:

Find ORG_DOMAIN row matching that domain (or wildcard — most specific wins)
If IDP_ID is set AND AUTO_REDIRECT is true → automatically redirect to that IdP
If IDP_ID is set AND AUTO_REDIRECT is false → show login page with the IdP as an option (no automatic redirect)
If IDP_ID is NULL → no federated IdP → show password form

No need to check multiple rows per domain — ORG_DOMAIN.NAME is unique per realm.

AUTO_REDIRECT replaces the old per-IdP kc.org.broker.redirect.mode.email-matches config. Moving it to the domain allows different redirect behavior per domain — e.g., acme.com auto-redirects to EntraID while partner.com shows a login page with multiple IdP options.

Org Context Resolution

After IdP callback, the system determines org context.

Resolution priority:

Client requested organization:alias → use that org
Auth session note ORGANIZATION_ATTRIBUTE → set by previous step (e.g., org login page)
User is member of exactly one org among those linked to this IdP → auto-select
User is member of multiple orgs → depends on scope:
- organization (singular) → show org selection UI
- organization:* → include all orgs in token
- No org scope → no org context in token, but memberships still managed
User is not a member of any org (new user) → use AM config; primary context = org matching email domain if unambiguous, otherwise first AM=true org, or no context
No match at all → regular realm login

Resolution Flows

A. Browser Login — SP-Initiated (OrganizationAuthenticator)

User enters email on login page
Extract email domain
IdP routing: find DOMAIN row matching domain
- IDP_ID set + AUTO_REDIRECT = true → redirect to IdP
- IDP_ID set + AUTO_REDIRECT = false → show login page with IdP option (no redirect)
- No IDP_ID → show password form
- Wildcard: most specific domain wins (existing getMatchingDomain() logic)
Org pre-selection (optional): if organization:alias scope or org login page, store in auth session note
If no org pre-selected: do NOT store org yet — resolved after callback

B. After IdP Callback (configureOrganization)

Auth session note ORGANIZATION_ATTRIBUTE → use that org
No auth session note, IdP linked to multiple orgs → don't pick yet, set "org resolution deferred" flag
Single org: if IdP linked to exactly one org → set that as context (backwards compatible)

C. Post-Broker Membership (IdpAddOrganizationMemberAuthenticator)

If configureOrganization resolved a specific org, only process that org (if it is linked to this IdP). Otherwise (no org resolved, e.g. IdP-initiated), iterate all orgs linked to this IdP via ORG_IDENTITY_PROVIDER:

For each org:

AM=false → skip (invitation-only)
AM=true → check domain gate:
- a. Org has no domains (no rows in ORG_DOMAIN) → add member with configured MT (domain-less org = domain-agnostic)
- b. Org has domains → check if user's email domain is claimed by this org (exists in ORG_DOMAIN for this org):
  - Yes → add member with configured MT
  - No → skip (user's domain doesn't belong to this org)
Existing members are NOT re-added and membership type is NOT upgraded

Why domain-gated AM? (feedback from @wschomburg and @bcmedeiros) A shared IdP alone should not create cross-org membership. If Org-A owns acme.com and Org-B owns globex.com, alice@acme.com authenticating via a shared IdP should only be auto-added to Org-A, not Org-B. Admins who want all IdP users auto-added regardless of domain can use a domain-less org (no DOMAIN rows).

D. Org Context for Token (post-membership)

If auth session has explicit org → use it
If user is member of exactly one org → auto-select
If user is member of multiple orgs → based on scope:
- organization:alias → that org
- organization → prompt or use default org
- organization:* → all orgs in token
No org membership → no org claims

Scenario Matrix

Group 1: SP-Initiated IdP Login — New User

Scenario 1.1 — Simple: One IdP, One Org, One Domain

Setup: Org-A owns acme.com (DOMAIN.ORG_ID = Org-A, IDP_ID = IdP-X). Join: (Org-A, IdP-X, AM=true, MT=MANAGED).

Action: New user enters alice@acme.com on login page.

Flow: DOMAIN lookup → acme.com → IdP-X → redirect. After callback, IdP-X linked to one org → set Org-A as context. Post-broker: AM=true, acme.com owned by Org-A ✓ → addManagedMember(Org-A, alice).

Final state: Alice is MANAGED member of Org-A. Equivalent to today's behavior.

Scenario 1.5 — Different Domains, Different IdPs, Same Org

Setup: Org-A owns acme.com (IDP_ID = IdP-X) and partner.com (IDP_ID = IdP-Y). Join: (Org-A, IdP-X, AM=true, MT=MANAGED), (Org-A, IdP-Y, AM=true, MT=UNMANAGED).

Action A: alice@acme.com → IdP-X → MANAGED in Org-A.
Action B: bob@partner.com → IdP-Y → UNMANAGED in Org-A.

Final state: Different domains → different IdPs → different membership types within same org. This is the #47554 use case.

Scenario 1.6 — Non-Federated Domain

Setup: Org-A owns acme.com (IDP_ID = IdP-X) and internal.acme.com (IDP_ID = NULL).

Action: bob@internal.acme.com on login page.

Flow: DOMAIN → internal.acme.com → IDP_ID = NULL → no redirect → password form → no broker flow → no auto-membership.

Final state: Bob is realm user, not member of Org-A. Must be invited or manually added.

Scenario 1.7 — Wildcard Domain with Specific Override

Setup: Org-A owns *.acme.com (IDP_ID = IdP-X) and hr.acme.com (IDP_ID = IdP-Y).

Action: carol@hr.acme.com logs in.

Flow: Both patterns match → most specific wins → hr.acme.com → IdP-Y. Post-broker via IdP-Y → Org-A AM=true + domain ✓ → add as configured.

Final state: Carol in Org-A, authenticated via IdP-Y (HR-specific IdP). Wildcard precedence from Organizations.getMatchingDomain() carries over.

Scenario 1.8 — Multiple Domains, Different IdPs, One Non-Federated

Setup: Org-A owns acme.com (IDP_ID = IdP-X), partner.com (IDP_ID = IdP-Y), internal.acme.com (IDP_ID = NULL). Join: (Org-A, IdP-X, AM=true, MT=MANAGED), (Org-A, IdP-Y, AM=true, MT=UNMANAGED).

Action A: alice@acme.com → IdP-X → MANAGED.
Action B: bob@partner.com → IdP-Y → UNMANAGED.
Action C: carol@internal.acme.com → NULL → password form → no auto-membership.

Note: No "ANY" catch-all needed. Each domain declares its IdP or null. This replaces the old kc.org.domain=ANY config attribute which was a workaround for the 1:1 domain-per-IdP limitation.

Scenario 1.9 — Different Domains, Same IdP, Different Orgs (core multi-IdP scenario)

Setup: Org-A owns acme.com, Org-B owns globex.com. Both DOMAIN.IDP_ID = IdP-X (same shared IdP). Join: (Org-A, IdP-X, AM=true, MT=MANAGED), (Org-B, IdP-X, AM=true, MT=UNMANAGED).

Action: alice@acme.com logs in.
Flow: DOMAIN → acme.com → IdP-X → redirect. After callback: IdP-X linked to two orgs. Post-broker: Org-A AM=true + acme.com owned by Org-A ✓ → MANAGED. Org-B AM=true + acme.com NOT owned by Org-B ✗ → skip.

Final state: Alice MANAGED in Org-A only. Domain gate prevents cross-org membership — acme.com is not Org-B's domain, so shared IdP alone doesn't create membership.

Group 2: SP-Initiated IdP Login — Existing User

Scenario 2.2 — Existing User, Invited to Org-B, Shared IdP, Different Domains

Setup: Alice is UNMANAGED member of Org-B (invitation). Org-A owns acme.com, Org-B owns globex.com. Shared IdP-X. Join: (Org-A, IdP-X, AM=true, MT=UNMANAGED), (Org-B, IdP-X, AM=false, MT=UNMANAGED).

Action: Alice (alice@acme.com) logs in via IdP-X.

Flow: Post-broker: Org-A AM=true + acme.com owned by Org-A ✓ → add. Org-B AM=false → skip (already member anyway).

Final state: Alice UNMANAGED in both. Note: even if Org-B had AM=true, acme.com is not owned by Org-B, so Alice would NOT be auto-added to Org-B via IdP. Invitation-based membership is unaffected.

Scenario 2.3 — Existing User, MANAGED in Org-A, Shared IdP, Different Domain in Org-B

Setup: Alice is MANAGED in Org-A. Org-A owns acme.com, Org-B owns globex.com. Org-B now linked to IdP-X: (Org-B, IdP-X, AM=true, MT=UNMANAGED).

Action: Alice (alice@acme.com) logs in via IdP-X.

Flow: Post-broker: Org-A already member → skip. Org-B AM=true + acme.com NOT owned by Org-B ✗ → skip.

Final state: MANAGED in Org-A only. Domain gate prevents auto-addition to Org-B.

Scenario 2.4 — Membership Type NOT Upgraded on Login

Setup: Alice was invited to Org-A → UNMANAGED. Org-A has IdP-X with MT=MANAGED, AM=true. Org-A owns acme.com.

Action: Alice logs in via IdP-X for first time.

Flow: Post-broker: Org-A AM=true, MT=MANAGED, but Alice already a member → skip. UNMANAGED status preserved.

Final state: Alice stays UNMANAGED in Org-A.

Rationale: Membership type set at creation time only. Admin invited her intentionally as UNMANAGED. Silent upgrade to MANAGED would change her lifecycle semantics as a side effect of login — dangerous and surprising.

Group 3: IdP-Initiated Login (No Auth Session)

Scenario 3.1 — IdP-Initiated, Single Org

Setup: IdP-X linked only to Org-A. Org-A owns acme.com.

Action: IdP-X sends assertion for alice@acme.com.

Flow: No auth session → IdP-X has one org → set Org-A → add member per AM config. Same as SP-initiated.

Scenario 3.2 — IdP-Initiated, Shared IdP, Domain Disambiguates

Setup: IdP-X linked to Org-A (owns acme.com) and Org-B (owns globex.com).

Action: IdP-X sends assertion for alice@acme.com.

Flow: No auth session note. configureOrganization(): IdP-X in multiple orgs, look up acme.com → owned by Org-A → primary = Org-A. Post-broker: Org-A AM=true + domain ✓ → add. Org-B AM=true + acme.com NOT owned by Org-B ✗ → skip.

Final state: Alice in Org-A only.

Scenario 3.4 — IdP-Initiated, Email Domain Not Owned by Any Org

Setup: IdP-X linked to Org-A (owns acme.com) and Org-B (owns globex.com). User has alice@external.com (not in any DOMAIN row).

Action: IdP-X sends assertion for alice@external.com.

Flow: No domain match. Post-broker: Org-A AM=true + external.com NOT owned ✗ → skip. Org-B AM=true + NOT owned ✗ → skip.

Final state: Alice exists in realm, no org membership. Domain gate prevents auto-addition when the email domain isn't owned by any org. If admin wants users with unknown domains auto-added, they should use a domain-less org (see 7.6) or route users explicitly via kc_idp_hint

Group 4: Invitation Flow

Related: #46914 — Allow invite-user to onboard new members as unmanaged. Membership type for invited users should be a configuration option at org level, not per-invite.

Scenario 4.1 — Invite to Org with Shared IdP (AM=false)

Setup: Org-B has IdP-X (AM=false). Org-A also has IdP-X (AM=true). Org-A owns acme.com, Org-B owns globex.com.

Action: Admin of Org-B invites alice@acme.com.
Flow: Invitation created, Alice accepts → addMember(Org-B, alice) as UNMANAGED. No broker flow.

Final state: Alice UNMANAGED in Org-B only. Later login via IdP-X → post-broker adds to Org-A (AM=true + domain ✓). Org-B (AM=false) skipped; already member.

Scenario 4.2 — Invite to Org, User Later Logs In via Shared IdP

Setup: Alice invited to Org-A (UNMANAGED) and Org-B (UNMANAGED) — both AM=false. IdP-X shared.

Action: Alice logs in via IdP-X.

Flow: Both AM=false → no new memberships. Already member of both → context per scope.

Final state: Unchanged. Both memberships preserved.

Scenario 4.3 — Invite MANAGED User from Another Org

Setup: Alice is MANAGED in Org-A. Admin of Org-B invites Alice.

Action: Alice accepts → addMember(Org-B, alice) as UNMANAGED.

Final state: MANAGED in Org-A, UNMANAGED in Org-B. Dual membership.

Group 5: Manual Admin Addition

Scenario 5.1 — Add Existing User to Org Manually

Unchanged. POST /organizations/{orgId}/members → UNMANAGED member. No IdP interaction, no domain gate.

Group 6: Lifecycle Events

Scenario 6.1 — Org Deletion with MANAGED Members

Setup: Alice MANAGED in Org-A, UNMANAGED in Org-B. Bob MANAGED in Org-A only.

Action: Admin deletes Org-A.

Behavior: MANAGED → removeUser(realm, member):

Bob: deleted from realm (expected — MANAGED means lifecycle tied to org)
Alice: deleted from realm → gone from Org-B too (expected — MANAGED in Org-A)

MANAGED semantics are intentional. DOMAIN rows for Org-A are cascade-deleted. Tools to manage this include #48913 (API to change membership type), AM=false + invitation model, and the decision that membership type is never silently upgraded on login.

Scenario 6.2 — Admin Removes IdP from Org

Setup: IdP-X linked to Org-A (AM=true, MT=MANAGED). Alice and Bob are MANAGED via IdP-X.

Action: Admin unlinks IdP-X from Org-A.

Expected behavior:

Remove ORG_IDENTITY_PROVIDER(Org-A, IdP-X) row
DOMAIN rows whose IDP_ID = IdP-X remain (domain still routes to IdP-X — routing is independent of org-IdP association)
Existing members remain unchanged

Rationale: IdP unlinking is config, not membership. Members can still log in via password or other IdPs.

Scenario 6.3 — User Email Change

Unchanged:

MANAGED members: email change to non-org domain rejected
UNMANAGED members: email change allowed

Scenario 6.4 — Domain Removed from Org

Action: Admin removes acme.com from Org-A.

Behavior:

Delete the DOMAIN row for acme.com (domain belongs to this org alone — no orphan question)
Existing Org-A members with @acme.com remain members (membership ≠ domain ownership)
Future logins: post-broker domain gate for Org-A fails for @acme.com users → no new auto-additions

Domain removal doesn't revoke existing memberships — only affects future auto-routing and auto-membership.

Group 7: Edge Cases

Scenario 7.1 — Same User, Different Membership Types Across Orgs

Valid. Membership type is per org. Alice can be MANAGED in Org-A and UNMANAGED in Org-B.

Scenario 7.2 — Two IdPs for Same Domain

DOMAIN.IDP_ID is a single FK → one IdP per domain. If admin needs two IdPs for same domain, use a single federating IdP or split into subdomains.

Scenario 7.3 — MT=MANAGED Conflict Across Orgs

(Org-A, IdP-X, MT=MANAGED) + (Org-B, IdP-X, MT=MANAGED) → violates C1. Rejected at config time (409/400).

Scenario 7.5 — User Belongs to Org Without Domain Match

Valid. Domain matching is for IdP routing and auto-membership only, not a membership requirement. Invited/manually-added users don't need matching domains.

Scenario 7.6 — Org Has No Domains

Setup: Org-A has no domains (no DOMAIN rows with ORG_ID = Org-A). IdP-X linked with AM=true.

7.6a — IdP-initiated (no resolved org): User logs in via IdP-X with kc_idp_hint. No org resolved by configureOrganization → resolved-org gate open → Org-A iterated → AM=true + no domains → domain gate skipped → add member.

7.6b — SP-initiated via another org's domain: User enters alice@acme.com → routed to IdP-X via Org-B's domain. configureOrganization resolves Org-B → resolved-org gate limits processing to Org-B → Org-A skipped (not the resolved org).

7.6c — Client requests organization:org-a: Resolved org = Org-A → processed → AM=true + no domains → domain gate skipped → add member.

Note: A domain-less org has no domain routing, so it cannot be reached via email-based IdP discovery. To direct users to it, use organization:alias scope, kc_idp_hint, or invitations. The resolved-org gate prevents surprise membership — a user logging in through Org-B's page will not silently join an
unrelated domain-less org.

Scenario 7.7 — Catch-All

Bare * as a domain is not supported. validateDomain() rejects it (fails email validation for user@*). Wildcard domains use the *. prefix (e.g., *.acme.com) for subdomain matching within a known domain hierarchy.

For "add everyone who comes through this IdP regardless of email domain", use a domain-less org (scenario 7.6): an org with no DOMAIN rows skips the domain gate entirely, achieving the same post-broker membership result.

Scenario 7.8 — Multiple Orgs Need Users from Same Email Domain

With 1:1 domain-to-org, a domain can only be owned by one org. For use cases where multiple orgs need users from the same email domain, two approaches:

Invitations — Org-B invites alice@acme.com explicitly (no domain ownership needed)
Domain-less org with AM=true — Org-B has no domains and links the shared IdP with AM=true → all IdP users auto-added regardless of email domain (see Scenario 7.6)

Follow-ups (out of scope for this proposal)

org_hint query parameter — @wschomburg's use case: pre-selecting org context for portal-based flows via login_hint. Separate enhancement.
Claim-based org membership — @FWest98's request: determining org membership from IdP token claims instead of email domain. Future enhancement on ORG_IDENTITY_PROVIDER (e.g., MEMBERSHIP_CLAIM_NAME + MEMBERSHIP_CLAIM_VALUE). No design conflict with this proposal.

vramik · 2026-05-19T10:14:32Z

vramik
May 19, 2026
Collaborator Author

@wschomburg I'd welcome your feedback on this one, thank you

0 replies

FWest98 · 2026-05-19T11:18:51Z

FWest98
May 19, 2026

This seems like a very comprehensive proposal that mostly covers our usecase! Thanks for the work!

There is one small note here; for shared IdPs, we would prefer org membership to be determined by a specific claim value, rather than the email address. I'm not sure that's easy to integrate here, but it could be a situation that happens more often.

0 replies

jthimonier · 2026-05-19T19:13:06Z

jthimonier
May 19, 2026

Thanks @vramik , it covers well the requirements from #47554
Would it make sense to normalize ORG_DOMAIN into a separate DOMAIN table (holding name, verified, and routing_idp_id) and a join table ORG_DOMAIN (org_id, domain_id), so that domain attributes are defined once globally, eliminating duplication across organizations and enforcing C6 by design rather than by application logic?

10000

1 reply

vramik Aug 28, 2026
Collaborator Author

incorporated your suggestion, it makes a lot of sense, thanks a lot

wschomburg · 2026-05-20T10:10:48Z

wschomburg
May 20, 2026

Thanks @vramik, for your work.
It looks very good and covers nearly everything, but in my opinion, the requirements for #31705 are missing. Here are the places, where I see a problem with a shared SaaS IDP:

In scenario 1.9, why is Alice UNMANAGED in Org-B? As the domain isn't owned by the Org-B, I wouldn't expect any connection of Alice to Org-B.
Same for 2.2 and 2.3. As long as the domain isn't owned by the Org, the users shouldn't be added to the Org only because they share the same IDP. With a shared IDP for the SaaS in EntraID, the users should only be added to the Org (if AM=true) when the domain is configured in the Org.
Scenario 3.2: "Post-broker: iterate all AM=true orgs for IdP-X → add to each" Add only, if the domain is configured for the Org
Scenario 3.4: Alice shouldn't be a member of any Org, as her domain isn't configured.

1 reply

bcmedeiros Jun 28, 2026

I have the same concerns as @wschomburg.

Final state: Alice MANAGED in Org-A (primary), UNMANAGED in Org-B.

Alice should not have any relation to Org-B at all in 1.9

Note: When the domain is NOT shared (only one org has it), domain CAN disambiguate the primary org.

I don't this the fact that an IdP is shared between 2 orgs should create any relationship on contract between those orgs at all, apart from the fact of the IdP itself being shared.

I'm interested in this feature exactly because of the single IdP being used against mulitple orgs case, and it's a pretty simple use case; we have multiple orgs authenticating with Google Workspace and Microsoft domains, each one has their own domain, but now I have to create one "copy" of the same IdP for each org, replicate credentials, etc. I would like not do that, just have one "Google" IdP with multiple domains, and each domain would direct users to that specific org that own that domain.

wschomburg · 2026-05-21T09:49:53Z

wschomburg
May 21, 2026

@vramik One additional question about the process to choose the right org. We are using the IDP login_hint a lot to provide links that directly forward users to the customer IDP, without the extra step of choosing the IDP. This is used for internal customer app portals (on their infrastructure) and for dedicated customer frontends from one of our apps. Will it work with the flows you described, or do you plan to also provide an org_hint query parameter?

0 replies

vramik · 2026-08-28T07:10:28Z

vramik
Aug 28, 2026
Collaborator Author

The original post above has been updated to incorporate community feedback. Here's what changed and who drove it:

Contributors:

Key changes:

Normalized DOMAIN table (from @jthimonier's suggestion)
- Domain attributes (NAME, VERIFIED, IDP_ID, AUTO_REDIRECT) are now defined once in a realm-scoped DOMAIN table
- ORG_DOMAIN becomes a pure M:N join table (DOMAIN_ID, ORG_ID)
- AUTO_REDIRECT on DOMAIN replaces the old per-IdP kc.org.broker.redirect.mode.email-matches config — redirect behavior is now per-domain, not per-IdP
- Benefit: shared domains can't have conflicting IdP routing — C6 enforced by schema design, not application logic
Domain-gated auto-membership (from @wschomburg + @bcmedeiros feedback)
- Post-broker auto-membership now requires the user's email domain to be claimed by the target org (via ORG_DOMAIN)
- A shared IdP alone no longer creates cross-org membership
- Domain-less orgs (no ORG_DOMAIN rows) skip the gate — they're domain-agnostic by definition
- Admins who want the old "add everyone" behavior can configure a wildcard domain (*)
Updated scenarios — the following scenarios changed behavior:
- 1.9 — Different domains, same IdP, different orgs: domain gate now prevents cross-org auto-membership
- 2.2 — Existing user, invited to Org-B: domain gate prevents auto-addition to wrong org
- 2.3 — MANAGED user, shared IdP: domain gate blocks auto-addition to org that doesn't own user's domain
- 3.2 — IdP-initiated, shared IdP: domain disambiguates which org(s) get new member
- 3.4 — Email domain not owned by any org: no membership created (was ambiguous before)
Follow-ups (noted in updated post, not part of this proposal):
- org_hint query parameter — pre-selecting org context for portal flows (@wschomburg)
- Claim-based org membership — determining membership from IdP token claims (@FWest98)

Previous version did not have domain-gated AM and used a flat ORG_DOMAIN table where domain attributes were duplicated per org-domain association. The scenarios listed above all had different outcomes under V2 — in most cases, a shared IdP with AM=true would auto-add users to ALL linked orgs regardless of domain ownership.

1 reply

vramik Aug 28, 2026
Collaborator Author

@pedroigor fyi

pedroigor · 2026-09-03T18:49:56Z

pedroigor
Sep 3, 2026
Collaborator

Sorry for jumping in late, guys. Overall, the approach sounds solid, but I do not think we should allow different organizations to share the same domain. If you think otherwise, can you please share the use case?

2 replies

vramik Sep 4, 2026
Collaborator Author

Without different organizations sharing the same domain the proposal simplifies:

Data model

ORG_DOMAIN (one row per domain name per realm)
  - ID              VARCHAR(36)  PK
  - NAME            VARCHAR(255) NOT NULL
  - VERIFIED        BOOLEAN      DEFAULT FALSE
  - REALM_ID        VARCHAR(255) NOT NULL
  - ORG_ID          VARCHAR(255) NOT NULL, FK → ORG.ID ON DELETE CASCADE
  - IDP_ID          VARCHAR(36) nullable, FK → IDENTITY_PROVIDER.INTERNAL_ID ON DELETE SET NULL
  - AUTO_REDIRECT   BOOLEAN      DEFAULT FALSE
  - UNIQUE(REALM_ID, NAME)

ORG_IDENTITY_PROVIDER (M:N join table)
  - ORGANIZATION_ID       VARCHAR(36)  FK → ORG.ID, ON DELETE CASCADE
  - IDENTITY_PROVIDER_ID  VARCHAR(255) FK → IDENTITY_PROVIDER.INTERNAL_ID, ON DELETE CASCADE
  - AUTO_MEMBERSHIP       BOOLEAN      DEFAULT TRUE
  - MEMBERSHIP_TYPE       VARCHAR(255) DEFAULT 'UNMANAGED'
  - PK(ORGANIZATION_ID, IDENTITY_PROVIDER_ID)

IDENTITY_PROVIDER
  - ORGANIZATION_ID column REMOVED (replaced by join table)

Scenarios

┌───────────────┬───────────────────────────────────────────┐
│    Removed    │                  Reason                   │
├───────────────┼───────────────────────────────────────────┤
│ 1.2, 1.3, 1.4 │ Shared domain across orgs — not supported │
├───────────────┼───────────────────────────────────────────┤
│ 2.1           │ Existing user + shared domain             │
├───────────────┼───────────────────────────────────────────┤
│ 3.3           │ IdP-initiated + shared domain ambiguity   │
└───────────────┴───────────────────────────────────────────┘

bcmedeiros Sep 4, 2026

I also don't see much value in having the same domain being allowed on multiple organizations. That would cover all the use cases I have for this feature at the moment, and it seems to simplify things quite a lot, so I support that.

vramik · 2026-10-05T08:26:34Z

vramik
Oct 5, 2026
Collaborator Author

I'd like to gather feedback on #53115. Would you find this capability useful? Should it be configurable? Please share your thoughts here or in the issue. You can upvote the issue by adding a 👍 there — it will help us decide on priorities.

1 reply

wschomburg Oct 7, 2026

Hi @vramik,
I was not aware of this behavior, and the suggested solution is extremely useful. It will also support the migration from our current state without organizations to organizations with (then) multi-domain + multi-IDP. We have many customers, all with hundreds to thousands of users. Without this feature, we have to migrate them all by hand into the right organization. Same for later, when the scenarios from #53115 are met. You have my vote for it.

Organization Behavior Specification: Multi-Domain + Multi-IdP (M:N Domains) #49091

Uh oh!

Uh oh!

vramik May 19, 2026 Collaborator

Context

Legend

Data Model

Two Decoupled Concerns

IdP Routing (domain → IdP)

Org Context Resolution

Resolution Flows

A. Browser Login — SP-Initiated (OrganizationAuthenticator)

B. After IdP Callback (configureOrganization)

C. Post-Broker Membership (IdpAddOrganizationMemberAuthenticator)

D. Org Context for Token (post-membership)

Scenario Matrix

Group 1: SP-Initiated IdP Login — New User

Group 2: SP-Initiated IdP Login — Existing User

Group 3: IdP-Initiated Login (No Auth Session)

Group 4: Invitation Flow

Group 5: Manual Admin Addition

Group 6: Lifecycle Events

Group 7: Edge Cases

Follow-ups (out of scope for this proposal)

Replies: 8 comments · 6 replies

Uh oh!

vramik May 19, 2026 Collaborator Author

Uh oh!

FWest98 May 19, 2026

Uh oh!

jthimonier May 19, 2026

Uh oh!

vramik Aug 28, 2026 Collaborator Author

Uh oh!

wschomburg May 20, 2026

Uh oh!

bcmedeiros Jun 28, 2026

Uh oh!

wschomburg May 21, 2026

Uh oh!

vramik Aug 28, 2026 Collaborator Author

Uh oh!

vramik Aug 28, 2026 Collaborator Author

Uh oh!

pedroigor Sep 3, 2026 Collaborator

Uh oh!

vramik Sep 4, 2026 Collaborator Author

Data model

Scenarios

Uh oh!

bcmedeiros Sep 4, 2026

Uh oh!

vramik Oct 5, 2026 Collaborator Author

Uh oh!

wschomburg Oct 7, 2026

vramik
May 19, 2026
Collaborator

Replies: 8 comments 6 replies

vramik
May 19, 2026
Collaborator Author

FWest98
May 19, 2026

jthimonier
May 19, 2026

vramik Aug 28, 2026
Collaborator Author

wschomburg
May 20, 2026

wschomburg
May 21, 2026

vramik
Aug 28, 2026
Collaborator Author

vramik Aug 28, 2026
Collaborator Author

pedroigor
Sep 3, 2026
Collaborator

vramik Sep 4, 2026
Collaborator Author

vramik
Oct 5, 2026
Collaborator Author