Skip to main content

Map User Data

Your identity provider shares information about your users with Digital.ai in the form of key/value pairs (known as claims or assertions, depending on the IdP), and the Platform uses this data to create users in our system.

Platform administrators can use attribute mappers to ensure that user data from your IdP is properly understood by the Digital.ai Platform.

note

The Platform requires first name, last name, email address, and username to create a user. You don't need mappers for any other data.

tip

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

When to Use Mappers​

Mappers are used within the Digital.ai Identity service which allows integration between a customer’s Identity Provider (IdP) and the Digital.ai Platform. They serve as a bridge to translate the claims or attributes sent by the IdP into corresponding fields within a user profile in the Digital.ai Identity service

note

Claims are pieces of information (attributes) about a user provided by the IdP. Examples include email addresses, usernames, roles, or custom-defined attributes such as department or region. These attributes are typically sent in the form of SAML assertions, OIDC tokens, or similar protocols used by the IdP during authentication.

OIDC​

Mappers may be optional for OIDC connections.

Whether or not you need to use mappers to handle this data is entirely dependent on your organization's unique situation, and in general the Digital.ai Platform expects to receive user attributes based on the set of standard claims as defined by OpenID. You can view the list of standard claims here: 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 on the Digital.ai side. If this data is being sent in other claims, a mapper will be needed to map the claim name used by the customer to correct field on the Digital.ai side.

For example, if your IdP uses the standard claim email: john@example.com, the Platform will automatically map that to the Platform email user attribute.

However, if your IdP uses a claim called "email_address": john@example.com, then you would need to create a mapper to correctly get that data into the Platform email user attribute. See below for an example of how to map email_address to email:

Example Mapper: Mapper Type: The type of mapper, for mapping user data you should always use Attribute Importer Claim: The name of the claim in the customer’s token User Attribute Name: The user attribute in Digital.ai that you are mapping to. This can be firstName, lastName, username or email.

SAML​

Unlike OpenID Connect (OIDC), the SAML protocol does not follow standard naming conventions for the attributes it stores. These attributes, referred to as assertions in SAML tokens, can vary significantly across different Identity Providers (IdPs). This lack of standardization necessitates the use of mappers for SAML connections to ensure the Platform can correctly interpret the data provided by the IdP.

Why Mappers Are Required for SAML Connections​

Each IdP defines the names of its assertions differently. For example, one IdP might use givenName for a user's first name, while another might use first_name. Without mappers, the Platform would not be able to recognize or use these attributes effectively.

To address this, you need to configure mappers to align the IdP’s assertion names with the corresponding fields in the Digital.ai Identity service. By explicitly mapping these attributes, you ensure the Platform can accurately understand and process the user data.

Essential Mappers for SAML Connections​

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

  • First Name : Map the IdP’s attribute that represents the user’s first name (e.g., givenName, first_name, etc.).

  • Last Name : Map the IdP’s attribute for the user’s last name (e.g., surname, last_name, etc.).

  • Email : Map the IdP’s attribute for the user’s email address (e.g., email, emailAddress, etc.).

Handling Username Data​

The username field is treated differently in SAML connections. By default, the username is derived from the NameID attribute, which is defined in the IdP's SAML configuration. This behavior is governed by the following settings:

  • NameID Policy Format
  • Principal Type

You do not need to create a mapper for the username field unless you need to override the default NameID assertion. If an override is required, you can configure the mapper accordingly.

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 in the Digital.ai Identity service as follows:

  • Map first_name to the firstName field.
  • Map surname to the lastName field.
  • Map emailAddress to the email field.

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

By carefully setting up mappers for SAML connections, you ensure that the Digital.ai Platform can process user data accurately, providing a integration experience with the IdP.

Entra ID Assertion Names​

If you are using Entra ID the default assertion names are as follows:

  • 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

User Group Mappers​

You can also use mappers if you want users to inherit group assignments from your IdP in the Platform or Digital.ai applications. To learn more about mapping group data, see Map User Group Assignments.

Add or Edit Mappers​

You can add mappers during the initial IdP configuration process, or at any time after you've already established the connection by returning to edit the identity provider.

  1. Log in to the Platform as an administrator.
  2. In the left navigation, under SSO, click Identity providers.
  3. Find the SSO connection you want to modify and click the Edit icon under Actions.
  4. Click Next until you get to the Mappers page.
  5. Click the Add drop-down arrow, and select Mapper.
  6. In the Add mapper window, set the following fields:
    1. Name is merely a way to identify the mapper. Enter something like First Name Mapper.
    2. Sync Mode controls whether an update to a user attribute in your IdP will cause an update in the Platform. You are suggested to use INHERIT.
      • FORCE always updates the Platform user when there is a change in your IdP.
      • IMPORT never updates the Platform user after they are created the first time, regardless of changes in your IdP.
      • INHERIT uses the value that has been configured on the Advanced config page of this IdP connection.
    3. Mapper Type should be set to Attribute Importer.
    4. (For OIDC providers only) Claim is the name of the claim as specified by your IdP.
    5. User Attribute Name is the Platform user attribute that the data will be mapped to. This should be set to username, email, firstName, or lastName depending on the data you're mapping.
    6. (For SAML providers only) Attribute name is 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 (you must complete at least one of the fields, but you do not need to complete both).
  7. Click Add Mapper.
  8. Repeat step 6 for any additional mappers.
Last updated on