Keycloak identity brokering: external identity providers

How Keycloak identity brokering lets users sign in through an existing identity provider

Most users already have an account at a corporate identity provider or a social login, and they expect that account to work for every application behind Keycloak. Identity brokering makes this possible. Keycloak acts as the broker: it redirects the user to the external provider, the external provider authenticates the user, and Keycloak then issues its own tokens to the application. The application trusts Keycloak alone and does not receive the external provider's tokens, so the token contract your applications depend on stays under your control. Before you configure anything, decide which applications should accept external sign-in and which must remain on local credentials, because that choice shapes every provider setting that follows.

The administration guide documents brokering with OpenID Connect, OAuth 2.0 and SAML 2.0 providers, plus social providers including Google, GitHub, GitLab, Microsoft, Facebook, LinkedIn, PayPal and Twitter. For a corporate directory, an OpenID Connect or SAML provider run by the company is the usual choice, while social providers suit customer-facing applications. The provider types differ in the metadata, signing keys and options they expose, so confirm with the guide and with the provider's administrators which protocol version, endpoints and certificates you will use. Ask the directory team who owns the provider configuration, how certificates are rotated, and whether a test tenant exists before production configuration begins.

Enabling a provider button is the easy part. The harder work starts at the first sign-in. When a user arrives from an external provider, Keycloak has no matching local user, so the first broker login flow decides whether to create a new account, show the user a profile review, or require further verification. Account linking is the next decision: if a local user already has the same email address, the flow must choose whether to link the external identity to that account. Linking on an email address the external provider has not verified can let someone take over another person's account. Attribute mapping adds a third problem. Claims from the external provider must map to Keycloak user attributes and roles, and a renamed or missing claim produces users with wrong or empty roles, which often surfaces only after go-live.

Turn these decisions into a short checklist before build. Inventory which users already exist locally and which will arrive only through the external provider. Confirm whether each provider asserts that email addresses are verified, and decide whether Keycloak should trust that assertion for each provider. Write a test matrix that covers a first login, a returning login, a login that links to an existing local account, and a login where a mapped claim is absent. The Keycloak 26.8 upgrade notes also make signature validation of backchannel logout tokens from external providers mandatory, so confirm that each provider can send signed logout tokens before you plan single logout across applications.

Which Keycloak settings and extension points carry brokering

Brokering behavior is decided by a small set of connected settings: the identity provider definition, the flows that run on first and later sign-ins, the mappers that copy claims into users, and the realm rules that permit linking or creation. Reviewing these together, before any external provider is connected, prevents most account takeover and duplicate account problems.

Identity provider configuration for each protocol

Each external provider is defined in the realm with its protocol settings: OIDC needs the issuer, client credentials and scopes, SAML needs the entity descriptor, signing certificate and name ID format, and social providers need their app registration and requested scopes. Check which claims or assertions carry the user's email and whether the provider marks that email as verified. These fields decide what Keycloak can trust when matching a brokered user to an existing account.

First broker login flow

The first broker login flow runs the first time a user arrives through an external provider and no linked local account exists yet. Its review, create user and link steps determine whether Keycloak asks the user to confirm an existing account, automatically links on a matching email, or creates a new user. Review each execution in the flow, because an automatic link on an unverified email is the most common route to unintended account access.

Post login flows

Post login flows run after the broker has established the session, for example to require a second factor, check a condition or accept terms. They apply to every brokered sign-in, not only the first one, so a step that prompts the user again will repeat on each login. Confirm which conditions gate each step and test the flow with users who already have a local account.

Identity provider mappers for attributes and roles

Mappers copy claims, assertion attributes or group memberships from the external provider into user attributes, groups or realm and client roles. They run on every brokered login, so a mapper that grants a role will also revoke or fail to revoke it depending on its sync mode. Document each mapper with its source claim, target attribute and sync behavior, and check how group names from the provider line up with roles in your realms.

Realm settings that permit linking or creating users

