Map User Attributes

Identity provider 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.

Profile Mappers

The Platform requires first name, last name, email address, and username to create a user. Profile Mapping is the recommended way to configure the mappers that provide this data, for both OIDC and SAML identity providers, via a single guided form in the UI.

OIDC User Data Mapping (optional)

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, preferred_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 (required)

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.

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)

Handle the 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.

Create Profile Mappers

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.

3. 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)
4. 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.

Advanced Mapper Usage

For cases the Profile Mapping feature doesn't cover — mapping user data manually, synchronizing group memberships, or assigning roles — configure mappers directly using the Mapper option on the Mappers page.

Manually Map User Data

warning

It is strongly recommended to use the Profile Mapping method described above to add user data mappers. Use caution when adding these mappers manually.

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

For the email, firstName, and lastName user attributes, use the Attribute Importer mapper type.

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: email, firstName, or lastName
3. Click Add Mapper.
4. Repeat for any additional mappers.

If you need to override the default username behavior, use a Username Template Importer mapper for the username attribute.

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., Username 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 Username Template Importer
   • Template - Template that controls how the username value gets formatted. Replace user_data in the following template with the appropriate assertion/claim depending on your IdP type.
     • For SAML set to: ${ATTRIBUTE.user_data | lowercase}
     • For OIDC set to: ${CLAIM.user_data | lowercase}
   • Target - (Readonly) Leave as LOCAL.
3. Click Add Mapper.

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. The Platform never creates groups for you from your IdP, so every group you want to map must exist here first. For more information, see Where User Groups Come From.
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

You can assign any of the five Platform roles through a mapper: account-admin, account-application-admin, account-analytics-author, account-user, and account-service. For what each role grants, see User Roles and Permissions.

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 the appropriate type for your IdP protocol:
   • OIDC — choose Advanced Claim to Role
   • SAML — choose Advanced Attribute to Role
5. In New Key, enter the name of the claim or assertion 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 or assertion 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.

OIDC configuration:

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

SAML configuration:

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

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

Mapper Type Reference

Identity provider mapper types define how the Platform reads, transforms, and applies data from your IdP's token during login. This section is a reference for every mapper type available when configuring a mapper manually.

Common Fields

The following fields appear on every mapper regardless of type:

Field	Description
Name	A unique identifier for this mapper within the IdP configuration. Cannot be changed after creation.
Sync Mode	Controls when the Platform re-evaluates and applies this mapper for a user. See options below.
Mapper Type	Selects the mapper type. Locked after creation.

Sync Mode Options

Value	Behavior
INHERIT	Uses the sync mode configured on the IdP's Advanced Config page. Recommended default.
IMPORT	Applies the mapper only the first time a user logs in. Subsequent logins do not update the mapped value.
FORCE	Re-applies the mapper on every login, updating the mapped value if the IdP data has changed.

---

SAML Mapper Types

Advanced Attribute to Group

Maps users into Platform groups based on the value of a SAML assertion. When a user logs in, the Platform reads the specified assertion from the SAML token and assigns the user to the corresponding Platform group if one matches.

Field	Description
Attribute	The name of the SAML assertion that carries group membership information (for example: groups).
Regex Imported Groups	When enabled, the "Group to Import" values are treated as Java regular expressions matched against assertion values, instead of requiring an exact string match.
Group to Import	The group name (or Java regex pattern) as sent by the IdP in the assertion. Part of each Group Mapping pair.
Target Group	The Platform group the user will be placed into when the assertion value matches. Part of each Group Mapping pair.

---

Advanced Attribute to Role

Assigns a Platform role to a user when a set of SAML assertions from the IdP all match specified values. All attribute/value pairs must match simultaneously. Useful when role assignment depends on multiple conditions being true at once.

Field	Description
Regex Attribute Values	When enabled, assertion values in the Attributes list are treated as Java regular expressions.
Attributes	One or more key/value pairs where the key is the SAML assertion name and the value the assertion must contain for the role to be assigned. All pairs must match.
Select Role	The Platform role to grant when all attribute conditions are satisfied.

---

SAML Attribute to Role

Assigns a Platform role when a specific SAML assertion has a specific value. A simpler alternative to Advanced Attribute to Role when only a single assertion needs to be checked.

Field	Description
Attribute Name	The name of the SAML assertion as defined in the IdP's SAML token (for example: http://schemas.microsoft.com/ws/2008/06/identity/claims/role). At least one of Attribute Name or Friendly Name is required.
Friendly Name	An optional human-readable alias for the assertion name. At least one of Attribute Name or Friendly Name is required.
Attribute Value	The value the assertion must contain for the role to be assigned.
Select Role	The Platform role to grant when the assertion matches.

---

OIDC Mapper Types

Advanced Claim to Group

Maps users into Platform groups based on OIDC claim values. When a user logs in, the Platform reads the specified claim from the token and assigns the user to the matching Platform group.

Field	Description
Claim	The name of the OIDC claim that carries group membership information (for example: groups).
Regex Imported Groups	When enabled, the "Group to Import" values are treated as Java regular expressions matched against claim values, instead of requiring an exact string match.
Group to Import	The group name (or Java regex pattern) as sent by the IdP in the claim. Part of each Group Mapping pair.
Target Group	The Platform group the user will be placed into when the claim value matches. Part of each Group Mapping pair.

---

Advanced Claim to Role

Assigns a Platform role to a user when a set of OIDC claims from the IdP all match specified values. All claim/value pairs must match simultaneously. Useful when role assignment depends on multiple conditions being true at once.

