What Is Identity Brokering?

Identity Brokering is the arrangement where Keycloak, instead of authenticating a user itself using its own stored password, delegates that authentication to an external identity system, then translates the result of that external login into Keycloak’s own standard tokens — the same ID Tokens and Access Tokens covered elsewhere in this series — so that every connected application continues to see one single, uniform login experience, entirely unaware of which external system actually did the work.

The External Identity Provider (IdP)

In this arrangement, the outside system that actually verifies who the user is — Google, Microsoft Entra ID, a partner organization’s own Keycloak or other identity server — is called the external Identity Provider, commonly shortened to IdP. Keycloak registers a connection to each such IdP it wants to support, configuring exactly how to redirect users there and how to interpret what comes back.

Why Not Just Connect Every Application Directly to Each External Provider?

It’s worth asking directly why brokering through Keycloak is preferable to simply having each application integrate with Google or a partner’s identity system on its own. Without brokering, every single application would need to separately implement and maintain a working integration with every external provider it wants to support, separately handle that provider’s own quirks and token format, and separately manage the account-linking logic covered in Chapter 5. Brokering centralizes all of that complexity in exactly one place — Keycloak itself — so that adding support for a new external provider benefits every connected application at once, with zero changes required in any of those applications.

The Compounding Value as More Applications Join

This centralizing effect compounds as an organization’s number of connected applications grows. Integrating a single new external IdP once, at the Keycloak level, when an organization already has thirty applications relying on that same Keycloak Realm, instantly extends that new login option to all thirty applications simultaneously — a level of leverage that simply isn’t available to any single application integrating with an external provider entirely on its own.

Brokering Is Not the Same as Federation

It’s worth flagging early, and returning to in depth in Chapter 9, that Identity Brokering is a related but distinct concept from User Federation (connecting Keycloak directly to a corporate directory like LDAP or Active Directory). Both let Keycloak rely on an external source of truth rather than its own local user database, but they work in fundamentally different ways and solve somewhat different problems.

Keycloak’s Role Is Always the Broker, Never the IdP, in This Relationship

It’s worth being precise about which side of the relationship Keycloak occupies here, since the same word “provider” gets used loosely in casual conversation. Throughout this guide, Keycloak itself is the Identity Provider from the perspective of every application connected to it — exactly as established in earlier guides in this series. But from the perspective of the external system being brokered (Google, a partner’s identity platform), Keycloak temporarily switches roles and instead behaves as a relying party, exactly like any ordinary application would behave toward Keycloak. Brokering is, in this sense, Keycloak simultaneously playing both roles at once: Identity Provider to its own applications, and relying party to the external system it’s brokering.

The User Rarely Notices the Handoff Happening

From a purely visual standpoint, a well-configured brokered login often looks completely seamless to the end user — a click on “Sign in with Google,” a brief redirect, and then landing directly inside the target application, all within a couple of seconds. The three-party structure described above is entirely invisible in the everyday experience; it only becomes visible and relevant the moment something goes wrong, or the moment an administrator needs to configure or troubleshoot the relationship.

A Note on Terminology Across the Wider Industry

Different identity systems and standards documents sometimes use slightly different words for the same underlying idea described in this guide — “social login” for the specific case of consumer providers, “federated login” used loosely by some vendors to mean what this series calls brokering, or “external IdP integration” as a more generic catch-all phrase. Whatever term a specific document or vendor uses, the underlying pattern being described is almost always the same three-party relationship covered throughout this guide: a user, an external system that actually verifies them, and an intermediary translating that result into its own standard tokens.

Why SAML Still Matters in Modern Brokering Scenarios

It’s tempting to assume an older standard like SAML has been fully retired in favor of the more modern OpenID Connect, but this isn’t the reality inside many large, established organizations. Government agencies, large financial institutions, and universities frequently still run identity infrastructure built years or decades ago on SAML, and replacing it purely to satisfy a newer partner’s technology preference is often neither practical nor necessary. Keycloak’s ability to broker SAML on one side while issuing clean, modern OIDC tokens to every connected application on the other side means a newer organization can partner with one of these established institutions without either side needing to rebuild its own core identity infrastructure.