Realm-level choices decide whether a brokered identity may be linked to an existing user or create a new one, including whether the email must be trusted, whether a user can have several linked identities, and whether registration is permitted. These settings interact with the first broker login flow, so changing one without the other can silently open or close a path. Record the intended behavior for each provider and test both the new-user and existing-user cases.

Per-organization identity providers

The Organizations feature lets an organization inside a realm carry its own identity provider, so members of a business customer sign in through that customer's directory. This is an option on each organization, not a separate brokering model, and it still depends on the realm flows and mappers described above. Multi-tenant design, domain ownership and when separate realms are the better choice are covered in the sibling topic on Keycloak Organizations.

Which brokering design fits your users and applications

This table compares the main brokering choices for Keycloak, from realm structure to first-login behavior, account linking and provider type. Read each row for when the option fits and what it costs your support and security teams to run. The main takeaway is that account linking and email trust decisions drive most of the long-term operating load.

Design decision	When it fits	Operational cost to plan for
One shared realm with several brokered providers	Applications and users share one login experience, and you want one set of clients, roles and sign-in flows to maintain.	Every provider's users land in the same user store, so provider-specific claims, mappers and first-login rules must be kept separate and tested per provider.
Separate realms per tenant	Tenants need strict isolation of users, signing keys, branding and admin rights, or each tenant manages its own identity configuration.	More realms mean more clients, flows and upgrade checks to repeat, and cross-tenant reporting or shared policy changes take more coordination.
Auto-create users on first login	Partners or customers sign in with their own corporate accounts and you do not want an administrator to pre-register each person.	Accounts appear without review, so you need mappers that set roles conservatively and a plan for removing users who leave the provider.
Pre-provision users before first login	Access must be approved in advance, for example for regulated roles or small known groups of external staff.	Someone maintains the user list, and users who sign in before being created or with a different identifier are blocked and generate support tickets.
Link to existing local accounts by verified email	The same person already has a local account and the provider asserts that the email address is verified.	Accepting email from a provider you do not control can let one person take over another account, so trust only providers whose email verification you have reviewed.
Link only after the user confirms	Local accounts hold sensitive access, or the provider's email verification is unknown or weak.	Users see an extra step and some abandon sign-in, and duplicate accounts still appear when people do not recognize the prompt.
Social providers such as Google, GitHub or Microsoft	Users are external or consumer-facing and you accept the provider's sign-in without a contractual relationship.	Login policies, MFA and account recovery are controlled by the social provider, so your support team must handle lockouts you cannot fix directly.
Enterprise OIDC or SAML providers	Your customers or partners have corporate identity providers that they manage, and you need their group and attribute claims.	Each provider needs certificate or metadata rotation, claim mapping and testing, and you depend on their administrators for changes.

How to build a brokered sign-in step by step

Brokering is built in a fixed order, starting with the trust between the external provider and Keycloak, then adding the identity provider, trust settings, login flow and mappers on top of it. Each step closes with a check, so a failure points to one configuration change instead of the whole chain.

Register Keycloak as a client at the external provider
An administrator at the external provider, or your team with admin rights there, creates an OIDC application or a SAML service entry for the Keycloak realm. The redirect URI must match the broker endpoint Keycloak generates from the realm name and the identity provider alias, so decide the alias now. Store the client ID and secret in your secrets manager before moving on. The step is done when the provider's application settings show the exact redirect URI and a test sign-in reaches the provider's login page without a redirect error.
Create the identity provider in the target realm
In the target realm's admin console, add the provider under identity providers and choose the protocol type or the social provider. Enter the discovery document address or SAML metadata from the external provider, the client ID and secret, and a stable alias. The alias is part of the redirect URI, so changing it later means updating the client registered in the first step. The step is done when the provider appears as a sign-in option on the realm's login page and the imported endpoints show no validation errors.
Set trust and sync options
Decide whether Keycloak trusts the provider's email verification claim, and enable that trust only if the provider verifies addresses for its users. Without it, a user who has not proven ownership of an email address could be matched to an existing local account. Set the token storage, sync mode and any default scopes the provider requires. Your security owner should approve these choices in writing. The step is done when the settings are exported or recorded in your change log and a reviewer has signed off on the trust decision.
Define the first login flow and its review or link steps
Review the first broker login flow in the authentication section and confirm which steps run for a user who signs in through this provider for the first time. The default flow includes profile review and steps that create a new user or handle an existing account with the same email, and you can add a step that requires the user to confirm a password before linking. Confirm the step names in your Keycloak version. The step is done when a new account creates exactly one user record, and an existing email prompts for linking instead of merging silently.
Add attribute and role mappers
Add identity provider mappers that copy claims such as email, given name and a department or group claim into user attributes, and map group or role claims to realm or client roles. Keep the mapping list short and document which provider claim feeds which Keycloak field, since mappers run on every sign-in. The step is done when a test sign-in produces a user with the expected attributes, and the decoded access token from Keycloak contains the mapped role only for users who should have it.
Test each provider with a live account
Test every provider with accounts that actually exist there. Cover a first-time user, a returning user, a user whose email matches an existing local account, a user with an unverified email, and a user removed from the mapped group at the provider. Record the expected and actual result for each case. The step is done when every case matches the documented outcome, the unverified email is denied without creating or linking an account, and the login events in the admin console match your test log.

