Before opening the Keycloak admin console, let’s fix the plain-English idea in place.

Identity brokering is the general practice of one identity system trusting and forwarding authentication decisions made by another identity system, rather than authenticating users itself every single time. In Keycloak, this is configured through something called an Identity Provider, often shortened to IdP. Each Identity Provider configuration tells Keycloak about one external system it should trust — Google, a corporate Microsoft Entra ID tenant, GitHub, or even another, entirely separate Keycloak realm.

Once configured, Keycloak can present a “Login with X” button on its own login page. When a user clicks it, Keycloak steps out of the way, lets the external provider handle the actual authentication, and then takes the resulting proof of identity and turns it into a normal Keycloak session — complete with its own access tokens, roles, and user record, exactly as if the user had logged in with a local Keycloak username and password.

Understanding the problem it solves makes the feature much easier to reason about.

Without brokering, every application that wants to accept “Login with Google” or “Login with a partner company’s directory” would need to implement that specific provider’s protocol itself, store its own copy of that integration’s secrets, and maintain it independently. Multiply that by every application in an organization, and the same integration work gets duplicated many times over, each with its own chance of a subtle mistake.

By configuring the Identity Provider once, centrally, inside Keycloak, every application that already trusts Keycloak automatically gains the ability to log in through that external provider too — without any of those applications needing to know Google, or SAML, or any other protocol exists at all. From the application’s point of view, a user who logged in via a brokered identity looks exactly like any other Keycloak-authenticated user.

Keycloak actually offers three distinct ways to bring users in, and it’s easy to mix them up.

The distinction that matters most: with brokering, Keycloak never sees the user’s actual password at all. It only ever receives a signed assertion or token from the external provider confirming that authentication already happened successfully elsewhere.

A handful of pieces work together every time a brokered login happens.

flowchart LR
    U["User"] -->|clicks Login with Provider| K["Keycloak"]
    K -->|redirects to| IdP["External Identity Provider"]
    IdP -->|authenticates user| IdP
    IdP -->|returns token / assertion| K
    K -->|checks| L[("Federated Identity Link")]
    L -->|found| S["Existing local user logged in"]
    L -->|not found| F["First Broker Login Flow
(create or link account)"]
        

Keycloak doesn’t just support one flavor of “external login” — it supports several standard protocols under one roof.

Regardless of which protocol a given Identity Provider configuration uses, Keycloak normalizes the result into the same internal shape once login completes — which is exactly what allows every downstream application to stay protocol-agnostic.

Setting one up in the admin console follows a predictable shape, regardless of protocol.

Here’s what actually happens on the wire when a user clicks a brokered login button.

sequenceDiagram
    participant U as User Browser
    participant K as Keycloak
    participant IdP as External Identity Provider

    U->>K: Clicks "Login with Provider"
    K->>IdP: Redirect to provider's login page
    U->>IdP: Enters credentials, authenticates
    IdP-->>K: Redirect back with authorization code / assertion
    K->>IdP: Exchange code for identity token (if OIDC)
    IdP-->>K: Identity token / attributes
    K->>K: Look up Federated Identity Link
    alt Link exists
        K-->>U: Local session issued immediately
    else No link yet
        K-->>U: First Broker Login flow (review, link, or create account)
    end
        

The very first login from a given external identity is the trickiest moment in the whole flow, and Keycloak handles it with a dedicated flow.

The First Broker Login flow only runs the first time Keycloak sees a particular external identity for a particular Identity Provider configuration. Depending on how that flow is configured, a few outcomes are possible: Keycloak can automatically create a brand-new local user based on the external identity’s attributes; it can prompt the user to review and confirm their profile details before creating the account; or, if a local account already exists with a matching email or username, it can offer to link the external identity to that existing account instead of creating a duplicate.

External providers rarely describe a user in exactly the shape Keycloak expects — mappers bridge that gap.

An Identity Provider Mapper is a small, configurable rule that takes a specific piece of information coming back from the external provider — a claim in an OIDC token, or an attribute in a SAML assertion — and decides what to do with it inside Keycloak. Common mapper types copy an external claim into a Keycloak user attribute, assign a Keycloak role based on a claim’s value, or add the user to a specific group automatically.

Mappers typically run both during the first login (to populate a brand-new account) and on subsequent logins (to keep the local record synchronized with any changes on the external provider’s side).

Tracing what happens across a user’s entire relationship with a brokered login, not just a single request.

After the first login establishes the federated identity link, every future login through that same Identity Provider is far simpler: Keycloak recognizes the returning external identity, finds the linked local user, applies any configured mappers to refresh attributes, and issues a normal session — without repeating the account-creation decision each time.

Brokering means placing real trust in a system Keycloak doesn’t control — that trust needs to be deliberate.

Brokering is a powerful convenience, but it does shift where trust and dependency live.

A few recurring habits distinguish smooth brokering setups from painful ones.

A short, practical checklist for teams setting up their first Identity Provider in Keycloak.

Identity brokering shows up anywhere an organization wants to reuse an identity that already exists somewhere else.

Because brokered logins span two systems, good visibility matters even more than for purely local authentication.

No. With brokering, Keycloak never sees the user’s raw password at the external provider at all — it only receives a signed token or assertion confirming that authentication already succeeded.

Yes. A single Keycloak user can have multiple federated identity links, one per configured Identity Provider, letting them log in through any of several external systems.

A client represents an application that trusts Keycloak to log its users in. An Identity Provider represents an external system that Keycloak itself trusts to authenticate users. They serve opposite directions of trust.

Yes. Keycloak can require additional authentication steps, such as an OTP, on top of a brokered login, either always or only in specific configured circumstances.

Users attempting to log in through that specific Identity Provider will be unable to authenticate until it’s reachable again; this doesn’t affect local accounts or other configured providers.

Yes, through the Admin REST API or admin console. Doing so means the next login from that provider will be treated as new and will re-trigger the First Broker Login flow.

An Identity Provider configuration is how Keycloak extends trust outward, letting an external system perform authentication while Keycloak translates the result into a normal local session. Built on standard protocols like OIDC and SAML, and governed by mappers and a dedicated First Broker Login flow, this feature turns “Login with X” buttons from a one-off integration problem into a centrally managed, reusable capability. Used carefully — with verified claims, deliberate linking rules, and properly protected secrets — identity brokering lets organizations reuse identities that already exist, rather than asking users to create yet another password.