Before looking at Keycloak specifically, it helps to isolate the general problem being solved.

Account linking is the process of connecting a user’s login through an external identity source — such as Google, a corporate directory, or another company’s identity system — to one single, existing local account, rather than treating each login source as a completely separate, unrelated identity.

Without account linking, a person who first registered directly with a username and password, and later tries logging in through “Sign in with Google” using the same email address, might end up with two disconnected accounts: their original one, and a brand-new one created automatically because Keycloak has no way of knowing these two logins belong to the same human being unless it is told so, deliberately and securely.

Account linking cannot be understood in isolation from the broader brokering system it depends on.

Keycloak can be configured to trust one or more external identity providers — outside systems capable of authenticating a user on Keycloak’s behalf. When this is set up, Keycloak is acting as an identity broker: rather than checking a password itself, it redirects the user to the external provider, waits for that provider to confirm who the user is, and then translates that confirmation into a Keycloak session.

Every time a user authenticates through one of these external providers for the first time, Keycloak faces a decision point: is this a brand-new person who has never been seen before, or is this actually someone who already has a local account, just arriving through a different front door? Account linking is precisely the mechanism that resolves that decision correctly.

Understanding the moving pieces clarifies how linking decisions actually get made and stored.

These pieces work together: the federated identity record is what makes the connection permanent, the first broker login flow is what decides whether and how a new connection gets created automatically, and the account console is where a user can manage those connections directly and deliberately.

Keycloak supports linking through two distinctly different journeys, suited to different situations.

Automatic linking based purely on a matching email address is convenient, but it carries real risk if the external provider does not reliably verify email ownership, which is discussed further in the security chapter. Confirmation-based linking trades a small amount of user friction for a meaningfully stronger guarantee that the person completing the link genuinely controls both identities. Self-service linking, by contrast, carries the least risk of all, because it can only happen while the user is already authenticated and knowingly adding a new option to their own account.

Here is the sequence Keycloak follows the very first time it sees a particular identity coming from an external provider.

Here is the end-to-end flow from an external login attempt through to a fully linked account.

sequenceDiagram
    participant U as User
    participant K as Keycloak
    participant IDP as External Identity Provider
    U->>K: Chooses "Sign in with Provider"
    K->>IDP: Redirects for authentication
    IDP-->>K: Confirms identity
    K->>K: Checks for existing federated identity record
    alt No link found
        K->>K: Runs first broker login flow
        alt Match found
            K->>U: Prompts to confirm linking (or auto-links)
        else No match
            K->>K: Creates a new local account
        end
    else Link already exists
        K->>K: Recognizes returning linked user
    end
    K-->>U: Issues session tied to the correct local account
        

Notice that this entire decision process happens only once per external identity — on every subsequent login, Keycloak simply recognizes the already-stored federated identity record and moves straight to issuing a session, without repeating the matching or confirmation logic. This is precisely why the very first login through a new provider deserves the most careful configuration: it sets a decision that persists indefinitely afterward.

Account linking meaningfully improves user experience, but it comes with genuine design trade-offs to consider.

Account linking, done carelessly, can quietly become a way for one person to take over another person’s account.

The core risk: unverified email matching

If Keycloak is configured to automatically link accounts purely because an external provider reports the same email address, and that external provider does not strictly verify email ownership before allowing account creation, an attacker could register an external account using someone else’s email address and be automatically linked into that victim’s existing local account.

Account takeover through dangling links

If a user’s local account password is compromised, and an attacker uses that access to link an additional external identity provider to it through the account console, the attacker gains a lasting, independent way back into the account even after the original compromised password is changed. This is why reviewing linked identities is often recommended as part of a broader account-recovery security process.

Consistent identity verification across providers

Applying uniform, careful thought to how each external provider’s identity claims are trusted — not assuming every provider behaves the same way — is essential groundwork before enabling any form of automatic linking.

Because account linking decisions happen quietly and only once per identity, dedicated visibility is important for catching problems early.

Many organizations also maintain an audit trail specifically for identity-provider linking events, separate from general login logs, since these events represent a structural change to an account’s authentication options rather than a routine login.

A few recurring patterns separate a safe, well-designed linking strategy from a risky one.

Pattern: Provider-specific linking rules

Rather than applying one uniform linking policy to every external provider, mature deployments configure trust levels per provider — allowing automatic linking for providers with strong email verification, while requiring confirmation for providers where that guarantee is weaker or unknown.

Pattern: Clear self-service visibility

Giving users an easy, discoverable way to see and manage exactly which external identities are linked to their account, through the account console, builds trust and gives users the ability to notice and remove a link they did not authorize.

A practical checklist for teams configuring or reviewing account linking.

Account linking quietly supports many everyday login experiences people rarely think twice about.

Yes. A single local account can maintain separate federated identity links to several different external providers simultaneously, allowing a user to log in through any of them and always reach the same account.

Keycloak prevents this, since a single external identity can only be federated to one local account at a time — otherwise the entire purpose of linking, avoiding ambiguity about which account a login belongs to, would break down.

Yes, typically through the account console, provided the user still has at least one remaining way to authenticate afterward, so they are never accidentally locked out of their own account.

Not quite. Account linking connects a new external identity to one existing local account. Merging two already-existing, previously separate local accounts into one is a related but distinct administrative operation with its own considerations.

Not directly — the tokens issued still follow whatever protocol mappers are configured, as covered in Keycloak’s claim customization features. Linking determines which local account a login resolves to, not what information that account’s tokens carry.

Confirmation-based linking closes the door on the specific risk where an external provider’s email address cannot be fully trusted as proof of ownership, at the cost of a small extra step the very first time a new identity is encountered.

Account linking is the quiet mechanism that keeps a person’s identity coherent across every door they choose to walk through — a password, a social login, a corporate identity provider — resolving each one back to a single, authoritative local account rather than a scattering of disconnected identities. Built on top of Keycloak’s identity brokering system, it offers real flexibility in how that resolution happens, from fully automatic matching to deliberate, confirmation-based, or entirely self-service linking. The security stakes are genuine, since a careless automatic-linking configuration can open a path for one person to slip into another’s account, which is exactly why thoughtful, provider-by-provider trust decisions and ongoing review matter as much as the initial setup.