What drives the effort of brokering with several providers

This table lists the factors that change how much design, build and testing work brokering needs, and how to keep each one manageable. Read each row as a lever: the number of providers and mapping rules compound, so reducing them early saves the most later.

Driver	Why it changes effort	How to keep it down
Number of identity providers	Each provider adds its own metadata, client registration, certificate or secret rotation, test cases and support contact.	Agree the provider list up front, and avoid creating a separate identity provider per application when one shared provider serves several clients.
Protocol mix (OIDC, SAML or social)	OIDC and SAML providers need different endpoint, signing and encryption settings, and social providers each have their own app registration and scope rules.	Prefer one protocol per partner where possible and document the settings for each protocol in a single runbook.
Quality of claims from the provider	Missing, renamed or unverified email, name or group claims force custom mappers, fallback logic and manual fixes.	Ask each provider which claims it sends, confirm them in a test realm, and standardize on one agreed claim set that Keycloak maps to its own user model.
Existing duplicate accounts	Users who already have local accounts with the same email must be linked or reconciled, which needs rules for trust, verification and conflict handling.	Count duplicates in the current directory before design, decide whether to link automatically or only after verification, and clean up records before cutover.
Attribute and role mappings	Every mapped attribute, group or role adds configuration, documentation and regression tests, and each change to a provider can break a mapping.	Limit mappings to what applications actually use, keep one mapping pattern across providers, and review the mapper list whenever a provider changes.
Custom first login logic	Custom authentication steps for first sign-in, such as additional prompts or account review, are extensions that must be maintained through Keycloak upgrades.	Use the built-in first broker login flow where it meets the need, and limit custom steps to documented requirements that a test suite covers.
Environments needing separate registrations	Each development, test and production environment usually needs its own redirect URIs, client credentials and provider settings, which multiplies setup and secret handling.	Template the provider configuration per environment, store secrets in the client's secret manager, and confirm with each provider how many registrations it allows.

How brokering changes in single node, clustered and Kubernetes deployments

On a single node, Keycloak runs as one server behind one reverse proxy, and every brokered sign-in returns to one public frontend hostname. The redirect address is easy to trace because there is only one place where it is served. Development setups often use the built-in dev-file database, which is for development only, so this model assumes a supported production database is configured before any external provider is registered.

Confirm the public frontend hostname that the browser sees after the reverse proxy, and register that exact callback URL at each external provider.
Register a separate test application at each provider for this environment, even when it is only a proof of concept, so test and production redirect lists stay apart.
Keep provider client secrets out of exported realm files and confirm how the chosen secret store is read at startup.
Test first login flows with a non-administrative account, because a single node has no second site to fall back on if the broker configuration breaks.
Check that the admin console hostname is separate from the public frontend hostname, as the production guide recommends.

Before go-live, compare the callback URL in the browser redirect, the proxy headers and the provider's registered redirect list, and confirm all three match.

