Keycloak Identity Brokering Explained

Identity brokering lets Keycloak trust a login that already happened at another identity provider. Your applications still use Keycloak as their identity provider; Keycloak redirects the browser to Entra ID, Okta, Google, or another Keycloak realm, then turns the upstream result into a Keycloak session and application tokens.

This page is the architecture map for that pattern. Provider-specific registration, mapper tuning, and first-broker-login customization live in the dedicated brokering lessons that follow it in the Keycloak tutorial syllabus.

Quick answer

1. Add an Identity provider under Identity providers in the realm (not under User federation).
2. Give it an alias — that alias appears in broker URLs and on the login page button.
3. Configure OIDC, SAML, OAuth 2.0, or a built-in social template toward the upstream IdP.
4. User chooses Sign in with … on the login page (or Keycloak redirects with a default IdP or kc_idp_hint).
5. Browser authenticates at the upstream IdP, then returns to Keycloak at /realms/<realm>/broker/<alias>/endpoint.
6. Keycloak validates the response, runs First broker login when needed, links or creates a local user, and finishes the application login with Keycloak-issued tokens.

What identity brokering means in Keycloak

Keycloak documentation calls the feature identity brokering. In the Admin Console the menu is Identity providers. Each entry is an upstream identity provider (IdP). Keycloak acts as a broker: it sits between your applications and that upstream IdP.

Toward the application, Keycloak is still the identity provider. Toward Entra ID or a SAML company IdP, Keycloak is the client: an OIDC relying party or a SAML service provider. OAuth vs OIDC vs SAML describes those protocol hops in more detail.

┌─────────────┐   OIDC/SAML    ┌─────────────────────┐   OIDC/SAML    ┌──────────────┐
│ Application │ ◄────────────► │ Keycloak realm      │ ◄────────────► │ Upstream IdP │
│             │   (app protocol)│ (broker)            │  (broker proto)│ Entra, Okta… │
└─────────────┘                └─────────────────────┘                └──────────────┘
         ▲                                  ▲
         │         browser redirects        │
         └──────────────────────────────────┘

The application never receives the upstream IdP’s raw protocol response as its primary session mechanism. It receives whatever your client is configured for against Keycloak (authorization code, tokens, or SAML assertion from Keycloak).

Identity brokering is not user federation

Keycloak uses two different integration models. Mixing the labels causes broken designs — for example registering Active Directory twice (LDAP federation plus a duplicate “AD broker”) when you only need directory passwords on the Keycloak login form.

Keycloak user federation vs identity brokering compares login flows side by side. Use that article when you are choosing between directory federation and an external IdP button.

Active Directory LDAP and Kerberos stay on the federation path

Corporate AD scenarios split cleanly:

• LDAP bind on the Keycloak login page — user federation (lab-ad style). See Integrate Keycloak with Active Directory.
• Kerberos / SPNEGO with tickets from the AD KDC — still user federation when users come from the LDAP provider with Allow Kerberos authentication enabled. See Keycloak Kerberos with Active Directory. That guide does not add an Identity provider entry for AD.
• “Sign in with Microsoft” using Entra as an OIDC or SAML IdP — identity brokering. Users leave Keycloak’s form and authenticate at Microsoft; that is a separate lesson track (Entra OIDC and Entra SAML when published).

Kerberos tickets and LDAP passwords are validated between Keycloak and the directory. Brokering sends the browser to another product’s login UI. You can use both in one realm for different user populations, but they are different configuration trees.

Identity providers in the Admin Console

Each brokered upstream system is one row under Identity providers:

• Alias — short name used in URLs and kc_idp_hint. Example: company-idp.
• Provider type — OpenID Connect v1.0, SAML v2.0, OAuth 2.0, or a social template (Google, GitHub, …).
• Enabled — disabled providers do not appear on the login page.
• Store tokens / Stored tokens readable — optional retention of upstream tokens for later API calls (advanced; see retrieve-token guides later in the syllabus).

Mappers for brokering live on the identity provider entry (claim → user attribute, group import, hardcoded role, etc.). They are not LDAP mappers on User federation. Outbound client scopes and protocol mappers still shape what applications receive from Keycloak after the broker step completes.

