Add Wildcard Subdomain Matching Support for Organization Domains by shaidar · Pull Request #45190 · keycloak/keycloak

shaidar · 2026-01-06T17:16:48Z

Problem Statement

This addresses this issue. When using the Organizations feature in Keycloak, domain-based redirection to Identity Providers (IdPs) only works with exact domain matches. This creates problems in real-world scenarios where users authenticate with email addresses containing subdomains (e.g., user@sub.example.com) while the organization is configured with the base domain (example.com).

Common use cases that were previously unsupported:

Microsoft 365 tenant subdomains: user@contoso.onmicrosoft.com when org is configured for onmicrosoft.com
University departments: user@cs.university.edu when org uses university.edu
Multi-tenant SaaS environments with customer-specific subdomains
Corporate environments with regional or departmental subdomains

This resulted in authentication failures, NullPointerExceptions, or users being unable to access their organization.

Solution

Added a new matchSubdomains boolean flag to organization domains that enables hierarchical subdomain matching. When enabled for a domain like example.com, it will match:

✅ example.com (exact match still works)
✅ sub.example.com
✅ deep.sub.example.com
✅ Any level of subdomain nesting

The feature is opt-in per domain and backward compatible - all existing domains default to exact matching.

Implementation Details

Architecture

The implementation follows a simple, performant approach:

// Core matching logic
if (email.equals(domain)) return true;  // Exact match
if (domain.matchSubdomains) {
    return email.endsWith("." + domain);  // Subdomain match
}
return false;

Files Modified

1. Data Model Layer (3 files)

server-spi/src/main/java/org/keycloak/models/OrganizationDomainModel.java
- Added matchSubdomains boolean field with default value false
- Added new constructor overload maintaining backward compatibility
- Added isMatchSubdomains() getter
core/src/main/java/org/keycloak/representations/idm/OrganizationDomainRepresentation.java
- Added matchSubdomains field to REST API representation
- Added getter/setter methods
model/jpa/src/main/java/org/keycloak/models/jpa/entities/OrganizationDomainEntity.java
- Added MATCH_SUBDOMAINS column mapping
- Added getter/setter for JPA entity

2. Database Layer (2 files)

model/jpa/src/main/resources/META-INF/jpa-changelog-27.0.0.xml (new)
- Liquibase changeset to add MATCH_SUBDOMAINS column with default false
model/jpa/src/main/resources/META-INF/jpa-changelog-master.xml
- Included new changelog

3. Data Mapping Layer (3 files)

model/jpa/src/main/java/org/keycloak/organization/jpa/OrganizationAdapter.java
- Updated toModel() to include matchSubdomains when converting entity to model
- Updated setDomains() to persist matchSubdomains flag
model/jpa/src/main/java/org/keycloak/organization/jpa/JpaOrganizationProvider.java
- Enhanced getByDomainName() with hierarchical lookup:
  1. Try exact match first (fast path)
  2. Parse email domain into parent domains
  3. Check each parent domain for wildcard enabled
- Example: deep.sub.example.com checks example.com, sub.example.com
server-spi-private/src/main/java/org/keycloak/models/utils/RepresentationToModel.java
- Updated toModel() conversion to include matchSubdomains field

4. Business Logic Layer (3 files)

services/src/main/java/org/keycloak/organization/utils/Organizations.java
- Added domainMatches(String emailDomain, OrganizationDomainModel orgDomain) helper method
- Centralized matching logic used throughout the codebase
- Updated matchesOrganizationDomain() to use new helper
services/src/main/java/org/keycloak/organization/authentication/authenticators/browser/OrganizationAuthenticator.java
- Updated redirect() method to use wildcard-aware domain matching
- Enables automatic IdP redirect for subdomain emails
services/src/main/java/org/keycloak/organization/validator/OrganizationMemberValidator.java
- Updated validateEmailDomain() to support wildcard matching
- Added validateEmailDomainMatch() helper method
- Ensures subdomain emails pass validation when wildcard is enabled

Database Schema

ALTER TABLE ORG_DOMAIN 
ADD COLUMN MATCH_SUBDOMAINS BOOLEAN DEFAULT FALSE NOT NULL;

Testing

Unit Tests (1 new file)

Created OrganizationDomainMatchingTest.java with 8 comprehensive unit tests:

Exact domain matching (default behavior)
Wildcard subdomain matching
Case insensitivity
Real-world scenarios (Microsoft 365, universities)
Null/empty value handling
Edge cases (special characters, deep nesting)
Backward compatibility verification