Choosing a Protocol When Both Are Available

When an external IdP genuinely supports both protocols, OpenID Connect is generally the more straightforward choice for a new integration — it tends to be simpler to configure, produces more compact tokens, and is the protocol most new identity tooling is built around first. SAML remains the right choice specifically when the external system doesn’t offer an OIDC option at all, or when an existing, already-working SAML relationship simply doesn’t need to be disturbed.

Social Login Providers as a Distinct Sub-Category

It’s worth calling out social login providers specifically, since they’re the brokering scenario most people encounter as ordinary internet users, even without ever hearing the term “Identity Brokering” itself. These providers are almost universally OpenID Connect based, tend to have well-documented, stable integration processes, and typically require the organization brokering them to register as a recognized application with that provider ahead of time — a lightweight registration process, but a genuine prerequisite step distinct from the IdP configuration performed inside Keycloak itself.

The Reconciliation Problem

A user might already have a local Keycloak account (created through direct registration), and separately also have a Google account carrying the exact same email address. When that user first chooses “Sign in with Google,” Keycloak must decide: is this the same person, deserving to be logged into their existing local account, or a genuinely new person who needs a brand-new account created?

Automatic Linking by Email

One common configuration automatically links a newly arriving external identity to an existing local account whenever their email addresses match exactly, on the assumption that possession of an email address is sufficient proof the two identities belong to the same real person. This is convenient and low-friction, but it rests on that specific assumption holding true, a point returned to with more nuance in Chapter 11.

Prompting the User to Confirm or Link Manually

A more cautious configuration, instead of linking automatically, prompts the arriving user with a choice: log into the existing account by re-entering its local password (proving they genuinely control it), or proceed with creating a brand-new, separate account instead. This trades away some convenience for a meaningfully stronger guarantee that linking only happens with the user’s own explicit, verified confirmation.

Creating a Brand-New Account

When no matching local account exists at all, or when linking isn’t configured to happen automatically, Keycloak simply creates a fresh local user record to represent this newly arrived external identity, populated using the IdP Mappers covered in Chapter 7.

Reviewing and Confirming Profile Information Before Account Creation

Some organizations configure the First Broker Login flow to pause even for a genuinely new user, showing them a review screen summarizing the profile information about to be imported from the external IdP — their name, their email — before finalizing account creation. This adds a small extra step but gives the user a chance to correct anything the external IdP reported inaccurately, and gives the organization one last opportunity to apply any additional Required Actions (covered elsewhere in this series) before the account is considered fully onboarded.

What Happens When Reconciliation Is Ambiguous

Occasionally, the available signals don’t cleanly resolve to either “definitely the same person” or “definitely a new person” — for instance, an external IdP might not report an email address at all, leaving nothing to match against. In these ambiguous cases, a well-designed First Broker Login flow generally defaults toward the safer path: treating the arrival as a new account requiring explicit user action to link, rather than guessing at a match and potentially connecting two unrelated identities together by mistake.

How This Works

Keycloak’s user model allows one local account to maintain links to several external identities simultaneously — the same person might link both their Google account and their Microsoft account to a single underlying Keycloak identity, letting them log in through either path interchangeably while always landing in the exact same account, with the exact same Roles, Groups, and history.

Managing Links From the User’s Own Account Settings

Keycloak typically exposes a self-service account management area where a logged-in user can view which external identities are currently linked to their account, add a new link to another provider they haven’t connected yet, or remove an existing link they no longer want active. This puts a meaningful degree of control directly in the user’s own hands, rather than requiring an administrator to manually adjust linkages on their behalf for routine changes.

Unlinking as a Security Response

If a user suspects one of their linked external accounts has been compromised, promptly unlinking it from their Keycloak account through this same self-service area immediately closes that specific login path, without affecting their ability to continue logging in through any other still-linked identity or their local password, if one exists. This makes account linking not just a convenience feature but also a meaningful, user-controllable security lever in its own right.