Broker alias and callback endpoints

The alias is part of the public broker endpoint path. For realm apps and alias company-idp, SAML and OIDC brokers commonly use:

https://<keycloak-host>/realms/apps/broker/company-idp/endpoint

That URL is where the upstream IdP redirects the browser after authentication (SAML ACS or OIDC redirect URI registered at the upstream IdP must match). Internal login initiation uses the same alias in paths such as:

/realms/apps/broker/company-idp/login

The Keycloak SAML SSO tutorial exercises this layout with two Keycloak realms: company issues assertions; apps hosts the SAML identity provider and broker endpoint. Reading that lab after this page makes the abstract paths concrete.

Browser login flow (brokered)

A typical brokered login looks like this:

           Application
                 │
                 │ redirect to Keycloak
                 v
           Keycloak login
                 │
                 │ user picks IdP (or default / hint)
                 v
           Upstream IdP login
                 │
                 │ MFA / password / SSO
                 v
           Redirect to broker endpoint
                 │
                 v
           Keycloak validates response
                 │
                 │ First broker login if new
                 v
           Redirect to application
                 │
                 v
           App session (Keycloak tokens)

Keycloak never sees the user’s password at the upstream IdP. It only sees the signed OIDC result or SAML assertion the upstream IdP issues. Validation failures surface as broker errors in the Admin Console event log or on the error page — not as LDAP bind failures.

First broker login and federated identities

The first time a user arrives from a given upstream IdP, Keycloak may not yet have a local user linked to that external identity. The realm’s First broker login authentication flow controls:

• whether to create a new Keycloak user automatically;
• whether to ask the user to confirm profile fields (common when only NameID arrived from SAML);
• whether to link to an existing account with the same email.

After linking, Keycloak stores a federated identity record on the user (provider alias + upstream subject identifier). Later logins skip account creation and reuse that link. Sync mode on the identity provider decides whether upstream attributes refresh the local user on each login — covered in the dedicated sync-mode lesson.

Protocol choices for the upstream hop

Pick the protocol the upstream IdP supports and that your security team approves. OIDC is the default for cloud IdPs; SAML remains common in enterprise federations. Keycloak-to-Keycloak SSO can use either OIDC or SAML — Keycloak SAML SSO demonstrates SAML; Keycloak-to-Keycloak OIDC covers the OIDC variant when published.

Login page behavior and hints

Without extra configuration, Keycloak shows one button per enabled identity provider on the realm login page. Options you will see in later articles include:

• Default identity provider — skip the chooser and redirect immediately.
• kc_idp_hint query parameter — send users straight to one alias (deep links from applications).
• Hide on login page — use broker only through hints or custom flows.

Those settings do not change the broker endpoint shape; they only change how the browser reaches the redirect.

What brokering does not replace

Identity brokering solves authentication trust with an external IdP. It does not by itself:

• import every LDAP group from Active Directory (use user federation or group claims from the IdP);
• provision users into Keycloak from Entra SCIM (that is Entra SCIM to Keycloak, with Entra as SCIM client);
• validate Kerberos service tickets (that stays on the LDAP/Kerberos federation path in Keycloak Kerberos with Active Directory).

Plan brokering when users should authenticate at a product that already runs OIDC or SAML for employees or customers. Plan federation when Keycloak must check passwords or tickets against LDAP or AD directly.

Where to go next in the brokering track

Summary

Identity brokering in Keycloak means configuring Identity providers so Keycloak redirects the browser to an upstream IdP, accepts the OIDC or SAML result at /realms/<realm>/broker/<alias>/endpoint, and completes login for applications with Keycloak’s own session and tokens. It is separate from User federation, where Keycloak talks to LDAP or Active Directory (including Kerberos on an LDAP provider) without that redirect chain.

Use this article as the map: three-party roles, alias and endpoint URLs, first broker login, and protocol choices. Use Keycloak Kerberos with Active Directory and Integrate Keycloak with Active Directory for directory-backed login; use the brokering track lessons for Entra, Okta, Google, and SAML/OIDC broker registration.

References

• Keycloak Server Administration Guide — Identity broker
• Keycloak Server Administration Guide — Identity provider mappers
• Keycloak Server Administration Guide — First login flow