How to keep brokered sign-ins from becoming an account takeover path

When Keycloak accepts sign-ins from an external identity provider, it trusts that provider's assertions about who the user is. The controls below decide how far that trust extends, and a weak link in any one of them can let an outside party take over a local account. Review them for each provider you broker, and see the sibling security hardening topic for the wider server setup.

Decide when email claims can link accounts

Automatic linking matches an incoming external identity to an existing local user, often by email address. Keycloak's first broker login flow decides whether that match happens without user confirmation. Before enabling automatic linking, confirm that the external provider verifies email ownership, and that the claim Keycloak reads is the one the provider marks as verified. Where verification is not guaranteed, require the user to confirm the link with their existing local credentials.

Restrict accepted tenants and domains

A multi-tenant provider such as Microsoft Entra ID can issue tokens to users from any tenant unless the broker restricts the issuer. Configure the provider so Keycloak accepts only the tenant or tenants you own, and check that the issuer in each token matches that allow list. For domain-based routing, confirm that only verified domains of your organization can be used to reach a given identity provider, so a user in another tenant cannot claim one of your addresses.

Protect client secrets and signing keys

Each brokered provider has a client ID and secret or a signing key that Keycloak uses to validate its tokens. Store these outside realm exports and version control, limit who can view or change them in the admin console, and rotate them on a schedule your team can actually run. Record which provider uses which credential so a compromised secret can be revoked without disabling every other broker in the realm.

Require TLS on every external call

Keycloak fetches discovery documents, JSON Web Key Sets, token endpoints and user information from external providers during sign-in. Each of these calls carries credentials or identity data, so each must use HTTPS with certificate validation. Check the trust store used by the Keycloak runtime, especially in private networks where providers sit behind an internal certificate authority, and confirm that no broker is configured with an http endpoint.

Validate backchannel logout tokens from providers

External providers can send backchannel logout tokens to end sessions held in Keycloak. The Keycloak 26.8 upgrade notes make signature validation mandatory for these tokens, so a forged logout cannot be accepted. Before upgrading, test that each provider's logout tokens validate against its published keys, and confirm that the provider's logout endpoint and key configuration match what the broker expects.

Review mappers that copy external attributes

Attribute and role mappers copy claims from the external token into local user attributes and roles. A mapper that reads a claim the provider lets users edit can grant local roles or change attributes that drive authorization. List each mapper, identify the source claim, and decide whether that claim is controlled by your organization. Limit role mappers to claims you trust and test them with a dedicated test account.

How to test that brokered logins work and fail safely

Testing a brokered login means proving two things for every external provider: the happy path produces the right Keycloak user and tokens, and each failure path stops the sign-in instead of quietly creating or linking an account. Build a written test matrix before you touch production configuration, and run it against each identity provider you connect, whether it is an OIDC provider, a SAML 2.0 provider or a social login such as Google, Microsoft or GitHub. Each row should name the provider, the realm, the identity provider alias, the first login flow and the expected result, so that a reviewer can check the outcome without reading the configuration.

Start with the first login. Sign in with a test account that has never existed in the realm and confirm that Keycloak runs the first broker login flow you configured, creates exactly one local user, and maps the claims you intended, such as email, given name and any group or role attributes. Then sign in a second time with the same account and confirm that Keycloak reuses the existing user rather than creating a duplicate. Check the user list in the admin console after each step. A duplicate user on the second login is one of the most common defects in brokering setups, and it usually points to a mismatch in the username or link configuration.

Next, test the cases that must be stopped. Use a test account whose email is unverified at the provider, and another whose email matches an existing local user but comes from a different provider identity. The expected result is that sign-in is blocked or routed to a review step that your flow defines, and that no link is created silently. Then test account linking. When a link to an existing local account is required, confirm that Keycloak asks for the local password or a second factor (OTP, WebAuthn or a recovery code, depending on your policy) before it attaches the external identity. Also test a revoked or disabled provider and a removed attribute mapping. In both cases the login should fail closed, with no partial user creation.