Integration Tests (10 new tests)

Added to existing test classes:

OrganizationTest.java:

testDomainWithWildcardSubdomains() - CRUD operations for wildcard flag

AbstractBrokerSelfRegistrationTest.java:

testRedirectToIdentityProviderWithWildcardSubdomainMatching() - Subdomain redirect
testRedirectToIdentityProviderWithDeepSubdomain() - Multi-level subdomain redirect
testNoRedirectWithoutWildcardSubdomainMatching() - Verify disabled wildcard blocks subdomains
testExactDomainStillWorksWithWildcardEnabled() - Exact match with wildcard enabled
testEmailDomainValidationWithWildcardSubdomains() - Member creation with subdomain
testEmailDomainValidationRejectsSubdomainWithoutWildcard() - Rejection when disabled
testDeepSubdomainValidationWithWildcard() - Multi-level validation

All tests pass and follow Keycloak testing patterns.

Usage

REST API

Create organization with wildcard subdomain matching:

POST /admin/realms/{realm}/organizations
{
  "name": "Example Corp",
  "domains": [
    {
      "name": "example.com",
      "verified": true,
      "matchSubdomains": true
    }
  ]
}

Update existing domain:

PUT /admin/realms/{realm}/organizations/{id}
{
  "domains": [
    {
      "name": "example.com",
      "verified": true,
      "matchSubdomains": true
    }
  ]
}

Admin Console

The matchSubdomains field will be available in the organization domain configuration UI (requires separate UI changes).

Behavior

With matchSubdomains: false (default):

User john@example.com → Matches ✅
User john@sub.example.com → Does not match ❌

With matchSubdomains: true:

User john@example.com → Matches ✅
User john@sub.example.com → Matches ✅
User john@team.dev.example.com → Matches ✅

Backward Compatibility

✅ Fully backward compatible:

Existing domains automatically default to matchSubdomains: false
No behavior changes for existing deployments
Database migration adds column with safe default value
Old API calls without matchSubdomains field continue to work
Existing constructors maintained with new overloads

Migration Notes

For administrators:

Existing organizations are unaffected - all domains use exact matching
To enable subdomain matching, update domain configuration via REST API or Admin Console
Consider enabling for domains like onmicrosoft.com or organizational base domains
Test thoroughly before enabling in production

For developers:

New OrganizationDomainModel constructor available with matchSubdomains parameter
Old constructors still work (default to false)
Use Organizations.domainMatches() helper for custom domain matching logic

Performance Considerations

Exact match: Single database query (no performance impact)
Wildcard match: Additional queries only when exact match fails
- Parses domain into parent domains (sub.example.com → example.com)
- Queries each parent domain sequentially
- Short-circuits on first match
Optimization: Most common case (exact match) remains fast
Caching: Existing organization cache applies

Security Considerations

✅ Safe by default - wildcard matching must be explicitly enabled
✅ Domain validation - existing domain validation rules still apply
✅ No new attack vectors - only matches legitimate DNS subdomain hierarchy
✅ Verification required - verified domains should be verified before enabling wildcards

Related Issues

Resolves issues with:

Microsoft 365 multi-tenant scenarios
University/enterprise subdomain structures
SaaS platforms with customer-specific subdomains
Any environment where email addresses use subdomains of a managed domain

Checklist

ahus1 · 2026-01-07T07:41:30Z

@shaidar - thank you for the PR. Can you please update the PR contain only contain your commits? This can probably be done by rebasing it.

Once you have done that, there is no need for further rebases until a reviewer asks for you for a rebase, or GitHub reports merge conflicts.

ahus1 · 2026-01-07T07:42:27Z

@keycloak/core-iam - can you please have a look at this PR? Thanks!

sguilhen · 2026-01-07T15:01:56Z

+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.2.xsd">
+
+    <changeSet author="keycloak" id="27.0.0-org-domain-wildcard">


I would just change this to 26.6.0 (along with the filename), as Keycloak 27 won't be released in the near future.

sguilhen · 2026-01-07T15:03:02Z

@ahus1 changes look ok to me, apart from the jpa changeset version that I would switch from 27.0.0 to 26.6.0. We can trigger the CI to see if there's anything else that needs to be taken care of

sguilhen · 2026-01-07T18:31:14Z

@shaidar looks like there's a compilation failure - can you take a look and update the PR?

pedroigor

@shaidar As you mentioned, we need the setting available from the UI. I can work on it if you are not doing it already.

sguilhen · 2026-01-09T15:45:03Z

