feat(auth): Simplify user identity management with email-first approach

[mohityadav766]

Summary

This PR simplifies OpenMetadata's authentication system by using email as the primary user identifier, replacing the complex claim resolution logic with a straightforward email-first approach.

Closes #23285

Key Changes

• Email as primary identifier: Users are now identified and looked up by email address instead of complex claim resolution
• Simplified configuration: New emailClaim and displayNameClaim replace the confusing jwtPrincipalClaims and jwtPrincipalClaimsMapping
• Email-based admin management: New adminEmails list replaces adminPrincipals for clearer admin specification
• Domain restrictions: New allowedEmailDomains for restricting authentication to specific email domains
• Bot email configuration: New botDomain for system-created bot email addresses
• Backward compatibility: All deprecated configs continue to work with deprecation warnings logged at startup

Configuration Changes

New fields in authenticationConfiguration:

• emailClaim (default: "email" for OIDC/SAML, "mail" for LDAP)
• displayNameClaim (default: "name" for OIDC/SAML, "displayName" for LDAP)

New fields in authorizerConfiguration:

• adminEmails - List of admin user email addresses
• allowedEmailDomains - Restrict authentication to specific domains
• botDomain - Domain for system bot emails (default: "openmetadata.org")

Deprecated (still functional with warnings):

• jwtPrincipalClaims → use emailClaim
• jwtPrincipalClaimsMapping → use emailClaim + displayNameClaim
• adminPrincipals → use adminEmails
• principalDomain → use botDomain for bots, allowedEmailDomains for user restrictions

Username Generation

Usernames are auto-generated from email addresses:

• john.doe@company.com → john.doe
• On collision, append random suffix: john.doe_x7k2

Test plan

• Unit tests for SecurityUtil email extraction and domain validation (28 tests)
• Unit tests for UserUtil username generation, admin check, bot email (21 tests)
• All tests pass
• Code formatted with mvn spotless:apply
• Manual testing with OIDC provider
• Manual testing with SAML provider
• Manual testing with LDAP provider

[github-actions]

TypeScript types have been updated based on the JSON schema changes in the PR

[gitar-bot]

🔍 CI failure analysis for 8cccdcc: SonarCloud CI fails with same Maven tests as postgresql CI (Apps, AWS); duplicate failure pattern

CI Status - SonarCloud Analysis

New Job: maven-sonarcloud-ci (Job 61512116051)

Status: Failed with same Maven test failures as previously analyzed

Test Results: 7878 tests run, 1 failure, 3 errors, 701 skipped

Failed Tests (identical to maven-postgresql-ci):

1. AppsResourceTest.post_trigger_app_200: Max retries exceeded polling for app trigger
2. AwsCredentialsUtilTest (3 errors): Credential validation tests throwing IllegalArgumentException

Analysis

This is a duplicate failure pattern - the same Maven integration test failures occurring in a different CI job (SonarCloud analysis).

Why this is the same issue:

• ✅ Identical test failures: AppsResourceTest + AwsCredentialsUtilTest
• ✅ Same error messages
• ✅ Same test count (7878 tests run)
• ✅ Different CI job but running same test suite

Not related to this PR (as previously established):

• ✅ No Apps/Application code modified
• ✅ No AWS credentials code modified
• ✅ This PR only changes authentication (JwtFilter, SecurityUtil, UserUtil)
• ✅ Zero overlap with failing test areas

---

Complete CI Summary

Maven Test Failures (affecting multiple CI jobs):

• ❌ maven-postgresql-ci: 6 failures (Feed, Apps, AWS)
• ❌ maven-sonarcloud-ci: 4 failures (Apps, AWS) [subset of postgresql failures]
• Pattern: Same underlying test issues appearing in multiple CI jobs

Playwright E2E Tests:

• ❌ Retry completed (attempt 2/2), still failed
• Max retries reached per Flaky Test Retry rule

Python S3 Tests:

• ❌ Consistent failure across all runs

Integration Tests:

• ✅ Fixed by retry (TagRecognizerFeedbackIT)

---

Key Insights

Maven Test Failures Are Widespread:

• Same test failures appearing in both postgresql and sonarcloud CI jobs
• Suggests these are not environment-specific but actual test issues
• Likely caused by:
  • Recent changes to Apps/Feed/AWS logic merged to main
  • Test assertion problems
  • Test data setup issues

All Failures Remain Unrelated to Authentication Changes:

• ✅ This PR: Java backend authentication only
• ❌ Failures: Apps, Feed, AWS, S3, Playwright E2E
• ✅ Zero code overlap

Conclusion

SonarCloud CI failure is a duplicate of the maven-postgresql-ci failures. The same Maven integration tests are failing across multiple CI jobs, confirming these are persistent test issues unrelated to the authentication changes in this PR.

Recommendation: These CI failures should not block this PR as all failures are in completely separate code areas from the authentication changes.

Code Review 👍 Approved with suggestions 0 resolved / 4 findings

Well-structured authentication refactor with solid backward compatibility, but has a potential race condition in concurrent username generation and minor issues in the JWT filter's email-first flow.

