Last updated: June 2026
The “account already exists” message appears during identity brokering when a user logs in through an external identity provider (Google, GitHub, a SAML IdP) but Keycloak already has a local account with the same email address. This is Keycloak’s First Broker Login flow protecting against account hijacking, not a bug. You resolve it by linking the brokered identity to the existing account — either through the default email-verification or re-authentication steps — or by customizing the first-login flow to auto-link when the external IdP marks the email as verified.
Why the Error Occurs
Keycloak separates two concepts that users often treat as the same thing: an email address and an identity. When you create a local account for [email protected] and Alice later tries to log in with “Sign in with Google” using the same address, Keycloak sees a conflict: it has a local user record for that email, but the incoming Google identity has no link to it.
Rather than silently merging the two — which would let anyone who controls an external IdP account claim ownership of a pre-existing local account — Keycloak stops and asks the user to confirm the link. This is the correct behavior from a security standpoint, and it is controlled entirely by the First Broker Login flow.
The exact error message varies by Keycloak version, but common forms include:
- “User with email [email protected] already exists. How do you want to continue?”
- “Account already exists. Please re-authenticate to link your account.”
- A redirect to an intermediate page asking the user to verify ownership of the existing account
Understanding which step in the First Broker Login flow triggered the message is the first step toward fixing it.
The First Broker Login Flow
The First Broker Login flow runs exactly once per user per identity provider — the first time a brokered identity is seen by Keycloak. After the link is established, subsequent logins through that IdP skip this flow entirely and go straight to the existing Keycloak user.
Keycloak’s default First Broker Login flow includes the following executions, in order:
| Step | Execution | Default Requirement | What It Does |
|---|---|---|---|
| 1 | Review Profile | Required | Lets the user review and correct profile data coming from the IdP |
| 2 | Create User If Unique | Alternative | Creates a new Keycloak user if no existing account shares the email |
| 3 | Handle Existing Account | Required (sub-flow) | Runs only when step 2 finds a duplicate |
| 3a | Confirm Link Existing Account | Required | Shows the “account already exists” prompt |
| 3b | Verify Existing Account by Email | Alternative | Sends a confirmation email to prove ownership |
| 3c | Verify Existing Account by Re-authentication | Alternative | Prompts for the local account’s password |
When a user hits the “account already exists” screen, the flow has reached step 3a. The user will then be routed through either 3b (email verification) or 3c (password re-authentication) depending on which alternative is enabled and satisfiable.
To view and edit this flow in the admin console, go to Authentication > Flows, then select first broker login from the dropdown.
For a broader look at how flows work in Keycloak, the custom authentication flows guide walks through flow structure, execution requirements, and how to build new flows from scratch.
The Secure Default: Verification Before Linking
The default behavior — requiring the user to verify ownership before linking — is the right choice for most deployments. It prevents a class of attack where a malicious actor registers an account on an external IdP using a victim’s email address and then uses that to take over the victim’s Keycloak account.
Verify Existing Account by Email sends a one-time link to the address on file. If the user can open that link, they have proven access to the mailbox associated with the existing account. Keycloak then links the brokered identity and the local account, and the user is logged in.
Verify Existing Account by Re-authentication prompts the user to enter their local Keycloak password. This is slightly more friction but does not depend on email deliverability.
Both approaches are safe. Choose based on your user population: if your users are likely to have forgotten their local password (common in consumer apps that added social login after launch), email verification is friendlier.
Automatic Linking: When and How to Use It
Some deployments want to skip the confirmation step entirely. If your external IdP is a corporate SAML provider or a Google Workspace domain you control, and you are confident that the IdP only issues tokens for verified email addresses, you can configure Keycloak to link accounts automatically.
This is done by combining two settings:
- Trust Email on the identity provider configuration
- A custom First Broker Login flow using the Detect Existing Broker User and Automatically Set Existing User authenticators
Step 1: Enable Trust Email on the IdP
In the Keycloak admin console:
- Go to Identity Providers and select your provider
- Open the Settings tab
- Enable Trust Email
When Trust Email is on, Keycloak treats the email claim from that IdP as already verified. It will not send an additional verification email for accounts created through this provider.
This setting alone does not auto-link accounts. It only affects whether newly created accounts are marked as email-verified. To actually skip the linking prompt, you also need to customize the First Broker Login flow.
For more detail on how IdP-level settings interact with the brokering process, see our guide on attribute mapping during OIDC identity brokering.
Step 2: Create a Custom First Broker Login Flow
You cannot edit the built-in first broker login flow directly. You must copy it first.
- Go to Authentication > Flows
- Select first broker login in the dropdown
- Click Action > Duplicate and give the copy a name (e.g., “first broker login – auto link”)
- In your new flow, find the Handle Existing Account sub-flow
- Delete or disable the Confirm Link Existing Account, Verify Existing Account by Email, and Verify Existing Account by Re-authentication executions
- Add a new execution: Detect Existing Broker User (set to Required)
- Add another execution: Automatically Set Existing User (set to Required)
- Confirm the order: Detect Existing Broker User must come before Automatically Set Existing User
Step 3: Assign the Flow to Your IdP
- Go to Identity Providers and select your provider
- Open the Settings tab
- Scroll to First Login Flow
- Select your new custom flow from the dropdown
- Save
Now, when a user logs in through this IdP with an email that matches an existing Keycloak account, Keycloak will detect the existing user and link the identity automatically — no prompt shown.
If you need to understand how this IdP configuration works in a concrete social login context, our guides on GitHub social login via identity brokering and Google, Apple, and GitHub social login setup cover the full IdP configuration from scratch.
Security Warning: Do Not Blindly Trust Unverified Emails
Auto-linking is safe only when the IdP guarantees that the email address in the token belongs to the authenticated user and has been verified. Many public IdPs do not make this guarantee for all account types.
For example:
- GitHub allows users to set any email in their profile, including unverified ones. A GitHub token can contain an email address the user does not actually own.
- Some SAML IdPs pass email as an attribute without confirming delivery.
- Consumer OAuth providers may include email claims for accounts that have not completed email verification.
If you enable auto-linking with Trust Email for an IdP that passes unverified email addresses, you create an account takeover vector: an attacker creates an IdP account using [email protected], logs in through your Keycloak, and Keycloak automatically links that brokered identity to the victim’s existing account.
The rule is simple: only enable auto-linking when you control the IdP or have verified through the provider’s documentation that all email claims are confirmed addresses. For enterprise SAML IdPs (Entra ID, Okta, Google Workspace in a managed domain) this is generally safe. For public social providers, use the default verification flow.
For broader context on social login security considerations, see the guide on social login with Google, Apple, and GitHub in Keycloak.
Symptom, Cause, and Fix Reference
| Symptom | Root Cause | Fix |
|---|---|---|
| “Account already exists” prompt on first social login | Local account with matching email already exists; no IdP link established | Walk through email verification or re-authentication in the default flow |
| User is stuck in a loop at the “account already exists” screen | Email verification link expired or password re-authentication failing | Have user complete the appropriate verification step, or reset their local password |
| Auto-link not working after enabling Trust Email | Custom first-login flow not assigned to the IdP | Assign the custom flow in Identity Providers > {idp} > First Login Flow |
| New accounts are not marked as email-verified | Trust Email not enabled on the IdP | Enable Trust Email in Identity Providers > {idp} > Settings |
| Auto-linking occurs for IdP accounts with unverified emails | Trust Email enabled on an IdP that does not verify emails | Disable auto-linking; revert to default verification flow for that IdP |
| User cannot link account because they forgot their local password | Re-authentication step requires local credentials | Configure the flow to use email verification as the alternative, or trigger a password reset |
Step-by-Step: Fixing the Error in the Admin Console
If you want to resolve the “account already exists” error for a specific user without changing the flow, you can manually create the IdP link from the admin console.
- Go to Users and find the existing local account (search by email)
- Open the user record and click the Identity Provider Links tab
- Click Add identity provider link
- Select the identity provider
- Enter the Identity Provider Username — this is the user’s ID or username at the external IdP, not their email. For Google, it is the numeric subject ID from the ID token. For GitHub, it is the numeric user ID.
- Save
The user can now log in through that IdP without hitting the “account already exists” prompt. No verification step is required because an administrator performed the linking.
This approach is practical for small teams or one-off migrations. For bulk migrations — for example, importing a user base from an external system and pre-linking their IdP identities — the Admin REST API provides a POST /admin/realms/{realm}/users/{id}/federated-identity/{provider} endpoint.
If you are using kc_idp_hint to send users directly to a specific provider, the account-linking flow still applies on the first login. Our guide on using kc_idp_hint to select an identity provider covers that parameter in detail.
Keycloak 26 Specifics
As of Keycloak 26.x, the First Broker Login flow and the identity provider Trust Email setting work as described above. The admin console paths are:
- Authentication > Flows: flow list and editor
- Authentication > Flows > first broker login: the default flow (read-only; duplicate before editing)
- Identity Providers > {your-idp} > Settings > Trust Email: toggle (default: off)
- Identity Providers > {your-idp} > Settings > First Login Flow: dropdown to assign a custom flow
- Users > {user} > Identity Provider Links: manual link management
The Detect Existing Broker User and Automatically Set Existing User authenticators are available as built-in executions in Keycloak 25+ and do not require any SPI installation.
Frequently Asked Questions
Why does Keycloak say “account already exists”?
Keycloak stores users and their identity provider links separately. When a user who already has a local account (created via registration, admin, or LDAP sync) tries to log in through an external IdP for the first time, Keycloak detects the email collision and runs the Handle Existing Account sub-flow. It presents the “account already exists” prompt to confirm the user actually owns the local account before creating the link. This protects against account takeover via external IdP registration.
How do I auto-link accounts in Keycloak?
Auto-linking requires two changes: enable Trust Email on the identity provider in Identity Providers > {idp} > Settings, and assign a custom First Broker Login flow that includes the Detect Existing Broker User and Automatically Set Existing User executions (in that order) instead of the confirmation and verification steps. Assign the custom flow to the IdP via the First Login Flow dropdown in the same settings page.
Is automatic account linking in Keycloak safe?
Automatic linking is safe only when the identity provider guarantees that the email address in the token is verified and belongs to the authenticated user. It is appropriate for enterprise SAML providers (Entra ID, Okta, Google Workspace) where your organization controls the IdP and email verification is enforced. It is not safe for public social providers like GitHub or Twitter where unverified email addresses can appear in tokens. Enabling auto-linking for an IdP that passes unverified emails creates an account takeover vulnerability.
Can I link accounts without the user doing anything?
Yes, via the Keycloak Admin REST API or through the admin console’s Identity Provider Links tab on the user record. An administrator can create a federated identity link for any user, specifying the IdP and the user’s subject identifier at that IdP. This bypasses all verification steps and is intended for migrations or administrative corrections, not for automated user-facing flows.
What happens if the user loses access to the email address used for verification?
If the Verify Existing Account by Email step is the only alternative in the Handle Existing Account sub-flow and the user cannot access the email, they will be blocked. Solutions: configure Verify Existing Account by Re-authentication as a second alternative (it prompts for the local password instead), or have an administrator manually create the IdP link from the admin console. Enabling both alternatives gives users a fallback.
Dealing with identity brokering errors often signals that your Keycloak deployment has grown to the point where flow customization, IdP management, and user account hygiene need dedicated attention. If you would rather focus on your product than on Keycloak operations, Skycloak provides managed Keycloak hosting with preconfigured identity provider support, expert-level configuration help, and a team that handles upgrades and infrastructure — so your engineering team can spend time on what matters.