For every test, inspect what was issued. Decode the ID token from the external provider in a debugging tool or through the broker's logs, and compare its issuer, audience, subject and email claims with what Keycloak recorded. Then inspect the Keycloak access and ID tokens for the expected claims and roles, and confirm that no provider-specific claim leaks into tokens for clients that should not see it. Record the token claims in your test log, since auditors and your own security team will ask for evidence of the mapping behavior.

Run every test from a clean browser session, such as a new private window with no cookies or an automated browser profile that is reset each time. Reused sessions can hide broker state, skip the first login flow and make a failed case look successful. Confirm the outcome from the user's point of view as well as in the admin events log. Ask your identity team and the provider's administrators to confirm the exact client registration, redirect URIs and claim names for each provider before the tests begin, because those values, not the Keycloak defaults, decide whether the test results are meaningful.

What to monitor, document and re-test after brokering goes live

Once external identity providers are brokered into a realm, the broker becomes a shared dependency for every application that signs in through it. The cards below cover the records you keep, the signals you watch, the tests you rerun after change, and the rotation work that sits at both ends of each trust relationship.

Provider registration record

For each identity provider, record the team that owns the registration at the external provider, the redirect URIs registered there, the client identifier, and the date the client secret or signing certificate was last rotated. Keep the record alongside the realm configuration so that whoever answers an outage call can see who to contact and which URI must match. Review the record whenever a hostname or realm name changes.

Claim contract per provider

Document which claims each external provider must send, such as subject, email, email verification status and group membership, and how each one maps to Keycloak user attributes or roles. Note which claims are required for first login and which are optional. When an external team changes a claim name or format, this written contract shows which mappers and first login rules are affected.

Login failures per provider

Keycloak can expose Prometheus-format metrics on its management interface when metrics are enabled, and the event log records login errors. Build a view that separates failures by identity provider so that a spike at one provider does not hide inside overall sign-in numbers. Agree with the team which failure rate and duration should trigger a page, since DeployOpen does not set alert thresholds for your environment.

Rotation at the external provider

Certificate and client secret rotation at the external provider is a change Keycloak does not see until a login fails. Agree a rotation calendar with the provider team, confirm which signing certificate Keycloak trusts and whether the provider publishes old and new keys during overlap, and test a sign-in in a non-production realm before the old credential expires. Record each rotation in the provider registration record.

Re-testing after Keycloak upgrades

Keycloak minor releases can change broker or authentication behavior, and the upgrade notes for each release state which changes apply. After each upgrade, rerun first login, account linking, attribute mapping and logout for every brokered provider in a copy of production. Confirm that backchannel logout tokens from external providers are still validated, since the 26.8 upgrade notes make signature validation mandatory for them.

Ownership and review cadence

Name one owner in the identity team for the broker configuration and one contact per external provider, and agree how often the registration records and claim contracts are reviewed. Decide with the team who approves a change to a redirect URI or a mapper, and who is told when a provider announces a change. Without named owners, a rotation or claim change tends to surface first as a user-facing sign-in failure.

What buyers ask before bringing in help with identity brokering

What drives the cost of Keycloak identity brokering work?

The cost is driven mainly by the number of external identity providers, the quality of the claims they send, the complexity of your linking rules, and how many environments the work covers. Each provider needs its own client configuration, mapper design, first login flow decisions and testing, so the work scales with the number of providers. Your own team pays for provider admin time, decision owners and test accounts, while a partner bills against the written scope. One-time costs include design, build and testing. Recurring costs appear when a provider changes its claims or certificates, when Keycloak is upgraded, or when a new provider is added. When you request a quote, ask for line items per provider, the environments included, the test coverage, and the assumptions made about claim formats.

How long does a Keycloak brokering project usually take?

Duration depends on the number of providers and on how much test coverage you require, and it is fixed in the written scope before work starts. A single provider with predictable claims moves faster than several providers that each send claims in different formats. Schedule risk usually comes from waiting on provider admins to create clients, share metadata or issue test accounts, not from the Keycloak configuration itself. Ask for milestones per provider, the dependencies you must meet, and the test cases that count as done. If a provider's team cannot commit dates, ask how the scope handles a delayed provider, so the rest of the project can continue in a non-production realm.

