Skip to main content

Map User Attributes

Attribute mappers enable Digital.ai Platform to integrate user information from your Identity Provider (IdP) by translating IdP claims or assertions into corresponding fields within the Platform. This ensures that user data, group memberships, and role assignments from your IdP are properly synchronized with the Platform.

note

Your identity provider shares information about users in the form of key/value pairs, known as claims (OIDC) or assertions (SAML). Claims are pieces of information about a user provided by the IdP, such as email addresses, usernames, roles, or custom-defined attributes like department or region.

tip

Mappers are also used when transmitting data from the Platform to other Digital.ai applications, but those mappers are configured automatically during application connection.

Prerequisites​

Before configuring mappers, you must have already established an SSO connection with your identity provider. For more information, see Manage Identity Providers.

Mapper Types​

The Platform uses three types of mappers to handle different aspects of user integration:

  1. User Data Mappers - Map basic user attributes (first name, last name, email, username)
  2. Group Mappers - Synchronize user group memberships from your IdP
  3. Role Mappers - Assign Platform roles based on IdP groups or attributes

Edit Mappers​

You can add or edit mappers at any time after establishing your SSO connection:

  1. Navigate to SSO > Identity providers.
  2. Click the Edit icon for the relevant IdP.
  3. Proceed to the Mappers page.
  4. Modify existing mappers or add new ones as needed.
  5. Review your configuration on the Summary page before saving.

The procedures on this page assume that you have navigated to the Mappers page.

Map User Data​

The Platform requires first name, last name, email address, and username to create a user. Mappers ensure that this data from your IdP is properly understood by the Platform.

OIDC User Data Mapping​

Mappers may be optional for OIDC connections, depending on your organization's configuration. The Platform expects to receive user attributes based on standard claims as defined by OpenID. You can view the list of standard claims at https://openid.net/specs/openid-connect-core-1_0.html#StandardClaim.

Digital.ai expects that given_name, family_name, username, and email are included as claims. If these standard claims are included, they will automatically be mapped to the correct user attributes. If your IdP sends this data using different claim names, you will need to create mappers.

Example: If your IdP uses the standard claim email: john@example.com, the Platform will automatically map it to the email user attribute. However, if your IdP uses a claim called email_address: john@example.com, you need to create a mapper.

SAML User Data Mapping​

Unlike OIDC, the SAML protocol does not follow standard naming conventions. SAML attributes, referred to as assertions, can vary significantly across different IdPs. This lack of standardization necessitates the use of mappers for all SAML connections.

Essential Mappers for SAML​

When setting up SAML connections, you must create mappers for the following user data:

  • First Name - Map the IdP's attribute for the user's first name (e.g., givenName, first_name)
  • Last Name - Map the IdP's attribute for the user's last name (e.g., surname, last_name)
  • Email - Map the IdP's attribute for the user's email address (e.g., email, emailAddress)

Handling Username in SAML​

The username field is treated differently in SAML connections. By default, the username is derived from the NameID attribute defined in the IdP's SAML configuration, governed by the NameID Policy Format and Principal Type settings. You do not need to create a mapper for the username field unless you need to override the default NameID assertion.

Entra ID Assertion Names​

If you are using Entra ID (formerly Azure AD), the default assertion names are:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Add User Data Mappers with Profile Mapping​

The Platform provides a streamlined Profile Mapping feature that simplifies creating and managing the mappers required for user provisioning. This feature reduces the effort required when connecting your IdP to the Platform.

  1. From the Mappers page, click the dropdown arrow next to Add, and choose Profile mapping.
  2. In the Profile Mapping modal, map non-standard claim or assertion keys from your IdP to the standard attribute names expected by the Platform.

Example: If your IdP sends the email address using the key email_address, enter email_address in the email field. When your IdP sends a claim such as email_address: john@example.com, the mapper translates it into the format understood by the Platform: email: john@example.com.

  1. Configure mappings for the required user attributes:
    • Email - Enter the claim/assertion key your IdP uses for email addresses
    • First Name - Enter the claim/assertion key your IdP uses for first names
    • Last Name - Enter the claim/assertion key your IdP uses for last names
    • Username - Enter the claim/assertion key your IdP uses for usernames (if applicable)
  2. Click Save or Add to create the mappers.

Using this feature, you can quickly configure all required mappers to support automatic user creation and profile population. All generated mappers can be edited or deleted individually or collectively.

note

Not all profile mappers are required. When using OIDC, mappers are unnecessary if your IdP already follows standard OIDC token claim naming conventions.

note

A warning message is displayed when the IdP configuration does not have required mappers for user provisioning. This warning can be disregarded if your IdP is an OIDC IdP and follows the standard naming conventions.

Add User Data Mappers Manually​