Field	Description
Regex Claim Values	When enabled, claim values in the Claims list are treated as Java regular expressions.
Claims	One or more key/value pairs where the key is the OIDC claim name and the value the claim must contain for the role to be assigned. All pairs must match.
Select Role	The Platform role to grant when all claim conditions are satisfied.

---

Claim to Role

Assigns a Platform role when a specific OIDC claim has a specific value. A simpler alternative to Advanced Claim to Role when only a single claim needs to be checked.

Field	Description
Claim	The name of the OIDC claim to evaluate (for example: groups).
Claim Value	The value the claim must contain for the role to be assigned.
Select Role	The Platform role to grant when the claim matches.

---

SAML and OIDC Mapper Types

Attribute Importer

Reads a value from the IdP token and maps it into a standard Platform user attribute. Used to bridge non-standard claim or assertion names to the fields the Platform expects when creating or updating a user. The SAML variant reads from SAML assertions; the OIDC variant reads from JWT claims.

OIDC - (Optional) Only add this mapper for OIDC IdPs if the Platform's default behavior for deriving email, firstName, and lastName from the IdP token is not desirable for your use case.

Default Behavior:

• firstName is set from the given_name claim.*
• lastName is set from the family_name claim.*
• email is set from the email claim.

*If both given_name and family_name are absent, the name claim is split on its last space instead: everything before the last space becomes firstName, and everything after becomes lastName (if name contains no space, the entire value becomes firstName and lastName is left unset).

SAML - (Required) SAML IdPs have no default behavior for these attributes — SAML assertion names are not standardized — so an Attribute Importer mapper must be defined for all three attributes when configuring a SAML IdP.

This mapper should not be used to set the username attribute — use the Username Template Importer instead.

OIDC fields:

Field	Description
Claim	The name of the OIDC claim to read the value from.
User Attribute Name	The Platform user attribute to map to: email, firstName, or lastName.

SAML fields:

Field	Description
Attribute Name	The name of the SAML assertion to read the value from. At least one of Attribute Name or Friendly Name is required.
Friendly Name	An optional human-readable alias for the assertion name. At least one of Attribute Name or Friendly Name is required.
User Attribute Name	The Platform user attribute to map to: email, firstName, or lastName.

---

Username Template Importer

This is the mapper to use for setting the username. Only add this mapper if the Platform's default behavior for deriving a username from the IdP token is not desirable for your use case.

By default, with no username mapper configured, the Platform derives the username as follows:

• OIDC — the username is set from the preferred_username claim. If that claim is absent, the email claim is used instead; if email is also absent, the token's sub (subject identifier) claim is used.
• SAML — the username is set based on the IdP's Principal Type setting: SUBJECT (the default) uses the SAML assertion's NameID value, ATTRIBUTE uses the value of a SAML attribute matched by attribute name, and FRIENDLY_ATTRIBUTE uses the value of a SAML attribute matched by friendly name.

The Username Template Importer sets the username by applying a template expression that can reference claims or assertions from the IdP token. It also provides an important safeguard: if a referenced claim or assertion is absent or null, its substitution resolves to an empty string rather than propagating null, so the template always produces a result and an existing username is never erased. The Attribute Importer does not have this safeguard — if the referenced claim is absent when mapping to username, it will overwrite the existing username with an empty value. Transformations are optional and independent of this safeguard.

Field	Description
Template	A template string defining how the username is constructed. Substitutions are enclosed in ${}. The available substitution variables are listed below. An optional transformation can be appended after a | pipe character. The available transformations are: lowercase (converts the value to lower case), uppercase (converts the value to upper case), and localpart (extracts the portion of the value before the @ symbol — if @ is not present the value is left unchanged). Multiple substitutions can be combined in a single template, e.g. ${ALIAS}.${CLAIM.preferred_username | lowercase}. Substitution variables (OIDC): ALIAS — the alias of the identity provider as configured in Platform. UUID — a randomly generated UUID, unique per login. CLAIM.<name> — the value of the named claim from the OIDC token (e.g. CLAIM.sub, CLAIM.email). Substitution variables (SAML): ALIAS — the alias of the identity provider as configured in Platform. UUID — a randomly generated UUID, unique per login. NAMEID — the SAML NameID value from the assertion subject. ATTRIBUTE.<name> — the value of the named SAML assertion, matched against both the attribute name and the friendly name (e.g. ATTRIBUTE.email, ATTRIBUTE.groups).
Target	Read-only. Always set to LOCAL, meaning the derived username is written to the Platform's local user database.

---

Hardcoded Role

Assigns a fixed Platform role to every user who authenticates through this IdP, regardless of any claim or assertion values in their token. Useful when all users from a given IdP should receive the same role unconditionally.

Field	Description
Select Role	The Platform role that will be assigned to every user authenticating through this IdP.

---

Hardcoded Attribute

Sets a fixed value on a custom Platform user attribute for every user who authenticates through this IdP, regardless of what the IdP sends. This mapper is intended for custom attributes only — do not use it to set standard user attributes such as email, firstName, lastName, or username. For those, use the Attribute Importer or Username Template Importer instead. A common use case is stamping a static marker on all users from a specific IdP (e.g. setting a source attribute to okta-prod).

Field	Description
User Attribute	The name of the custom Platform user attribute to set.
User Attribute Value	The fixed value to set on the attribute for every user authenticating through this IdP.