Mapping Claims and Assertions in Keycloak

Keycloak’s integration with external identity providers (IDPs) via SAML (Security Assertion Markup Language) and OIDC (OpenID Connect) enables user authentication while bringing valuable user profile information. The integration process claims and assertions to Keycloak’s local user attributes, which can then be used by applications within your realm. This blog will walk through the steps and best practices for setting up and configuring claims and assertions mapping in Keycloak.

Understanding SAML and OIDC Metadata Imports

When integrating an IDP, Keycloak can import its SAML or OIDC metadata, which defines how the IDP transmits user data. This import includes the user profile data, claims (for OIDC), and assertions (for SAML), which can then be mapped onto Keycloak’s user attributes. Once integrated, every new user who logs in through the external provider has an entry created in Keycloak’s database, making it easier to manage these users within the realm.

Why Import Metadata?

Importing metadata from the IDP into Keycloak allows you to synchronize user attributes and customize access controls based on information from the external provider. This setup helps ensure secure, efficient authentication and user data flow from IDP to Keycloak, allowing seamless access for applications that rely on Keycloak’s identity and access management.

Setting Up Mappers for Claims and Assertions

After the external IDP is connected, configuring mappers in Keycloak is essential to translate the IDP’s data into Keycloak’s user model. Mappers help assign data from SAML assertions or OIDC claims to user attributes and roles in Keycloak.

Accessing Mappers in Keycloak

Navigate to the Identity Providers Page: Within your realm, go to Identity Providers and select the configured provider.
Open the Mappers Tab: Under the settings for your chosen IDP, go to the Mappers tab. Here, you can define how specific claims or assertions map to Keycloak’s internal structure.
Click Create: Use the Add mapper button to add a new broker mapper. Broker mappers allow you to transform IDP-provided data into local attributes, allowing applications to access external user data seamlessly.

Mapping Claims and Assertions in Keycloak

Selecting and Configuring Mapper Types

When creating a new mapper, Keycloak offers different mapper types, each designed for specific tasks. Common mapper types include the following things.

SAML Attribute Mapper: Maps attributes in SAML assertions from the IDP to Keycloak user attributes.
OIDC Claim Mapper: Maps OIDC claims, such as email or name, to Keycloak’s internal user fields.

Select the appropriate mapper type and complete the necessary fields, such as Token Claim Name (for OIDC) or Attribute Name (for SAML). These fields specify the exact claim or assertion Keycloak should import, as well as the local Keycloak attribute to which it maps.

Practical Example: Mapping an Email Claim

For example, if the external IDP provides an email claim, you can map this to the email field in Keycloak’s user attributes:

Mapper Type: Select OIDC Claim Mapper.
Token Claim Name: Enter email.
User Attribute Name: Enter email.

This configuration will automatically populate the email field for any user authenticating through the external IDP.

Advanced Mapping with JSON-Based Claims

For more complex data structures, especially JSON-based claims, Keycloak supports dot notation and array indexing. This functionality is useful when the IDP’s user data includes nested fields or arrays. For example, if a claim from the IDP has contact.address[0].country, you can use this exact notation in the mapper configuration to ensure Keycloak extracts the correct data.

Debugging and Testing Mappers

After configuring mappers, it’s a good idea to verify that the mappings are correct and functioning as expected. Keycloak provides a logging feature that enables detailed inspection of user profile data received from social identity providers:

Enable DEBUG Logging: In the server configuration file (standalone.xml or domain.xml), enable the logger org.keycloak.social.user_profile_dump at the DEBUG level.
Review the Output: The debug log will provide a JSON output of user data, allowing you to examine the claim structure and refine mappings as necessary.

Thanks for reading ❤️

Mapping claims and assertions in Keycloak is crucial for leveraging the full functionality of external IDPs. By setting up mappers to import SAML attributes and OIDC claims, Keycloak can centralize user data management while giving applications easy access to enriched user profiles. Thank you so much for reading and do check out the resources provided to learn more about the Keycloak. You can click the button below to create your service on Elestio. See you in the next one👋