Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Identity Brokering and Social Login

Identity Brokering Explained

Learn how Keycloak brokers logins to external identity providers, what first login does, how accounts are linked, and which flows and settings control it.

So far, users have proven who they are with a password stored in your realm. Identity brokering lets Keycloak delegate that proof to another system: Google, GitHub, a corporate Microsoft Entra ID tenant, or any other OpenID Connect or SAML provider. Your applications still talk only to Keycloak. They never learn that the user signed in somewhere else.

This is the big idea of brokering: Keycloak sits in the middle as an identity broker. To the application, Keycloak is the identity provider. To the external provider, Keycloak is a client (or a SAML service provider). The user gets one login experience and your apps get one token format, no matter how many outside providers you plug in.

The product itself cannot run on this site. Menu paths below describe the admin console of recent Keycloak versions (26.x). The code blocks are small, clearly labelled stand-ins written in JavaScript that model the same decisions, so you can experiment with the logic.

Broker, identity provider, and federated identity

A few terms keep coming back in this chapter:

  • Identity provider (IdP): in the admin console, an entry under Identity providers that points at an external system. Each has an alias, such as google or acme-entra. The alias becomes part of URLs.
  • Federated identity link: a row that connects a local Keycloak user to an account at an IdP. It stores the IdP alias, the external user ID (the sub claim for OIDC), and the external username.
  • Brokered login: a login where the user clicked a provider button, or was redirected there automatically, instead of typing a local password.

Under the hood, a brokered OIDC login is simply the Authorization Code flow you saw earlier, run twice. Your app starts a code flow with Keycloak. Keycloak starts a second code flow with the external provider. When the provider returns, Keycloak turns the result into a local session and finishes the first flow.

sequenceDiagram
    participant U as Browser
    participant A as Your app
    participant K as Keycloak (broker)
    participant G as External IdP
    U->>A: Open app
    A->>K: Redirect to /auth (client_id=app)
    K->>U: Login page with IdP buttons
    U->>K: Click "Google"
    K->>G: Redirect to IdP authorization endpoint
    G->>U: User signs in at the provider
    G->>K: Redirect to /broker/google/endpoint?code=...
    K->>G: Exchange code for tokens (back channel)
    K->>K: Find or create local user, run flows and mappers
    K->>A: Redirect back with Keycloak code

Two code flows chained: the app only ever sees Keycloak.

The redirect URI you register at the external provider is always the broker endpoint of the realm: https://auth.example.com/realms/<realm>/broker/<alias>/endpoint. Getting that exact string right is the most common setup stumble.

What happens on the first login

When someone arrives from an IdP for the first time, Keycloak has no federated identity link for them. It runs the First login flow (the realm default is called first broker login). The default steps are roughly:

  1. Try to review profile, letting the user confirm or fill missing attributes.
  2. Check whether a local user already exists with the same email or username.
  3. If one does, ask the user to link the accounts: the user must prove they own the existing account, for example by verifying the email or typing the local password.
  4. If none exists, create a new local user and a federated identity link.

On every later login the link is found immediately and the flow is skipped. An optional Post login flow runs after every brokered login, for example to require a second factor.

Linking by matching email sounds convenient, and it is also dangerous. If an attacker creates an account at a weak provider using a victim's email address, a careless "link automatically" setting would hand the attacker the victim's local account. That is why the default flow forces a verification step and why the Trust email switch on an IdP should be turned on only for providers that verify addresses.

Try the decision logic yourself with this stand-in:

JS Stand-in: first broker login decision

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Important IdP settings

Whatever the provider type, several settings sit on the same Settings tab and shape behaviour:

  • Enabled and Hide on login page: hide the button but still allow redirects that name the provider.
  • Trust Email: treat the provider's email as verified. Use it only for providers you control.
  • Account linking only: the provider can link to existing accounts but cannot create users.
  • Sync mode: how imported attributes behave on later logins. import copies values once, legacy is the old default, and force overwrites local values at every login so the provider stays the source of truth.
  • First login flow override and Post login flow: replace the realm defaults for this provider only.
  • Store tokens: keep the provider's access and refresh tokens so your apps can fetch them later (the broker token endpoint). Leave it off unless you need to call the provider's API.

Skipping the login page

You can send users straight to a provider without showing the Keycloak login form. Your app adds the hint kc_idp_hint=google to its authorization request, and Keycloak redirects immediately. A realm can also set an Identity Provider Redirector execution in the browser flow with a default provider. Hints are handy for enterprise customers whose staff always sign in with the corporate IdP.

Here is the same idea as a tiny helper that builds the request:

JS Stand-in: building an authorization URL with a provider hint

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Registering the wrong redirect URI at the provider, usually by forgetting /realms/<realm> or using http behind a proxy that Keycloak does not know about.
  • Turning on Trust Email for a provider that does not verify addresses.
  • Changing the IdP alias later: it is part of every registered redirect URI and of stored links.
  • Expecting a provider's logout to log the user out of Keycloak. Sessions are separate unless you configure backchannel logout.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a brokered login, what role does Keycloak play toward the external provider?

    Keycloak redirects the user to the external provider as a relying party, while to your own applications it acts as the identity provider.
  2. 2. Which URL pattern is the broker endpoint you register at an external OIDC provider?

    The broker endpoint contains the realm name and the provider alias; the provider returns the user there.
  3. 3. Why is automatic linking by email address risky?

    Unless the provider verifies emails, matching on email lets someone else claim your account, so Keycloak asks the user to verify the existing account.
  4. 4. What does the kc_idp_hint parameter do?

    The hint carries a provider alias so Keycloak can redirect straight to it.

Summary

  • Keycloak is an identity broker: apps talk to it, it talks to external providers.
  • A brokered login is two chained Authorization Code flows.
  • The first login flow finds or creates a local user and records a federated identity link.
  • Trust Email, Sync mode, and flow overrides control how safe and how consistent the link is.
  • kc_idp_hint jumps straight to a provider.

Next: Social Login with Google and GitHub