IdP Mappers

Why mappers are needed

When a user logs in via a brokered identity provider, the external IdP sends a token (for OIDC) or an assertion (for SAML) that contains claims — pieces of information about the user such as their email address, display name, group memberships, or department. Keycloak does not automatically map all of these onto the local user record.

IdP mappers are rules you configure on an identity provider that tell Keycloak: “when this user logs in via this IdP, take claim X from their external token and set it as Keycloak attribute Y” (or assign them role Z, or set a specific username template).

Without mappers, brokered users often have incomplete profiles and no realm roles — because Keycloak only copies a minimal set of standard attributes (email, first name, last name) from the external token by default.

Types of IdP mappers

Mapper type	What it does
Attribute importer	Copies a named claim from the external token into a Keycloak user attribute (e.g., department claim → department attribute).
Hardcoded attribute	Sets a specific Keycloak user attribute to a fixed value for all users from this IdP (e.g., set org to acme-corp for everyone from the Acme IdP).
Hardcoded role	Assigns a Keycloak realm role or client role to every user who logs in via this IdP.
Role importer	Maps a specific claim value from the external token to a Keycloak role (e.g., if the external token has groups: ["admin"], assign the Keycloak admin realm role).
Username template importer	Constructs the Keycloak username from a template using claim values (e.g., \${CLAIM.email} to set the username to the external email).
Hardcoded user session note	Attaches a fixed value to the user’s session (used for auditing).

Step 1 — navigate to the IdP’s mapper list

1. In the admin console, click Identity providers in the left sidebar.
2. Click the alias of the identity provider you want to configure.
3. Click the Mappers tab.
4. Click Add mapper.

Step 2 — configure an attribute importer

To copy the external department claim onto the Keycloak user:

1. Set Mapper type to Attribute importer.
2. Set Name to something descriptive, e.g., Import department.
3. Set Claim (for OIDC) or Attribute (for SAML) to department — the exact key as it appears in the external token.
4. Set User attribute name to department — the name of the Keycloak user attribute to populate.
5. Click Save.

The next time a user logs in via this IdP, Keycloak will copy the department value from their external token into their Keycloak profile.

Step 3 — configure a hardcoded role mapper

To assign the Keycloak realm role employee to everyone who logs in via this IdP:

1. Click Add mapper.
2. Set Mapper type to Hardcoded role.
3. Set Name to Assign employee role.
4. In Role, start typing employee and select the realm role from the dropdown.
5. Click Save.

Sync mode per mapper

Each mapper has a Sync mode setting (overriding the IdP-level sync mode):

INHERIT  — use the IdP-level sync mode setting.
LEGACY   — only apply this mapper on first login.
FORCE    — re-apply this mapper on every login (useful for roles and attributes that may change in the external IdP).

# Use FORCE for attributes/roles that change frequently in the external IdP
Mapper sync mode: FORCE

Copy recommendation ⧉

Checking the result

After saving mappers and logging in as a brokered user, you can verify the result:

1. Go to Users in the left sidebar and find the brokered user.
2. Click the user’s username.
3. On the Details tab, check the Attributes section for imported attributes.
4. On the Role mappings tab, check for the hardcoded role.

🔐 Use IdP mappers to copy external claims onto Keycloak users

Without IdP mappers, brokered users arrive with only the minimal standard claims (email, first name, last name). Use mappers to copy the external provider’s claims — groups, department, custom attributes — onto the Keycloak user at login. Use FORCE sync mode for any mapper whose value may change between logins.

Trade-offs

Option	Benefit	Cost
Map many claims (import every attribute the external IdP sends)	A complete user profile that covers future use cases without revisiting the mapper	Increases attack surface and stores more PII than needed, adding privacy/compliance overhead
Map only what you actually use (minimal mapping)	Lower privacy risk — only the data the application really needs is stored, and it’s easier to review	Adding an attribute later means going back to add a mapper, and users may need to log in again for it to sync

Common mistakes

• Not mapping email_verified or another verification-status claim — Keycloak then has no way to know whether the user’s email was verified by the external IdP, affecting flows such as account recovery that depend on a verified email.
• Forgetting to set Sync mode to FORCE for claims that change often — such as group membership or role. With LEGACY (the default), the value is applied only on first login, so a user’s permissions can go stale even after the external IdP updates them.
• Using a hardcoded role mapper with the wrong scope — assigning a role too broadly to every user from one IdP, without differentiating by the actual claim (use a role importer instead when permissions should depend on data from the external token).

Real-world example

An organisation brokering with Azure AD that wants to sync employee department/group — uses an attribute importer and a role importer so users who log in via Azure AD automatically get the Keycloak role matching their Azure AD group, with no admin assigning permissions one person at a time.

A platform brokering with Google Workspace — uses a hardcoded attribute mapper to set org for everyone who logs in through the company’s Google Workspace, separating internal users from general social-login users signing in with a personal Google account.

What does an attribute importer mapper do?

Assigns a fixed Keycloak role to all users from the IdP Copies a named claim from the external token into a Keycloak user attribute Creates a new identity provider from an existing user attribute Sets a hardcoded username for all brokered users

When should you use mapper sync mode FORCE?

Only on the first login, to avoid overwriting manual changes Never — FORCE disables attribute mappers When the attribute or role may change in the external IdP between logins When the external IdP uses SAML instead of OIDC

Which mapper type assigns the same Keycloak role to every user from a given IdP?

Attribute importer Role importer Hardcoded role Username template importer

Where in the admin console do you add a mapper for a brokered IdP?

Authentication → Flows → First broker login Identity providers → <alias> → Mappers tab Clients → <client> → Mappers tab User federation → <provider> → Mappers tab

Submit

Mark as complete