What does our team need to provide for identity brokering work?

You need provider admins who can register Keycloak as a client in each external identity provider and share the metadata, client identifiers and signing certificates. You also need test accounts for each provider, including accounts for common edge cases such as a user with no email address, a user whose email is unverified, and a user who already exists locally. Decision owners must approve the linking rules, including whether accounts are matched on a verified email, whether users confirm a link, and which attributes Keycloak may overwrite on each login. Finally, you need access to a non-production Keycloak realm and to the application owners who will consume the resulting tokens.

Can our own team set up Keycloak brokering without a partner?

Yes, for one external provider with clean, stable claims and simple linking rules, an experienced Keycloak team can usually do the work alone. The harder cases involve several providers, inconsistent claim formats, group or role claims that need mapping, and linking rules that touch existing accounts. Account linking deserves the most care, because linking on an email address that the provider has not verified can let one person take over another person's account. If your team is new to OIDC or SAML trust settings, or if security review is required before go-live, a fixed-scope partner engagement can cover the design review, build and test evidence in one place.

Does Keycloak identity brokering replace our user directory?

No. Brokering passes the sign-in step to an external identity provider, but Keycloak still creates and stores a local user record on first login, and your existing directory keeps its role as the source of truth for identities it owns. Brokering does not make Keycloak read users from that directory. If you need Keycloak to query LDAP or Active Directory for users, groups and password checks, that is user federation, which is covered in the sibling topic Keycloak LDAP and Active Directory user federation. Decide early which system owns each attribute, because conflicting ownership is a common source of stale data after the first login.

What usually breaks when linking accounts across identity providers?

The most common failures are duplicate accounts, accounts linked to the wrong person, and attribute mappers that overwrite good values with empty ones. Duplicates appear when the first broker login flow matches on a field that changes, such as a display name, or on an unverified email. Wrong links appear when two providers reuse an email address or when a provider's subject identifier is not stable. Mapper problems appear when a claim is missing for some users and the mapper clears a local attribute. Test each provider with a new user, an existing user and a user whose claims change between logins, and confirm the resulting local user record after each run.

What should we check in a provider's claims before mapping them?

Start by confirming that the subject identifier is stable for each user, because it is the basis for a durable link. Check whether the email claim is present and whether the provider marks it as verified, since linking rules depend on that signal. For group or role claims, confirm the format, whether values are multivalued, and whether the provider includes them only when a specific scope is requested. Ask the provider admin for sample tokens or assertions from a non-production test user, and record the claim names, types and examples in your design notes. Re-check these claims after any provider configuration change, because claim names often change without notice.

How DeployOpen works on this

DeployOpen plans and implements Keycloak identity brokering inside your own infrastructure, so the external identity providers, first login rules and attribute mappings are agreed before any configuration changes. Each engagement is fixed-scope, with deliverables and timelines confirmed in writing before work starts.

How we scope

Inventory the external OIDC, SAML and social providers that users will sign in through, and who owns each one.
Agree which first login flows, account linking rules and trust settings apply to each provider in the written scope.
Define the attributes and roles to map from each provider, and which claims must be present before access is granted.

How we build

Configure each identity provider in a non-production realm first, then test sign-in with real test accounts from each provider.
Build first login flows and account linking behavior, including how existing local accounts are matched or refused.
Document the mapper configuration and test cases so each provider change can be reviewed and repeated later.

How we hand over

Hand over realm exports, provider configuration and mapper definitions stored in your own version control.
Deliver a runbook covering how to add a provider, rotate client secrets and respond to failed brokered logins.
Walk your identity and application teams through the test results, open risks and the sign-in paths left out of scope.

How we support

Ongoing support, upgrades and testing of brokered sign-in are available as a retainer, scoped separately from the build.
Confirm with us how provider certificate and secret expiry will be tracked, since these break brokered sign-in when missed.
Plan reviews of upgrade notes before each Keycloak minor release, since behavior changes are documented per release.