You can also create user data mappers individually using the manual method:

  1. From the Mappers page, click the dropdown arrow next to Add, and choose Mapper.
  2. In the Add mapper window, configure the following fields:
    • Name - Enter a descriptive identifier for the mapper (e.g., First Name Mapper)
    • Sync Mode - Controls whether updates to user attributes in your IdP will update the Platform. It is recommended to use INHERIT:
      • FORCE - Always updates the Platform user when there is a change in your IdP
      • IMPORT - Never updates the Platform user after initial creation, regardless of IdP changes
      • INHERIT - Uses the value configured on the Advanced config page of this IdP connection
    • Mapper Type - Set to Attribute Importer
    • Claim (OIDC only) - The name of the claim as specified by your IdP
    • Attribute Name (SAML only) - The name of the assertion as specified in your IdP's SAML token. You can add the name in either Attribute Name or Friendly Name (at least one field is required)
    • User Attribute Name - The Platform user attribute to map to: username, email, firstName, or lastName
  3. Click Add Mapper.
  4. Repeat for any additional mappers.

Example Scenario​

Problem: An IdP sends SAML assertions with the following attribute names:

  • first_name for the user's first name
  • surname for the user's last name
  • emailAddress for the user's email

Solution: Configure mappers as follows:

  • Map first_name to firstName
  • Map surname to lastName
  • Map emailAddress to email

The username will automatically be extracted from the NameID attribute based on the configured NameID Policy Format or Principal Type.

Map User Group Assignments​

Group mappers enable users to inherit group assignments from your IdP in the Platform. This is important for bridging the gap between your IdP and Digital.ai products, allowing users to be automatically assigned appropriate roles in each product.

Prerequisites for Group Mapping​

Before creating group mappers:

  1. Add any groups you want to map in the Platform. For more information, see User Groups.
  2. Enable Sync with IdP for each group.
  3. Ensure group names in the Platform match exactly the group names sent from the IdP.
note

For Azure AD / Entra ID, only Group IDs are sent, so group names in the Platform must be the Group IDs from your IdP.

Create a Group Mapper​

You only need to create one mapper to enable group synchronization. This mapper identifies which claim from your IdP contains the user's group memberships.

  1. From the Mappers page, click the dropdown arrow next to Add, and choose Group mapping.
  2. In Claim, enter the name of the group claim from your IdP.
  3. Click Add mapper.

Group Mapping Workflow​

When a user logs into the Platform via their IdP:

  1. The Platform checks the token from the IdP for groups (using the claim/assertion defined in your Group Mapper)
  2. The Platform places the user in any groups that have a name matching the groups sent from the IdP if Sync with IdP is set to True for the group

Map User Roles​

Role mappers allow you to automatically assign Platform roles based on user attributes or group memberships in your IdP. This enables organizations to manage user roles centrally in their corporate IdP and have those roles correctly translate into Platform permissions.

note

Role mapping only affects the user's role in the Platform itself and does not impact users or permissions in individual products.

Available Platform Roles​

The following roles can be assigned through mappers:

  • account-admin - Grants full administrative access to the account. Users can manage users and roles, configure account settings, and perform high-level administrative tasks across all applications.
  • account-analytics-author - Provides access to analytics dashboards and the ability to create or modify reports.
  • account-application-admin - Provides admin-level access to manage applications under the account.
  • account-service - A special service-level role used for automated systems or backend services. Users can authenticate as service accounts and access APIs or services as per assigned scopes.
  • account-user - The default role for regular users. Users can log in to the system, access features and services permitted by the account's policy, and view their own data or perform user-level tasks.
info

By default, any users created when logging into the Platform via an IdP are assigned the account-user role.

Create a Role Mapper​

To assign Platform roles based on IdP groups:

  1. On the Mappers page, click the Add dropdown and select Mapper.
  2. In Name, enter a descriptive identifier (e.g., allAdmins mapper).
  3. Leave Sync Mode as INHERIT.
  4. In Mapper Type, choose Advanced Claim to Role.
  5. In New Key, enter the claim name that contains group information from your IdP (commonly groups). The value for New Key is not constant and depends on what your IdP sends. Verify the claim name used by your IdP.
  6. In New Value, enter the name of the group from the IdP (e.g., allAdmins).
  7. In Select Role, choose the Platform role that users in this group should receive (e.g., account-admin).
  8. Click Add mapper.
  9. Repeat these steps for each group you want to map to a role.

Example: Map Admin Group to Admin Role​

Scenario: Your IdP has a group called System Administrator, and you want users in this group to have the account-admin role in the Platform.

Configuration:

  • Name: System Admin Role Mapper
  • Mapper Type: Advanced Claim to Role
  • New Key: groups
  • New Value: System Administrator
  • Select Role: account-admin

Once configured, users signing in through the IdP who have the System Administrator role will automatically be assigned the account-admin role in the Platform.

Last updated on