What an IdP Mapper Does

An IdP Mapper is a configured rule that takes one specific piece of information returned by an external IdP — a claim inside its token, an attribute inside its SAML assertion — and decides what to do with it inside Keycloak: store it as a user attribute, assign a Realm Role based on its value, or populate a specific built-in profile field like first name or email.

Mappers Run on Every Login, Not Just the First

It’s worth being clear that IdP Mappers aren’t a one-time, first-login-only affair. By default, they re-run and can update the local user’s attributes on every subsequent brokered login as well, meaning a change on the external IdP’s side (a new department, an updated name) can automatically propagate into Keycloak’s own copy the next time that user logs in.

Controlling How Aggressively Mappers Overwrite Local Data

Because mappers can run repeatedly, it’s worth thinking through what should happen if a local administrator has manually edited a user’s attribute after it was originally imported — should the next brokered login simply overwrite that manual change with whatever the external IdP currently reports, or should the manually edited value take precedence going forward? Keycloak’s mapper configuration allows this behavior to be tuned per mapper, and getting this choice right for each specific attribute avoids the frustrating experience of an administrator’s deliberate correction being silently reverted on the user’s very next login.

Mapping Group Membership, Not Just Simple Attributes

Beyond simple attributes and Roles, an IdP Mapper can also translate an external IdP’s own group-membership claims into Keycloak Group membership, letting an organization’s existing group structure at the external IdP (departments, teams, cost centers) carry over automatically into Keycloak’s own Group hierarchy, which in turn drives Role assignment through the Group-based patterns covered elsewhere in this series — a genuinely powerful way to keep two separate systems’ organizational structure in sync without manual, duplicate maintenance.

Registration. An administrator registers the external IdP inside the Realm, configuring its protocol, endpoints, and the credentials Keycloak will use to establish trust with it.

Mapper Configuration. IdP Mappers are set up to translate the external identity’s claims into Keycloak’s own user model, as covered in Chapter 7.

Exposure to Users. The external IdP option is surfaced to users, typically through an Identity Provider Redirector execution added to the relevant Authentication Flow.

First Arrivals. As users begin choosing this option, the First Broker Login flow governs each new external identity’s very first appearance, as covered in Chapter 5.

Ongoing Use. Returning users are recognized automatically on each subsequent login, with mappers continuing to refresh local attributes as covered in Chapter 7.

Decommissioning. If a partnership ends or an external IdP is retired, the registration can be disabled or removed, though already-linked local accounts and their history typically remain intact unless explicitly cleaned up.