⚠️ Edge Case: Email-first flow uses email prefix as username without collision check

📄 openmetadata-service/src/main/java/org/openmetadata/service/security/JwtFilter.java:217-218

In the JwtFilter's email-first flow, the username is derived directly from the email prefix (email.split("@")[0]) without checking for collisions with existing users. However, in the OIDC, SAML, and LDAP handlers, UserUtil.generateUsernameFromEmail() is used which properly handles collisions with random suffixes.

This could cause issues when authenticating via JWT (non-initial login) where a user with the same email prefix already exists, since the SecurityContext would be set with a potentially non-unique username that doesn't match the actual user's stored username.

Impact: The principal name in the security context might not match the actual stored username for users who had collision handling applied during account creation.

Suggested fix: Consider using the actual stored username from the user lookup instead of re-deriving it from the email prefix. Alternatively, document that this behavior is intentional for the filter context.

⚠️ Bug: Race condition between username existence check and user creation

📄 openmetadata-service/src/main/java/org/openmetadata/service/util/UserUtil.java:96-100

The generateUsernameFromEmail method has a TOCTOU (time-of-check-to-time-of-use) race condition. Between checking existsChecker.test(baseUsername) returns false and the caller creating the user, another concurrent request could create a user with the same username.

This affects concurrent user signups for users with identical email prefixes (e.g., john.doe@company1.com and john.doe@company2.com signing up simultaneously).

Impact: Could result in duplicate key constraint violations under concurrent load.

Suggested fix: Wrap user creation in a retry loop that catches duplicate key exceptions and regenerates the username with a new suffix.

💡 Quality: Use equalsIgnoreCase instead of toLowerCase().equals()

📄 openmetadata-service/src/main/java/org/openmetadata/service/security/SecurityUtil.java:2105

In validateEmailDomain, the domain comparison uses d.toLowerCase().equals(domain) which creates a new String object for each comparison in the stream.

boolean allowed = allowedEmailDomains.stream().anyMatch(d -> d.toLowerCase().equals(domain));

Impact: Minor performance overhead due to unnecessary String allocations.

Suggested fix: Use equalsIgnoreCase:

boolean allowed = allowedEmailDomains.stream().anyMatch(d -> d.equalsIgnoreCase(domain));

The same pattern appears in UserUtil.isAdminEmail at line 3023:

.anyMatch(adminEmail -> adminEmail.toLowerCase().equals(normalizedEmail));

💡 Edge Case: Removed retry delay in LDAP connection attempts

📄 openmetadata-service/src/main/java/org/openmetadata/service/security/auth/LdapAuthenticator.java:2296-2299

The refactored getLdapUserInfo method removed the baseDelayMs variable and the exponential backoff delay between retry attempts:

-  private String getUserDnFromLdap(String email) {
-    // Retry configuration (will be made configurable in future)
+  private LdapUserInfo getLdapUserInfo(String email) {
     final int maxRetries = 3;
-    final int baseDelayMs = 500;

Without a delay between retries, the code will immediately retry failed LDAP connections, which could overwhelm a recovering LDAP server or fail faster than necessary without giving the server time to recover.

Impact: Reduced resilience during LDAP server transient failures.

Suggested fix: Reintroduce the delay with exponential backoff between retry attempts.

Tip

Comment Gitar fix CI or enable auto-apply: gitar auto-apply:on

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[gitar-bot]

⚠️ Edge Case: Email-first flow uses email prefix as username without collision check

Details

In the JwtFilter's email-first flow, the username is derived directly from the email prefix (email.split("@")[0]) without checking for collisions with existing users. However, in the OIDC, SAML, and LDAP handlers, UserUtil.generateUsernameFromEmail() is used which properly handles collisions with random suffixes.

This could cause issues when authenticating via JWT (non-initial login) where a user with the same email prefix already exists, since the SecurityContext would be set with a potentially non-unique username that doesn't match the actual user's stored username.

Impact: The principal name in the security context might not match the actual stored username for users who had collision handling applied during account creation.

Suggested fix: Consider using the actual stored username from the user lookup instead of re-deriving it from the email prefix. Alternatively, document that this behavior is intentional for the filter context.

---

Was this helpful? React with 👍 / 👎

[gitar-bot]

⚠️ Bug: Race condition between username existence check and user creation

Details

The generateUsernameFromEmail method has a TOCTOU (time-of-check-to-time-of-use) race condition. Between checking existsChecker.test(baseUsername) returns false and the caller creating the user, another concurrent request could create a user with the same username.

This affects concurrent user signups for users with identical email prefixes (e.g., john.doe@company1.com and john.doe@company2.com signing up simultaneously).

Impact: Could result in duplicate key constraint violations under concurrent load.

Suggested fix: Wrap user creation in a retry loop that catches duplicate key exceptions and regenerates the username with a new suffix.

---

Was this helpful? React with 👍 / 👎

[github-actions]

Jest test Coverage

UI tests summary

Lines	Statements	Branches	Functions
	65.8% (55627/84538)	44.83% (28695/64002)	47.68% (8738/18325)

[sonarqubecloud]

Quality Gate passed for 'open-metadata-ui'

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud