The User Merge Flow exists to handle changes in user identification, such as when you have a local user who signs in via an IDP for the first time or during migration from one IDP to another. You enter the User Merge Flow when the system detects a change in your identification method. This flow attempts to link the users into a single user even though the login method may have changed.

note

A user may enter the User Merge Flow regardless of whether their Identity Provider uses OIDC or SAML. For instance, a company may have initially configured a SAML Identity Provider and later switched to an OIDC Identity Provider (or the other way around).

Scenarios That Trigger the User Merge Flow

This section includes scenarios where the user merge flow is triggered, as well as scenarios where the user merge flow is not applicable.

Supported Scenarios

• Logging in via an Identity Provider when a local user exists with the same email.
  • This scenario usually occurs during the initial account setup, where account-admins first create a local user to configure Single Sign-On (SSO).
• Logging in via a new Identity Provider after previously logging in through a different one (using the same email)
  • This typically happens when migrating to a new identity provider.
• The user's information has been updated, for example, a change in their last name.

Unsupported Scenarios

• Modifying the NameID Format Policy of a SAML Identity Provider can result in the user being recognized as a new user (refer to Common Problems below).
  • This usually occurs when the configuration of an active (in-use) Identity Provider is modified.
  • This will cause an error when the user selects Add to existing account as shown in the figure below.

Steps after user starts the User Merge Flow

1. When the User Merge Flow is triggered, the user will be presented with a screen displaying the options Review Profile and Add to existing account.

2. Review Profile option takes the user to a page displaying their updated information. This step is optional and allows the user to verify their details before linking their account.

note

After logging in, the user's First Name and Last Name are updated to reflect the information shown here. However, the Username remains unchanged.

• Click Submit to navigate back to the previous page.

3. The Add to Existing Account option will direct the user to the next page, where they will be prompted to verify their email address.

4. The user must check their inbox for an email from Digital.ai to confirm the merge. If the email does not arrive, they can use the provided link in step 3 to resend the confirmation email.

The following is an example of the email the user will receive:

Once the user clicks the Link my accounts button in the received email, they will automatically be logged in.

Known Issues and Their Resolution

1. Incomplete Information during the User Merge Flow (e.g., Missing First Name or Last Name).

• If the Identity Provider is misconfigured, Digital.ai may be unable to accurately populate the user's information. In such cases, the user will be directed to the Review Profile page at the beginning of the flow and will be required to complete any missing fields before continuing:

• This is typically an indication that the necessary mappers have not been set up on the Identity Provider, so Digital.ai is unable to determine the source of the missing field information.

Solution

Review the Identity Provider configuration and ensure that the mappers are correctly referencing the appropriate attributes or assertions sent by the Identity Provider. For more information on how to setup mappers check Map User Data

2. Modifying the NameID Format Policy for a SAML Identity Provider

• For SAML Identity Providers, the NameID Format Policy determines which attribute uniquely identifies the user. If this setting is changed for an Identity Provider currently in use, the Platform may treat existing users as new users and trigger the User Merge Flow. This process will fail, and the user will encounter the following message:

Solution

Reverting the change to the NameID Format Policy field will resolve the issue. If reverting is not an option, deleting the affected users from the Platform and having them log in again will also resolve the problem.