@shaidar build is failing due to wrong import order in one of the files. Can you run mvn spotless:apply to fix the imports and update the PR? Thanks!

pedroigor · 2026-01-09T17:10:33Z

Added a commit to fix the code format errors and changes to the liquibase changelog.

pedroigor · 2026-04-22T13:27:04Z

@shaidar, would you mind reviewing and trying out the latest changes to check if it is still aligned with your expectations?

Signed-off-by: sar <sar.haidar@gmail.com>

shaidar requested review from a team as code owners January 6, 2026 17:16

keycloak-github-bot Bot added team/cloud-native team/core-clients team/core-iam labels Jan 6, 2026

shaidar force-pushed the sar/issue_40026 branch from cd4a99c to eea5e2d Compare January 6, 2026 17:28

shaidar requested a review from a team as a code owner January 6, 2026 17:28

keycloak-github-bot Bot added the team/ui label Jan 6, 2026

ahus1 removed team/cloud-native team/ui team/core-clients labels Jan 7, 2026

sguilhen reviewed Jan 7, 2026

View reviewed changes

shaidar force-pushed the sar/issue_40026 branch 2 times, most recently from dba3465 to e939143 Compare January 7, 2026 16:04

pedroigor reviewed Jan 7, 2026

View reviewed changes

shaidar force-pushed the sar/issue_40026 branch 2 times, most recently from a149e02 to 275ee14 Compare January 8, 2026 20:56

pedroigor force-pushed the sar/issue_40026 branch from a4f3f68 to ea87513 Compare January 9, 2026 17:14

shaidar force-pushed the sar/issue_40026 branch 2 times, most recently from 2ce3b03 to 0189943 Compare January 12, 2026 19:25

pedroigor force-pushed the sar/issue_40026 branch 4 times, most recently from e9953d9 to 1aaee8c Compare April 20, 2026 00:58

keycloak-github-bot Bot mentioned this pull request Apr 20, 2026

Flaky test: org.keycloak.testsuite.model.session.OfflineSessionPersistenceTest#testPersistenceMultipleNodesClientSessionAtSameNode #47421

Closed

pedroigor force-pushed the sar/issue_40026 branch from 1aaee8c to 2151508 Compare April 20, 2026 11:01

keycloak-github-bot Bot mentioned this pull request Apr 20, 2026

Flaky test: org.keycloak.testsuite.model.session.UserSessionPersisterProviderTest#testExpirationDistribution #47834

Closed

pedroigor force-pushed the sar/issue_40026 branch from 2151508 to e499675 Compare April 20, 2026 14:11

keycloak-github-bot Bot mentioned this pull request Apr 20, 2026

Flaky test: org.keycloak.testsuite.model.session.UserSessionProviderOfflineModelTest#testOfflineSessionLazyLoading #47979

Closed

pedroigor force-pushed the sar/issue_40026 branch 10 times, most recently from 01f0412 to 3a29004 Compare April 21, 2026 15:51

ssilvert previously approved these changes Apr 22, 2026

View reviewed changes

pedroigor dismissed ssilvert’s stale review via 23f84bc April 23, 2026 14:57

pedroigor force-pushed the sar/issue_40026 branch 4 times, most recently from 94fa341 to 15cda50 Compare April 24, 2026 11:14

keycloak-github-bot Bot mentioned this pull request Apr 24, 2026

Flaky test: org.keycloak.testsuite.authz.PolicyEvaluationTest# #48446

Closed

Changes to address Org subdomain matching

1c2fdb7

Signed-off-by: sar <sar.haidar@gmail.com>

stianst mentioned this pull request Jun 1, 2026

js deps uuid 26.6 #49539

Closed

sguilhen mentioned this pull request Sep 28, 2026

Organizations: malformed domain in login username (e.g. user@example;com) causes unhandled ModelValidationException ('Invalid domain format') #53100

Closed

2 tasks done

Navigation Menu

Repository navigation

Add Wildcard Subdomain Matching Support for Organization Domains - #45190

Add Wildcard Subdomain Matching Support for Organization Domains#45190
stianst merged 1 commit into
keycloak:mainfrom
shaidar:sar/issue_40026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

Uh oh!

Problem Statement

Solution

Implementation Details

Architecture

Files Modified

Database Schema

Testing

Unit Tests (1 new file)

Integration Tests (10 new tests)

Usage

REST API

Admin Console

Behavior

Backward Compatibility

Migration Notes

Performance Considerations

Security Considerations

Related Issues

Checklist

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants