What are Identity Provider Mappers in Keycloak?
When a user logs in through Google or a partner company's own login system, someone has to translate their profile into a shape Keycloak understands. That translator is the Identity Provider Mapper.
Imagine two companies merging their phonebooks. One company writes names as “Last, First” and stores phone numbers with dashes; the other writes “First Last” and stores numbers with dots. Before you can merge them into one clean directory, someone has to translate every entry into a shared format. Keycloak faces exactly this problem whenever it lets someone log in through an outside identity system — Google, a corporate Active Directory, another company’s Keycloak, or any other external provider. The incoming information arrives in that outside system’s format, and Keycloak needs it translated into its own. That translation job belongs to Identity Provider Mappers. This guide explains what they are, how they fit into Keycloak’s login process, what happens internally on every external login, and how to design and operate them well. No prior background in identity systems is assumed.
1Core Concepts
What is Identity Brokering?
Identity brokering is Keycloak’s ability to let users log in using an account they already have somewhere else, instead of creating a brand-new username and password just for this application. The outside system — Google, Facebook, a corporate Microsoft Entra ID tenant, another Keycloak realm — is called an Identity Provider (often shortened to IdP). Keycloak acts as the middleman, or “broker,” between the user, the external IdP, and the application the user is actually trying to reach.
Why is a translator needed at all?
When a user logs in through an external IdP, that IdP sends back a set of facts about the user — an email address, a name, maybe a department or job title — but it sends them using its own field names and its own format. Google might call the field given_name; a corporate directory might call it firstName; another system might bury it inside a nested group of custom attributes entirely. Keycloak, meanwhile, has its own fixed internal idea of a user record, with fields like username, email, first name, last name, and custom attributes. An Identity Provider Mapper is the configured rule that says “take this specific field from the external IdP’s response, and place it into this specific field on the Keycloak user record.”
Think of a customs officer at an international border processing paperwork written in a foreign language and a different date format. The officer doesn’t just staple the foreign form to a local file and call it done — they translate the relevant fields (name, date of birth, nationality) into the local system’s format so every other department in the country can actually read and use that information consistently. Identity Provider Mappers are that customs officer, standing between the external identity provider’s paperwork and Keycloak’s own records.
Where do mappers fit into a login?
Mappers run automatically, behind the scenes, every time a user completes a login through a configured external identity provider. The user never sees this step directly — from their point of view, they just clicked “Sign in with Google” and ended up logged into the application. But internally, right after Google confirms the user’s identity and hands back a set of claims, Keycloak’s mappers step in to decide exactly how that information becomes part of the Keycloak-managed user record.
Any Keycloak deployment offering “Sign in with Google,” “Sign in with Microsoft,” or federating logins from a partner organization’s own identity system relies on Identity Provider Mappers to correctly populate names, emails, roles, and group memberships for those users.
Key vocabulary, explained simply
Identity Provider (IdP)
An external system a user can log in through instead of a Keycloak-managed password — Google, a corporate directory, or another Keycloak realm are common examples.
Identity Provider Mapper
A configured rule that extracts a piece of information from the external IdP’s login response and applies it to the Keycloak user record.
Claim
A single labeled fact returned by the external provider — for example, an email address or a department name — that a mapper can read from.
Brokered User
A Keycloak user account that was created or updated as a result of logging in through an external identity provider, rather than registering directly with Keycloak.
First Login Flow
The specific Keycloak authentication flow that runs the very first time a given external user logs in, often where mappers apply their initial values.
Sync Mode
A setting controlling whether a mapper’s values are applied once, or re-applied on every subsequent login, keeping the Keycloak record fresh over time.
2Architecture & Components
graph TB
EXT[External IdP
Google / Corporate AD / Partner Keycloak] -->|sends claims| BRK[Keycloak Identity
Brokering Endpoint]
BRK --> MP[Mapper Pipeline]
MP --> M1[Attribute Importer Mapper
e.g. email, firstName]
MP --> M2[Role Mapper
maps IdP claim to Keycloak role]
MP --> M3[Group Mapper
maps IdP claim to Keycloak group]
MP --> M4[Custom / Hardcoded Mapper]
M1 --> USR[Keycloak User Record]
M2 --> USR
M3 --> USR
M4 --> USR
Component breakdown
Identity Provider Configuration
The realm-level registration of the external IdP itself — its login URL, client credentials, and protocol (OIDC or SAML) — under which all its mappers are attached.
Attribute Importer Mapper
The most common mapper type, copying a specific external claim (like email or given_name) directly into a matching Keycloak user attribute.
Role and Group Mappers
Mapper types that translate an external claim’s value — such as a department name or a security group — into membership of a specific Keycloak role or group.
Hardcoded and Template Mappers
Mapper types that assign a fixed value, or a value built from a template combining several claims, useful when the external system doesn’t send exactly the shape of data needed.
Where this is configured in the admin console
Inside the Keycloak Admin Console, an administrator opens Identity Providers, selects the specific provider (say, “google” or a custom SAML provider), and switches to its Mappers tab. From there, “Add mapper” opens a list of available mapper types, each with its own configuration fields — typically the external claim name to read from, and the Keycloak field or role/group to write to.
A common real setup
A company federates logins from a partner organization’s Keycloak realm. An Attribute Importer Mapper copies the partner’s email claim into the local email field, a second one copies given_name and family_name into first and last name, and a Role Mapper reads the partner’s department claim, granting the local “external-partner” role whenever that claim equals “engineering.”
Protocol matters: OIDC versus SAML claim shapes
Identity providers speak one of two common protocols — OpenID Connect (OIDC), which sends claims as a JSON structure, or SAML, which sends them as XML attributes. Keycloak’s mapper types differ slightly between the two, since the underlying claim format is different, but the concept and purpose remain identical: read a specific piece of external data, and place it correctly into the Keycloak user record.
3Internal Working
What happens on a user’s very first brokered login
When a user logs in through an external IdP for the first time, Keycloak receives the IdP’s response containing all of its claims. Before creating a permanent Keycloak user record, Keycloak runs every configured mapper against this response, in order. Each mapper reads its designated claim and writes the resulting value onto a temporary in-memory representation of the new user. Once all mappers have run, Keycloak (depending on configuration) either creates the new user record automatically or pauses at a “review profile” step, letting the user confirm or adjust the imported details before the account is finalized.
What happens on every login afterward
On subsequent logins, Keycloak again receives fresh claims from the external IdP and again runs the mapper pipeline — but what happens with the results depends entirely on each mapper’s configured sync mode. A mapper set to sync “on every login” re-applies its value each time, keeping the Keycloak record continuously up to date with the external source. A mapper set to sync only “on first login” leaves the existing Keycloak value untouched afterward, even if the external claim later changes.
Why sync mode matters so much
Choosing the wrong sync mode causes two very different, equally real problems. Syncing too rarely means a user’s Keycloak profile silently drifts out of date compared to their actual external record — for example, keeping an old department after a legitimate transfer. Syncing too aggressively can overwrite legitimate local customizations a user or admin made directly inside Keycloak, since the external value wins every time. Choosing sync mode deliberately, per field, per identity provider, is one of the more consequential configuration decisions in a brokered setup.
Role and group mappers with “force sync” behavior can silently remove a role or group membership a local admin manually granted, the moment the external IdP’s claim no longer matches — a frequent source of confusing, hard-to-diagnose access changes.
Step-by-step: a brokered login with mappers
User selects external login
The user clicks “Sign in with [Provider]” on Keycloak’s login page.
Redirect and authenticate externally
Keycloak redirects to the external IdP, where the user actually logs in using that system’s own method.
Claims returned to Keycloak
The external IdP redirects back with a signed response containing the user’s claims.
Mapper pipeline runs
Keycloak runs every configured mapper against the incoming claims, in order.
User record created or updated
Depending on whether this is a first login or a return visit, and each mapper’s sync mode, the Keycloak user record is created or selectively refreshed.
Token issued to application
Keycloak completes the login as normal, issuing a token to the application the user originally wanted to reach.
4Data Flow & Lifecycle
sequenceDiagram
participant User
participant Keycloak
participant IdP as External Identity Provider
participant App as Application
User->>Keycloak: Clicks "Sign in with Provider"
Keycloak->>IdP: Redirects for external login
User->>IdP: Authenticates with external credentials
IdP->>Keycloak: Returns signed claims
Keycloak->>Keycloak: Runs Identity Provider Mappers
alt First login
Keycloak->>Keycloak: Creates brokered user record
else Returning user
Keycloak->>Keycloak: Updates record per sync mode
end
Keycloak->>App: Issues token
App->>User: Shows logged-in dashboard
Notice that the application at the end of this chain never interacts with the external identity provider directly, and never sees the raw external claims either. It only receives the finished, Keycloak-formatted token — exactly the same shape of token it would receive from a normal, non-brokered login. This is precisely the value mappers deliver: applications stay completely insulated from however many different external identity systems an organization happens to federate with.
The lifecycle of a mapped attribute
Mapper defined
An administrator adds a mapper to an identity provider, specifying the external claim and the destination Keycloak field, role, or group.
Applied at first login
The first time any user authenticates through that provider, the mapper populates their brand-new Keycloak record.
Re-applied or preserved on later logins
Depending on sync mode, the value either refreshes on every subsequent login or is left as the user or an admin last set it.
Retired or reconfigured
If the external system changes its claim names or an organization changes its mapping requirements, the mapper is updated or removed, affecting only future logins, not retroactively changing already-stored data.
Changing or deleting a mapper does not automatically go back and fix already-created user records — it only changes what happens on future logins, so a migration of existing brokered users sometimes needs a separate, deliberate cleanup step.
5Advantages, Disadvantages & Trade-offs
Advantages
- Lets users log in with an account they already trust and remember, reducing password fatigue and support burden
- Insulates applications entirely from the details of any specific external identity provider’s data format
- Enables automatic, ongoing synchronization of roles and profile details from an authoritative external source
- Supports federating with many different providers at once, each with its own independently configured mapping rules
Disadvantages & Trade-offs
- Aggressive sync settings can overwrite legitimate local customizations made directly inside Keycloak
- Every new external claim format requires deliberate mapper configuration — nothing is translated automatically without an admin defining the rule
- Reliance on an external IdP means Keycloak’s own record quality is only as good as the accuracy of the upstream data
- Debugging incorrect user data often means tracing back through both the external provider’s claims and the mapper configuration together, which is more moving parts than a simple local account
Relying on a translator at an international meeting speeds things up enormously — but if the translator mishears a word or uses an outdated glossary, the mistake propagates into every decision made afterward. Mappers carry the same responsibility: get the translation wrong, and the error becomes part of the permanent record, not just a passing miscommunication.
6Security
Trusting the wrong claim can grant unintended access
A Role Mapper that grants a powerful role based on a claim the external IdP doesn’t tightly control — say, a freely editable “title” field a user can set themselves — can let a user grant themselves elevated access simply by changing that field on the external system. Mappers should only be wired to claims the external identity provider treats as authoritative and tightly controlled, never to self-editable, low-trust fields.
Context
Some external identity providers expose user-editable profile fields (like a free-text job title) alongside genuinely authoritative ones (like a centrally managed security-group membership), and it’s easy to accidentally map a role from the wrong one.
Decision
Only configure Role or Group Mappers against claims the external provider’s own administrators control centrally, never against fields an end user can edit on their own external profile.
Consequence
Privilege escalation through self-edited external attributes becomes impossible, since the mapper only ever reads from a source the user has no ability to influence directly.
Claim spoofing and provider trust
Keycloak validates the signature on claims coming from a properly configured OIDC or SAML identity provider, ensuring the claims genuinely came from that trusted provider and weren’t tampered with in transit. This is why configuring the identity provider’s trust settings (certificates, signing keys, expected issuer) correctly is a prerequisite for mappers to be trustworthy at all — a mapper can only be as secure as the verified authenticity of the claims it reads from.
Mapping an external “email” claim directly into a Keycloak username or trusting it blindly for account linking, without considering that some providers allow unverified or user-changeable email addresses, which can enable account takeover through email reuse.
Auditing mapper-driven changes
Because mappers can silently change a user’s roles or groups on every login without any explicit admin action at that moment, keeping Keycloak’s admin event logging enabled for identity-provider-related changes helps ensure that access changes driven by external claims remain visible and reviewable, not invisible side effects of a routine login.
7Monitoring, Logging & Metrics
New brokered user rate
Tracking how many new Keycloak accounts are created via a given identity provider over time, useful for spotting unexpected spikes that might indicate misuse or a broken linking configuration.
Role/group change events from brokered logins
Logging every case where a login through an external IdP results in a role or group membership change, since these can otherwise happen silently and go unnoticed.
Mapper configuration change frequency
Watching how often mapper settings themselves are modified, since unexpected changes here can indicate either legitimate maintenance or unauthorized tampering with access rules.
Claim-missing errors
Logging cases where a mapper expects a claim the external provider didn’t actually send, which usually signals a provider-side change or a misconfigured mapper claim name.
A practical monitoring habit
Many teams periodically export a sample of recent brokered logins’ raw claims alongside the resulting Keycloak user record, specifically to visually confirm that mappers are still translating fields correctly — catching a silent upstream change (like a renamed claim) before it causes a wider data-quality problem across the user base.
8Design Patterns & Anti-patterns
Proven patterns
Minimal first-import, ongoing refresh for trusted fields
Import basic profile fields (name, email) once at first login to allow local customization, but keep authoritative fields like department or security-group role continuously synced.
Explicit claim-to-role mapping table
Maintain a documented, reviewable table of exactly which external claim values map to which Keycloak roles, rather than relying on ad hoc, hard-to-audit logic scattered across mapper configurations.
Provider-specific mapper sets
Configure each identity provider’s mappers independently, even when providers overlap in purpose, since their underlying claim formats and trust levels usually differ.
Review-profile step for first-time users
Pause at a “confirm your details” screen on first brokered login, letting the user catch an obviously wrong imported value before the account is finalized.
Anti-patterns to avoid
Anti-pattern
- Mapping a role or group from a claim the end user can freely edit on the external system
- Forcing every attribute to sync on every login, silently overwriting legitimate local edits
- Leaving mapper claim names undocumented, making future troubleshooting a guessing game
- Assuming every identity provider sends the same claim names without verifying the actual response shape first
Instead, do this
- Map roles and groups only from centrally controlled, non-editable claims
- Choose sync mode deliberately, per field, based on whether the external or local value should win
- Document every mapper’s claim source and destination clearly
- Inspect a real login’s actual claims before finalizing mapper configuration, rather than assuming a standard shape
9Best Practices & Common Mistakes
Best practices
Test against a real account from each provider
Verify mapper behavior using an actual login from each external identity provider, since claim shapes can differ from documentation or assumptions.
Keep a mapping reference document
Maintain a clear, accessible record of which external claim maps to which Keycloak field, role, or group, per identity provider.
Coordinate sync mode with account-ownership expectations
Decide, per field, whether the external system or the local Keycloak admin should be considered the source of truth, and configure sync mode to match that decision consistently.
Review mappers whenever an external provider changes
Treat an upstream identity provider’s own configuration changes (a renamed claim, a new attribute format) as a trigger to re-verify every dependent mapper.
Common mistakes
Assuming every external provider’s claim names follow a universal standard, when in practice even providers using the same underlying protocol frequently use different, provider-specific claim names for similar information.
Not distinguishing between first-login-only mappers and every-login mappers, leading to either stale data that never refreshes or unexpected overwrites of manually corrected local values.
Forgetting that deleting or changing a mapper does not retroactively fix already-created user records, and being surprised when old brokered accounts still show outdated or incorrectly mapped data.
10Real-world & Industry Examples
Enterprise workforce identity
Large organizations federating employee logins from a central corporate directory into Keycloak-protected internal tools rely on role and group mappers to automatically reflect organizational structure without manual provisioning per application.
Consumer applications with social login
Consumer-facing platforms offering “Sign in with Google” or similar social logins use attribute mappers to populate basic profile information automatically, reducing signup friction for new users.
B2B SaaS platforms
Software vendors serving enterprise customers commonly let each customer organization federate their own identity provider, using per-provider mappers to correctly translate each customer’s unique claim structure into a consistent internal user model.
Mergers and acquisitions
Organizations integrating systems after a merger often use Keycloak as a broker between two previously separate identity systems, with mappers bridging the gap while a longer-term consolidation plan is worked out.
A representative scenario
A software company selling to enterprise customers needed each customer’s employees to log in using their own corporate identity system. Rather than building custom integration code for every customer, the company configured Keycloak to broker each customer’s identity provider individually, using Attribute Importer Mappers to normalize differently named claims into a consistent internal user profile, and Group Mappers to translate each customer’s own security-group naming conventions into the company’s standard internal roles.
11FAQ
12Summary and Key Takeaways
Key Takeaways
- Identity Provider Mappers translate claims from an external login system into Keycloak’s own user record fields, roles, and groups.
- They run automatically as part of identity brokering, whenever a user logs in through a configured external identity provider like Google or a corporate directory.
- Common mapper types include Attribute Importer, Role Mapper, Group Mapper, and Hardcoded/Template mappers.
- Sync mode determines whether a mapper’s value is applied once at first login or refreshed on every subsequent login — choosing this correctly per field avoids both stale data and unwanted overwrites.
- Role and group mappers should only read from claims the external provider tightly controls, never from fields an end user can freely edit themselves, to avoid privilege-escalation risk.
- Mapper changes are not retroactive — they only affect logins that happen after the change, leaving existing brokered user records untouched until their next login.
- Because mappers run silently on every login, deliberate monitoring and auditing of resulting role, group, and attribute changes is essential to catch drift or misuse early.
- Well-designed mappers let applications remain completely insulated from however many different external identity systems an organization federates with.