Hello,

I am integrating Keycloak with an external OAuth 2.0 identity provider and have encountered an edge case related to email uniqueness conflicts during manual account linking.

Configuration

• Sync Mode: FORCE (user attributes, including email, are updated on every login)
• First Broker Login: Manual linking is supported, allowing users to link IdP accounts to existing Keycloak accounts even without matching attributes

Scenario

1. User has an existing local Keycloak account (userA) with email [email protected] (not linked to the IdP)
2. The same person logs in via the identity provider with email [email protected]
3. During first broker login flow, the user manually links the IdP account to a different Keycloak account with email [email protected]
4. After linking completes, the sync process attempts to update the email from [email protected] to [email protected]
5. Exception thrown: Email [email protected] already exists (duplicate emails not allowed in the realm)

Current Behavior

• The federated link is successfully established before the error occurs
• User receives a generic error message (Messages.IDENTITY_PROVIDER_UNEXPECTED_ERROR)
• User cannot understand what went wrong and likely doesn't remember having an old account with that email

Technical Details

The exception occurs in the following call chain:

IdentityBrokerService#afterFirstBrokerLogin
 → IdentityBrokerService#updateFederatedIdentity
    → AbstractIdentityProvider#updateBrokeredUser
      → AbstractIdentityProvider#updateEmail

The error is caught and rendered with a generic error page.

Question

What would be the best approach to provide a clearer, more actionable error message to users? Is there a better way to handle this situation gracefully?

Any guidance or best practices on handling this scenario would be greatly appreciated!