Configure mappers

To use your external identity provider (IDP) metadata for user profile information or automatic group assignment, you must define mappers within your IDP configuration.

Mapper types

Four types of mappers are available within the IDP configuration:

  • Hardcoded group: assigns the user to the specified group.

  • Attribute importer: imports user profile information, if any, from the identity provider JSON into the specified user attribute.

  • Hardcoded attribute: sets a predefined value to a specific user attribute when importing the user from the provider.

  • Advanced claim to group: assigns the user to the designated group if all specified claims exist. This mapper type is exclusively available for OpenID Connect IDPs.

Configuration

To configure an IDP mapper:

  1. In the navigation drawer of the Site Administration interface, select Identity providers.

  2. Select an IDP from the list.
    The IDP editor opens.

  3. Select the Mappers tab.

  4. Click the App mapper Add mapper button.
    The Add mapper dialog opens.

  5. In the dialog:

    1. Select a provider type from the Type drop-down menu.

    2. Enter a name for the new mapper in the Name field.

    3. Click Confirm.
      The newly created mapper appears in the list.

  6. Click the mapper to configure it.
    The mapper editor opens.

  7. Enter the configuration properties using the table below for reference.

General

Property Definition

Name

Name of the mapper.

Type

Type of the mapper, as described in Mapper types.

Sync mode override

Overrides the default sync mode of the IDP for this mapper. Possible values are:

  • Import: imports the user only once during the user’s first login with this IDP.

  • Force: always updates the user every time they log in with this IDP.

  • Inherit: uses the sync mode defined in the IDP for this mapper.

Group

Only applicable if the mapper type is Hardcoded group.
Group to which the user is assigned.

Claim

Only applicable if the mapper type is Attribute importer and IDP type is OpenID Connect.
Name of the claim to search for in the token. Nested claims can be referenced using a dot (e.g., address.locality). To use a dot (.) literally, escape it with a backslash (\).

Social profile JSON field path

Only applicable if the mapper type is Attribute importer and IDP type is Google or Microsoft.
Path of a field in the IDP’s user profile JSON data from which to retrieve the value. Dot notation can be used for nesting, and square brackets for array indexing (e.g., contact.address[0].country).

User attribute name

Only applicable if the mapper type is Hardcoded attribute.
Name of the user attribute name where the information will be stored.

User attribute

Only applicable if the mapper type is Hardcoded attribute.
Name of the user attribute that you want to hardcode.

User attribute value

Only applicable if the mapper type is Hardcoded attribute.
Value of the user attribute that you want to hardcode.

Claims

Only applicable if the mapper type is Advanced claim to group.
Name and value of the claims to search for in the token. Nested claims can be referenced using a dot (e.g., address.locality). To use a dot (.) literally, escape it with a backslash (\).

Regex claim values

Only applicable if the mapper type is Advanced claim to group.
If enabled, claim values are interpreted as regular expressions.

Group

Only applicable if the mapper type is Advanced claim to group.
Group to assign the user to if the claim is present.