The First Broker Login Flow in Keycloak
A zero-prior-knowledge guide to the one-time handshake Keycloak runs the very first time someone logs in through Google, a partner company, or any other external identity provider — and how it decides whether that stranger is actually someone it already knows.
Imagine a hotel that lets guests check in either with their own hotel loyalty card or with a boarding pass from a partner airline. The very first time someone shows up with an airline boarding pass instead of a loyalty card, the front desk has a genuinely tricky decision to make: is this the same person who already has a loyalty account under a different name, or is this a brand-new guest who has simply never stayed here before? Every subsequent visit with that same boarding pass is easy — the front desk remembers the answer. But that very first encounter needs its own special, careful procedure. Keycloak faces exactly this problem whenever a user logs in through an external identity provider like Google, Microsoft, or a partner company’s own Keycloak realm, and it solves it with something called the First Broker Login Flow. This article walks through, from the ground up, what that flow actually is, why it only runs once per user per identity provider, and what decisions an administrator controls inside it.
Foundations
Core Concepts
To understand the First Broker Login Flow, we first need to understand what “identity brokering” even means, and why logging in through someone else’s system is fundamentally different from logging in with a password Keycloak itself manages.
What is Identity Brokering?
Identity Brokering is Keycloak’s ability to delegate the actual proof of identity to an external system, called an Identity Provider, or IdP, rather than checking a password itself. When a user clicks “Sign in with Google” on an application protected by Keycloak, Keycloak does not verify anything on its own — it redirects the user to Google, waits for Google to confirm who the person is, and then receives that confirmation back. Keycloak acts as the trusted middleman, or broker, between the application and the external identity provider.
Why the very first login is special
Every login after the first one is straightforward: Keycloak already has a local record linking “this Google account” to “this specific Keycloak user,” so it simply looks up the match and lets the person in. But the very first time a brand-new external identity shows up, no such link exists yet, and Keycloak has to make several careful decisions before it can safely create one. Should it create a brand-new Keycloak user from scratch? Or does this external identity actually belong to someone who already has an existing Keycloak account, perhaps created earlier with a plain username and password? Getting this decision wrong could either annoy a real user with an unnecessary duplicate account, or worse, silently merge two different people’s identities together.
Picture a company merger, where employees from Company A start showing up at Company B’s office using their old Company A badges. The very first time each person swipes their Company A badge at Company B’s front desk, security cannot just wave them through automatically — someone has to check: does this person already have a Company B badge under a different name? Are they entirely new? Once that one-time check is done and recorded, every future swipe with the same Company A badge is instant and automatic. The First Broker Login Flow is that one-time front-desk check.
What gets created as a result
Once the First Broker Login Flow completes successfully, Keycloak permanently stores a federated identity link — a durable record connecting the specific external account (say, a particular Google account) to a specific Keycloak user. From that point forward, every future login through that same external provider skips the entire First Broker Login Flow and goes straight to a normal, fast login, because the hard question has already been answered once and recorded.
First Broker Login Flow
Executes only the very first time a specific external identity is seen for a specific identity provider.
Ordinary Post Broker Login
Once linked, subsequent logins through the same provider follow the regular, much simpler authentication path.
Link or Create?
Does this external identity belong to an existing Keycloak user, or does it need a brand-new one created?
Federated Identity Link
A permanent record tying the external account to a specific Keycloak user, checked on every future login.
Structure
Architecture & Components
Like every login sequence in Keycloak, the First Broker Login Flow is built from a series of individually configurable steps, arranged inside the same flow engine used elsewhere in the platform.
Identity Provider configuration
Every external Identity Provider connected to a realm has its own settings page, and one of those settings explicitly names which authentication flow should be used as its First Broker Login Flow. Different identity providers connected to the same realm can each point to a different First Broker Login Flow, allowing very different handling for, say, a trusted internal partner company versus a general public Google login.
The default First Broker Login Flow steps
Keycloak ships with a default First Broker Login Flow made up of several individual executions, each one a small, focused decision point. A Review Profile step lets the user confirm or edit the basic profile information received from the external provider before an account is created. A Create User If Unique step checks whether any existing Keycloak user already shares the same email address or username. A Confirm Link Existing Account step steps in specifically when a matching existing account is found, asking the user to prove they actually own that existing account before linking anything. An Automatically Set Existing User step, when enabled, can link accounts by trusted email match without requiring a manual confirmation step at all.
Executions and requirement levels
Just like other Keycloak flows, each step in the First Broker Login Flow carries a requirement level — Required, Alternative, Conditional, or Disabled — controlling whether that particular decision point actually runs for a given situation. This is what allows an administrator to, for example, disable the manual confirmation step entirely for a specific trusted partner identity provider, while keeping it firmly required for a general-purpose consumer login like Google.
flowchart TD
A["User logs in via external IdP for the first time"] --> B["Keycloak receives identity claims: email, name"]
B --> C["Review Profile step"]
C --> D["Create User If Unique check"]
D -->|"No existing match found"| E["New Keycloak user created"]
D -->|"Matching email found"| F["Confirm Link Existing Account step"]
F -->|"User proves ownership"| G["Federated Identity Link created to existing user"]
F -->|"User cannot confirm"| H["Login denied / account creation blocked"]
E --> I["Federated Identity Link created to new user"]
G --> J["Future logins skip this flow entirely"]
I --> J
Fig 1 — The core decision branches inside a default First Broker Login Flow.
The diagram highlights the single most important fork in the entire flow: what happens when the incoming external identity’s email address matches an account that already exists in Keycloak. Everything about how safely — or how riskily — an organization handles account linking comes down to how that one fork is configured.
This chapter looks closely at what Keycloak is actually checking, and why, at each individual step of the default flow.
Receiving claims from the external provider
After the external identity provider successfully authenticates the user on its own side, it sends Keycloak a set of claims — pieces of information about the user, typically including an email address, a name, and a unique identifier specific to that provider. Keycloak treats this unique provider-specific identifier as the true, permanent handle for the federated identity, while the email address becomes the primary signal used to check for a possible existing match.
The Review Profile step in detail
Because different identity providers return different amounts of profile information — some send a full name and email, others send very little — the Review Profile step gives the user a chance to fill in any missing required fields, or correct information before an account is finalized. Administrators can configure whether this step is shown to every user, or only when required information is genuinely missing.
The Create User If Unique check in detail
This step performs the actual lookup: does any existing Keycloak user in this realm already have the same email address as the one just received from the external provider? If no match is found, this step lets a brand-new Keycloak user be created immediately, with a fresh federated identity link pointing to it. If a match is found, control passes to whichever account-linking step the flow has configured next.
Think of a lost-and-found desk that receives a wallet with a name and photo on the driver’s license inside. Before handing it back, the clerk checks whether anyone matching that exact name has already filed a report for a lost wallet. If nobody has, the clerk simply logs the wallet as newly found under that person’s details. If someone has, the clerk does not just hand it over on the name alone — they ask a follow-up question to confirm it truly belongs to that specific person before releasing it.
Confirm Link Existing Account in detail
When a matching email is found, simply trusting the external provider’s word that “this is the same person” is risky, because email addresses can sometimes be reused, mistyped, or, in rare cases, spoofed by a provider with weaker verification standards. The Confirm Link Existing Account step addresses this by requiring the user to actually prove ownership of the existing Keycloak account — commonly by entering that account’s existing password — before the two identities are permanently linked together.
Automatically Set Existing User as an alternative
For identity providers that an organization trusts completely to verify email ownership accurately — often an internal corporate identity provider — the Automatically Set Existing User execution can replace the manual confirmation step entirely, linking accounts purely on a matching, trusted email address without asking the user to prove anything further. This trades a small amount of caution for a noticeably smoother login experience, and is only appropriate when the incoming identity provider’s email verification can genuinely be trusted.
Lifecycle
Data Flow & Lifecycle
Following one real person through their very first external login, from click to completed account, shows exactly how the pieces fit together in sequence.
User clicks “Sign in with Google”
The application redirects the user’s browser to Keycloak, which in turn redirects to Google’s own login page, since Google is configured as an external Identity Provider for this realm.
Google authenticates the user
The user proves their identity directly to Google, using whatever method Google itself requires, entirely outside Keycloak’s involvement.
Google redirects back with claims
Google sends the user’s browser back to Keycloak, carrying a signed set of claims that includes the user’s email address and name.
Keycloak checks for an existing federated identity link
Because this is the very first time this specific Google account has ever appeared, no existing link is found, so Keycloak triggers the First Broker Login Flow rather than a normal login.
The flow’s steps run in order
The user reviews their profile information, Keycloak checks for a matching existing account by email, and either a new account is created or the user confirms ownership of a matching existing one.
The federated identity link is saved
Keycloak permanently stores the connection between this specific Google account and the resulting Keycloak user, and issues the login session and tokens exactly as it would for any successful login.
Every future login is simple
The next time this same person clicks “Sign in with Google,” Keycloak finds the existing federated identity link immediately and skips the First Broker Login Flow entirely, going straight to a normal, fast login.
Weighing the Choice
Advantages, Disadvantages & Trade-offs
The way an organization configures the account-linking behavior inside this flow is a direct trade-off between login convenience and the risk of incorrectly connecting two different people’s identities.
Advantages of the Flow’s Design
- Lets an organization support multiple external login options — Google, a partner company, social logins — without duplicating identity management for every provider
- Runs only once per identity, meaning it has no ongoing performance impact on regular, everyday logins
- Gives administrators fine-grained control over exactly how cautious or how seamless account linking should be, per identity provider
- Prevents accidental duplicate accounts for users who already had a password-based account before adopting a new external login option
Disadvantages & Trade-offs
- A manual confirmation step, while safer, adds real friction to a user’s very first external login experience
- Automatic linking by email trust, while smoother, is only as safe as the trustworthiness of the external identity provider’s own email verification
- Misconfiguration of this flow is easy to overlook during setup, since its behavior is invisible until a real “matching email” scenario actually occurs
- Testing all the branching outcomes thoroughly requires deliberately simulating both brand-new users and users with pre-existing accounts
Choosing the right level of caution per provider
Not every identity provider deserves the same level of trust. A well-known consumer provider with a long track record of strict email verification might reasonably be configured for smoother, more automatic linking, while a newly integrated or less well-understood external provider warrants the full manual confirmation step, even at the cost of a slightly less seamless first-time experience for legitimate users.
Defense
Security
Because the First Broker Login Flow decides whether two identities get permanently merged, it is one of the highest-stakes moments in the entire identity-brokering system.
Account takeover through unverified email linking
The single most serious risk in this entire area is automatically linking accounts purely by email match, when the external identity provider itself does not reliably verify that the email it reports actually belongs to the person logging in. If an attacker can register an external account using someone else’s email address — on a provider with weak verification — and that email happens to match an existing Keycloak user, automatic linking without confirmation could hand the attacker access to that existing account.
It is tempting to assume that any external identity provider reliably verifies the email addresses it sends. In reality, verification practices vary significantly between providers, and some allow unverified or user-entered email fields. Automatic account linking should only ever be enabled for providers whose email verification is genuinely trustworthy — never as a blanket default.
Why “Confirm Link Existing Account” matters as a default
Requiring the user to actually authenticate into the existing account — proving they know its password — before linking closes the exact gap described above. Even if an attacker’s external identity happens to share an email address with a real Keycloak user, the attacker cannot complete the link without also knowing that existing account’s actual credentials, which defeats the attack.
Reviewing which identity providers use which flow
Because different identity providers in the same realm can each be assigned a different First Broker Login Flow, periodically reviewing this mapping is important, especially as new providers are added over time. A provider added quickly for a specific integration project can easily be left pointing at an overly permissive flow if this configuration is not explicitly checked.
Protecting the profile review step from injection
Since the Review Profile step can display and allow editing of information received from an external, untrusted source, applications and administrators should ensure this information is handled the same way any other user-supplied input would be, rather than assuming it is automatically safe simply because it originated from an identity provider rather than directly from the end user.
Visibility
Monitoring, Logging & Metrics
Because the First Broker Login Flow only runs once per identity, spotting problems with it requires paying attention at exactly the right moment — the very first login through a given provider.
Relevant events to track
Keycloak’s event logging system records identity brokering activity, including successful federated identity links being created, and failed linking attempts. Watching specifically for account-linking events tied to the First Broker Login Flow — rather than ordinary login events — gives administrators visibility into exactly how often new external identities are being connected, and to which existing accounts.
What a spike in failed confirmations might mean
A cluster of failed “Confirm Link Existing Account” attempts, especially targeting the same existing account from different external identity attempts, can be a meaningful signal — it may indicate someone repeatedly trying to link an unauthorized external identity to a specific victim’s account by guessing at its password during the confirmation step, which is precisely the attack the confirmation step exists to stop.
Auditing the identity-provider-to-flow mapping
Because this configuration is set once per identity provider and rarely revisited, it is worth including in periodic security reviews specifically: confirming which First Broker Login Flow each connected identity provider currently uses, and whether that level of caution still matches how much the organization actually trusts that provider today.
Shape
Design Patterns & Anti-patterns
Organizations that operate multiple external identity providers over time tend to converge on a small number of recurring, sensible patterns — and a few recurring mistakes.
Pattern: Tiered trust by provider
Mature deployments configure a stricter, manual-confirmation First Broker Login Flow for general-purpose or lower-trust providers, while reserving a smoother, automatic-linking flow only for providers whose identity verification the organization has specifically evaluated and trusts, such as a tightly controlled internal corporate identity system.
Pattern: Custom flows for regulated onboarding
Organizations in regulated industries sometimes extend the default flow with additional custom steps — for example, requiring acceptance of updated terms of service, or capturing additional compliance-related information — specifically during this one-time first login, rather than adding friction to every ordinary subsequent login.
Pattern: Dedicated realms instead of shared linking
Some organizations sidestep the account-linking question almost entirely by keeping external-identity users in a completely separate realm from password-based users, avoiding the need for a permissive linking policy at all, at the cost of maintaining two separate user populations.
Anti-pattern: Enabling automatic linking as a global default
A common and risky mistake is enabling automatic, unconfirmed account linking across every identity provider in a realm simply to reduce friction for users, without evaluating whether each individual provider’s email verification is actually trustworthy enough to justify skipping confirmation.
Situation
A team adds several social login providers to speed up user onboarding, and copies the same permissive, automatic-account-linking First Broker Login Flow across all of them to keep the login experience consistent and frictionless.
Consequence
One of the added providers turns out to allow unverified, user-entered email addresses, and an incident later reveals that an account could theoretically have been linked to an existing user’s account without ever proving ownership of it, purely through a matching but unverified email claim.
Better Approach
Evaluate each identity provider’s email verification practices individually before deciding its First Broker Login Flow, defaulting to manual confirmation unless a specific provider has been deliberately reviewed and trusted for automatic linking.
Getting It Right
Best Practices & Common Mistakes
A handful of deliberate decisions, made early, prevent the First Broker Login Flow from becoming a quiet source of either account-takeover risk or endless duplicate-account support tickets.
Default to manual confirmation
Treat automatic account linking as an exception that must be earned by a specific, evaluated identity provider — not a convenience applied everywhere.
Test both branches deliberately
Explicitly test what happens for a genuinely new user and for a user with a pre-existing matching account, since the second scenario is easy to overlook during setup.
Review the Review Profile step’s required fields
Make sure the fields marked required actually match what your application genuinely needs, since providers vary widely in what information they supply by default.
Audit provider-to-flow mappings periodically
Revisit which First Broker Login Flow each identity provider uses whenever trust assumptions about that provider might have changed.
Assuming the default flow is always appropriate
The default is a reasonable general-purpose starting point, not a guarantee that it fits every identity provider’s actual trust level.
Forgetting this flow only runs once
Teams sometimes debug login issues by repeatedly testing with the same test account, never realizing the First Broker Login Flow has already completed and is no longer even running for that identity.
When testing changes to the First Broker Login Flow, remove the existing federated identity link for your test user, or use a brand-new test account each time, since a previously linked identity will simply skip the flow entirely and make it look like your configuration changes had no effect.
The First Broker Login Flow shows up wherever an organization lets people arrive through more than one front door — and each industry tends to lean toward a different balance of caution and convenience.
Consumer platforms with social login
Consumer applications offering “Sign in with Google” or similar social login options alongside a traditional email-and-password signup frequently rely on this flow’s account-matching logic specifically to catch users who already registered directly, preventing them from unknowingly ending up with two separate accounts under the same email.
Business-to-business partner integrations
Companies that let employees of partner organizations log in using the partner’s own identity provider commonly configure a stricter First Broker Login Flow, since business partnerships often involve sensitive shared resources where an incorrectly linked account could expose one partner’s data to the wrong person.
Enterprise mergers and acquisitions
Organizations going through a merger frequently connect the acquired company’s existing identity system as a new external identity provider to a shared Keycloak realm, relying on the First Broker Login Flow’s account-matching logic to gradually and safely reconcile employees who may already have accounts in both systems under the same corporate email address.
Government single sign-on portals
Public-sector portals that accept login through a national digital identity system alongside a locally managed citizen account frequently configure careful, manual-confirmation linking, given the high sensitivity of correctly matching a verified national identity to the right existing citizen record.
Questions Answered
FAQ
Wrapping Up
Summary & Key Takeaways
The First Broker Login Flow solves a problem that only ever appears once per relationship between a user and an external identity provider, but getting that one moment right matters enormously. It is the single point where Keycloak decides whether an incoming external identity represents someone brand new, or someone who already has a history inside the system under a different login method. Every configuration choice inside this flow — whether to review the profile, whether to require manual confirmation, whether to trust automatic linking — is really a choice about how much caution that one-time decision deserves, weighed against how smooth the very first login experience should feel.
Key Takeaways
- The flow runs exactly once per external identity, per identity provider — every subsequent login through the same provider skips it entirely.
- Its central job is answering one question — does this external identity belong to a brand-new user, or does it match someone who already has an account?
- Review Profile, Create User If Unique, and Confirm Link Existing Account are the default building blocks — each addressing a different part of that central question.
- Automatic linking trades caution for convenience — it should only be enabled for identity providers whose email verification is genuinely trustworthy.
- Different identity providers can use different flows — letting an organization apply stricter caution to lower-trust providers and smoother handling to trusted ones.
- Testing requires fresh identities — an already-linked test account will simply skip the flow, hiding the effect of configuration changes unless the link is removed first.
- The result is a permanent federated identity link — the durable record that makes every future login through that provider fast and simple.