graph LR
    A["IdP Registered
(protocol, endpoints, trust credentials)"] --> B["Mappers Configured"]
    B --> C["Exposed to Users
(via Identity Provider Redirector)"]
    C --> D["First Arrivals
(First Broker Login flow)"]
    D --> E["Ongoing Recognized Logins"]
    E --> F{"Partnership Ends?"}
    F -->|"Yes"| G["IdP Disabled or Removed"]
    

Treating Each Relationship as Its Own Small Project

Because each external IdP registration carries its own configuration, its own trust assumptions, and its own ongoing monitoring needs, larger organizations with several brokered relationships often benefit from tracking each one as its own small, named piece of ongoing operational ownership — with a clear answer to “who is responsible for noticing if this one breaks, and who has the authority to update its configuration” — rather than treating the entire collection of external IdPs as one undifferentiated, jointly owned configuration block that nobody feels fully responsible for in practice.

Planning for Eventual Migration Away From a Brokered Relationship

Just as an organization plans for onboarding a new brokered relationship, it’s worth planning upfront for what eventually unwinding one would involve — specifically, what happens to users whose only linked identity was through that one external IdP, once it’s disabled. A responsible decommissioning plan typically includes advance user communication and, where appropriate, prompting affected users to set a local password or link an alternative identity before the external relationship is actually switched off, so nobody is abruptly locked out of their own account with no path back in.

When an Organization Might Genuinely Need Both at Once

These two mechanisms aren’t mutually exclusive within a single Realm. A company might federate its own employees against its internal Active Directory (so staff log in with their familiar corporate username and password, without leaving Keycloak’s own page) while simultaneously brokering a completely separate population of external partner users through those partners’ own identity systems, and a third population of consumer customers through social login providers — all coexisting inside the very same Keycloak Realm, each population served by whichever mechanism actually fits how that population’s identity is really managed.

Federation’s Trust Model Is Simpler, but Less Flexible

Because federation involves Keycloak directly checking credentials against the external directory rather than trusting a separate system’s own assertion of success, its trust model is, in one sense, simpler to reason about — there’s no third party’s own token-issuing behavior to account for. But this comes at the cost of flexibility: federation generally assumes a fairly uniform, tightly integrated relationship with one specific directory technology, whereas brokering’s redirect-based approach comfortably accommodates a much wider and more loosely coupled variety of external identity systems, including ones an organization has no direct technical relationship with beyond the standard protocol itself.

None of these trade-offs argue against using brokering — they simply argue for treating each brokered relationship as a genuine, ongoing operational commitment, not a one-time configuration task completed once and never revisited.

Trusting the External IdP’s Own Security Practices

Brokering inherently extends a degree of trust to however securely the external IdP itself protects its own users’ accounts. An organization brokering logins through a partner’s identity system is, in effect, also relying on that partner’s own password policies, breach response practices, and account-recovery processes — a dependency worth factoring into any risk assessment, especially for high-sensitivity applications.

Reviewing Which Claims Are Actually Trusted

Because IdP Mappers can translate external claims directly into Keycloak Roles (as shown in Chapter 7’s partner-directory example), it’s worth reviewing exactly which claims are trusted this way and confirming the external IdP itself properly restricts who can set or influence those specific claim values — an externally controllable claim mistakenly mapped into a sensitive Role assignment can become an unintended privilege-escalation path.

Signature and Endpoint Verification

Just as with the token verification principles covered elsewhere in this series, Keycloak must properly verify the cryptographic signature on whatever proof of identity an external IdP returns, and must be configured with the correct, trusted endpoint addresses for that IdP rather than accepting values supplied at request time. A misconfiguration allowing an untrusted signing key or an unverified endpoint to be accepted would undermine the entire basis of trust the brokering relationship depends on, regardless of how carefully every other setting was configured.

Revoking Trust When a Relationship Ends

When a business relationship with an external IdP ends — a partnership dissolves, a social provider’s terms change unacceptably — promptly disabling or removing that IdP’s registration is a genuine security action, not merely administrative housekeeping. A stale, still-active brokering relationship with an organization no longer subject to any ongoing due diligence or monitoring represents an open trust boundary that no longer serves any legitimate business purpose.

Watching for Silent Protocol or Certificate Changes

External IdPs occasionally rotate their own signing certificates, change their endpoint addresses, or make other protocol-level adjustments on their own schedule, sometimes with limited advance notice to every relying party depending on them. Monitoring specifically for a sudden rise in signature-verification failures for one particular brokered IdP, distinct from a general outage, often reveals exactly this kind of change happening on the external side, well before it would otherwise surface only through a wave of confused user support tickets.

Tracking Linked-Identity Growth Over Time

For organizations actively encouraging account linking (as in the flexible multi-provider pattern from Chapter 6), tracking how many accounts have zero, one, or multiple linked external identities over time offers a useful, simple gauge of how well that feature is actually being adopted, and whether further in-product prompts or education might help more users take advantage of it.

Good Patterns

• Verify before linking: only enable automatic account linking when the external IdP explicitly guarantees the claim being matched on is verified
• Map narrowly and deliberately: only translate external claims into Keycloak Roles when the external IdP’s own governance over those claims is well understood and trusted
• Monitor the brokered path separately: treat brokered login reliability as its own dedicated metric, not folded invisibly into overall login statistics
• Document each external relationship’s purpose and trust basis alongside its configuration, for the same reasons documentation matters for Conditional Flows elsewhere in this series

Anti-patterns to Avoid