Mapping claims and assertions

You can import the SAML and OpenID Connect metadata, provided by the external IDP you are authenticating with, into the realm. After importing, you can extract user profile metadata and other information, so you can make it available to your applications.

Each user logging into your realm using an external identity provider has an entry in the local Keycloak database, based on the metadata from the SAML or OIDC assertions and claims.

Procedure

  1. Click Identity Providers in the menu.

  2. Select one of the identity providers in the list.

  3. Click the Mappers tab.

    Identity provider mappers

    identity provider mappers

  4. Click Add mapper.

    Identity provider mapper

    identity provider mapper

  5. Select a value for Sync Mode Override. The mapper updates user information when users log in repeatedly according to this setting.

    1. Select legacy to use the behavior of the previous Keycloak version.

    2. Select import to import data from when the user was first created in Keycloak during the first login to Keycloak with a particular identity provider.

    3. Select force to update user data at each user login.

    4. Select inherit to use the sync mode configured in the identity provider. All other options will override this sync mode.

  6. Select a mapper from the Mapper Type list. Hover over the Mapper Type for a description of the mapper and configuration to enter for the mapper.

  7. Click Save.

For JSON-based claims, you can use dot notation for nesting and square brackets to access array fields by index. For example, contact.address[0].country.

To investigate the structure of user profile JSON data provided by social providers, you can enable the DEBUG level logger org.keycloak.social.user_profile_dump when starting the server.