Seamless Multi‑IdP Login in Keycloak (No “User already exists” Errors)

This short document outlines how to achieve a seamless authentication flow in Keycloak where the same end user can log in via multiple OIDC Identity Providers (e.g., Google, GitHub) using the same email, without seeing Keycloak screens or “User already exists” errors, and with automatic behind‑the‑scenes account linking.

Problem Summary

• Current: Logging in via Google succeeds and creates a Keycloak user; logging in later with GitHub (same email) fails with “User already exists.”

• Goal: Allow users to authenticate with any configured IdP using the same email, automatically linking new IdPs to the existing Keycloak account, with no Keycloak UI exposure and no duplicate users.

High‑Level Solution

1. Configure First Login Flow per IdP to auto‑link by email.

2. Ensure deterministic user matching and disable interruptions (confirmation/verification steps).

3. Force IdP redirect from applications to avoid rendering Keycloak login UI.

4. Keep a single local user with multiple Federated Identity links.

5. Developed an authentication flow supporting multiple IDP logins with the same email condition:

   1. Detect existing broker user (disabled)
   2. Create a user if unique (alternative)
   3. Automatically set the existing user (alternative)
   4. Configured Keycloak to make the last name field optional.

Step‑by‑Step Implementation

1) Create a custom First Broker Login flow for auto‑linking

• Go to Authentication → Flows → Create a new flow (e.g., “Auto‑Link by Email”).

• Add the following executions with the Requirement set to Alternative:

  • Create User If Unique

  • Automatically Set Existing User

• Rationale:

  • Create User If Unique only creates a new local user when none exists; otherwise it defers.

  • Automatically Set Existing User links the incoming IdP identity to the already existing user (matching by email/username) without prompting.

• Assign this flow as the First Login Flow in each social IdP configuration (Google, GitHub). This eliminates the “User already exists” prompt and silently links identities when emails match

Optional variants:

• If only pre‑registered users may log in, use “Detect Existing Broker User” + “Automatically Set Existing User” both Required to only allow linking to existing accounts and skip prompts.

2) Align realm login settings for consistent matching

• In Realm Settings → Login:

  • Consider turning Email as username: Off, Login with email: Off, Duplicate emails: On for advanced cases where usernames drive uniqueness; otherwise keep Duplicate emails: Off for strict single‑email identity and rely on the flow above. This can help with multi‑IdP scenarios, but must fit org policy

• For OIDC IdPs:

  • Enable Trust email where appropriate and set Sync Mode to FORCE to keep profile data in sync and mark email verification based on the IdP’s email_verified claim; this reduces friction and avoids extra verification steps during linking.

• Keep SMTP disabled in the First Broker Login flow if wanting to avoid “Verify Existing Account by Email” prompts; the auto‑link flow removes that step.

3) Make Keycloak invisible to end users

• In the Browser flow, configure Identity Provider Redirect with a default IdP (or use kc_idp_hint from the application) so users are immediately redirected to the chosen IdP without seeing the Keycloak login page.

4) Validate acceptance criteria

• Log in first with Google → user created and authenticated.

• Log out, then log in with GitHub using the same email → success, no error, GitHub is linked to the same Keycloak user.

• Check the user’s Federated Identities tab to confirm both IdPs are linked; verify no duplicate users are created.

• Application never shows Keycloak UI because of direct IdP redirect.

Notes and Edge Cases

• Auto‑linking by email is powerful and should be used when emails are authoritative and unique across IdPs; otherwise consider custom authenticators that match on other attributes to avoid accidental account takeovers.

• If emails differ across IdPs for the same person, a custom authenticator SPI or operational linking process is required; the default email match will not link those accounts automatically.

• For fully curated environments, the “Automatically link existing first login flow” is explicitly documented as appropriate if user registration and identifiers are controlled and trusted.

• Community guidance and prior solutions support the two‑step First Broker Login configuration (Create User If Unique + Automatically Set Existing User) to skip the “Account Already Exists”/link confirmation page and achieve seamless linking.