Next Identity Adopt provides efficient methods for migrating users from a legacy directory to a new home directory. You can choose from the following migration options:

Bulk Migration: Migrate all your users simultaneously.
Just-in-Time Migration (JIT): Migrate users as they log in.

Bulk Migration

📘
About bulk migration
Contact your Next Identity Solutions Architect to discuss migrating all your users, whether you have hundreds or millions of them, from your legacy directory to the new directory. You can choose to maintain passwords for a seamless migration experience, or reset passwords and send password reset emails or SMS to all users.

Just-In-Time Migration

📘
Just-in-time migration terminology
Local IDP: Next Identity IDP
Home IDP: External IDP (e.g., third-party IDP like Salesforce or a homegrown IDP)
externalSystemsMapping: An object in the NI record that stores the home user ID and IDP information, marking the user as migrated.

Next Identity Adopt's Just-in-Time migration feature takes an incremental approach to data migration. Instead of completing the entire migration in a short time frame, Just-in-Time migration runs the old and new systems in parallel, migrating data as users authenticate. This can be achieved by allowing the home IDP to interact with the local IDP through an API or by providing a managed interface for connecting to the home IDP.

JIT migration also adds a flag in the user record to indicate the home IDP of the consumer. One of the benefits of JIT migration is that the home IDP password hash doesn't need to be supported since the user's password can be validated with the home IDP and stored in the local IDP using the native hash. JIT migration accounts for various scenarios, including users who have already been migrated and exist in a second home IDP, as well as merging flows for users who already exist in the local IDP.

JIT migration is initiated for clients with enabled JIT migration and a configured home IDP. It now checks for the presence or absence of the correct external system ID, rather than just any external system ID.

Migration Preference

If your application requires user migration, we recommend following this order. Please note that this process is manual and not automated or configured below.

Bulk migration
Password reset
Just In Time Migration (JIT)
Just In Time Migration (JIT) API

Just-in-Time Migration Overview

Here's the workflow for just-in-time migration:

The end user visits the website or app and is prompted to sign in using their home IDP credentials.
The end user's credentials are used to check if the record exists and matches in both the home IDP and local IDP.
Based on the results of the checks, either a new user record will be created in the local IDP, or an existing record in the local IDP will be updated.

When a record exists in both the local IDP and the home IDP, a check is performed to see if the key user attributes are the same or different. The user may be prompted to choose a "primary" set of data to be written into the local IDP, which is known as a merge workflow. The details of both the Journeys and API flows are provided below.

Note: The JITm feature is only available for clients with email and password login.

External ID Providers Storage

The external systems mapping object is used to determine whether the user has been migrated, indicate the source of the migration, and store the user's external UUID. This object can store multiple external system IDs, allowing for tracking of users across different systems. Additionally, the migration type is stored in the external system mapping. This type can be 'Migrated', 'Updated', or 'Sustained'. Analyzing and understanding the events that occurred during the migration process is crucial.

Example

   "external_systems_mapping": {
        "app1_cognito": { //unique id of source
            "name": "App 1", //human friendly name ID source? 
            "user_id": "b12889c5-1080-641f-db98-6e6304a704e1", //user's external ID
            "created": "[TIMESTAMP]"
        }
    },

The key ID field is a unique identifier of the external IDP. It is a human-readable unique ID, and uniqueness is important when multiple external IDPs are on the same platform. The suggested format is as follows:

appname_idpname

Example:

loyaltybrand_cognito

someapp_salesforce

newssource_cognito (this is a different Cognito than the first example)

Migration Directions

The migration can occur in either direction. An external provider (system) can utilize the JIT API to facilitate migrating from the home IDP to the local IDP. Conversely, Next Identity supports integrations with external providers to seamlessly migrate consumers with just a few simple configurations.

Supported Home IDP Systems

As of the current implementation, our system can connect with Cognito and Keycloak IDP systems when used as Home IDP. However, we have the flexibility to create new connectors for other IDPs if required in the future.

📘
Note on values validation
All values are validated based on regex for input fields.
If the code (auth code) is not present and an account already exists in the local system, merge criteria will begin as described below. Note that some scenarios result in the code being required for this call.

JIT Logical Flows v2

API

Scenario 1: Migration from an external system to local IDP via API

Entrance criteria: JIT migration is enabled for the property.

Start: The user enters username and password on the login screen, and the external system calls the /user/v1/jit-migration endpoint.

If the user exists in the Local IDP and externalSystemsMapping is set but does not match the current application's external system ID, the JIT flow is triggered.
- If the user exists in the local system and externalSystemsMapping is set but does not match the current application's external system ID, the JIT flow is triggered.
- If the credentials are correct, the standard logic process continues, resulting in an auth code. [end]
- If the credentials are incorrect:
  - If it's the first time logging in since JIT migration, the user is shown a message and an email is triggered to inform them which credentials to use. [end]
  - Otherwise, respond with an invalid credentials message as per standard practice. [end]
If the user exists in the local system and externalSystemsMapping is NOT set, the home IDP is called, and credentials are verified.
- If the credentials are invalid, the API responds with an invalid credentials message. [end]
- If the credentials are valid:
  - If the user is verified in the home IDP:
    - If the user is verified in the local IDP, the response indicates that the user has an existing account to log into. [end]
    - If the user is NOT verified in the local IDP, the password passed in is set in the local IDP, and the system responds with a message and an auth code. [end]
  - If the user is NOT verified in the home IDP:
    - If the user is verified in the local IDP, the response indicates that the user has an existing account to log into. [end]
    - If the user is NOT verified in the local IDP, the password passed in is set in the local IDP, and the user is informed that their account needs to be verified. [end]
If the user does not exist in the local system, the home IDP is called, and credentials are verified.
- If the credentials are invalid, the API responds with an invalid credentials message. [end]
- If the credentials are valid, the user details are migrated, and an account is created in the local IDP.
  - If the user was verified in the home IDP, the login proceeds and completes with an auth code. [end]
  - If the user is not verified in the home IDP, the user is informed that the migration happened and needs to verify their account. [end]

Scenario 2: Migration from an external system to local IDP where the external system uses Next Identity Journeys.

Entrance criteria: The client has a home IDP realm configured, and JIT enabled. The user is logging into the hosted login screen.

Start: User lookup in the local IDP.

If the user exists in the local IDP and externalSystemsMapping is set but does not match the current application's external system ID, the JIT flow is triggered.
- If the user exists in the local IDP and externalSystemsMapping is set but does not match the current application's external system ID, the JIT flow is triggered.
- If externalSystemsMapping exists and indicates that a user merge has occurred, credentials are verified only in the local IDP. [end]
- If externalSystemsMapping doesn't exist, the home IDP is checked.
  - If the user exists in the home IDP, credentials are verified against the home IDP, and the credentials and user details are compared with the local IDP.
    - If the password and user details match (email, firstname, and lastname must all match) in the local IDP, externalSystemsMapping is set, and the end-user experience remains seamless in this use case. [end]
    - If the user details match (email, firstname, and lastname must all match), but the password does not match:
      - If the client configuration is set to automated merge, the user is shown a screen where they can use their local IDP credentials to log in and externalSystemsMapping is set. [end]
      - If the client configuration is set to user-driven merge, the user receives a message: "You have an existing account with . Please enter those credentials to make it your primary account." Then, the user is prompted to enter their local IDP credentials. Upon validation, externalSystemsMapping is set. [end]
    - If the email matches but the first or last name does not match (both must match), the user is prompted to choose an account as the primary account.
      - If the user chooses the local IDP as the default:
        
        If the user credentials do not match, they are prompted to enter their local IDP credentials. The credentials are verified, and the credentials from the home IDP are not migrated, and user details are not migrated to the local IDP. externalSystemsMapping is set. [end]
        
        If the user credentials match, the credentials from the home IDP are not migrated, and user details are not migrated to the local IDP. externalSystemsMapping is set. [end]
      - If the user chooses the home IDP as the default, the user credentials and user info are migrated to the local IDP, and externalSystemsMapping is set. [end]
    - If the user credentials fail against the home IDP (either the password is incorrect or they do not have an account - the local IDP will not know the difference), the user's credentials are checked against the local IDP. [end]
  - If the user doesn't exist in the local IDP, the home IDP is checked.
    - If the user's credentials are checked with the home IDP and successful, the user is migrated, and externalSystemsMapping is set. [end]
    - If the user's credentials are checked against the home IDP and fail, the user is shown a username/password error since they don't exist anywhere and need to register. [end]

Exit criteria assumptions:

If the user exists in a second home IDP and has already been migrated, the system will now check the external system ID. If it doesn't match the current application's ID, the JIT flow will be triggered.
If the user is being migrated and does not have a verified account, they will be required to verify it before they can authenticate.
If a user who is being migrated already has an existing entry for the home IDP, the migration will not continue, and the failed event will be clearly logged.

Supported External Identity Providers

External Systems API

Users who are logging into a new application and have not granted access will be prompted to accept. Once the consumer is authenticated, the application needs to be able to map the user to an external system ID. This mapping may happen automatically based on whether the client has JIT configured. If the client doesn't have JIT configured, the app needs a way to set this value manually. Therefore, an endpoint is required to update the externalSystemsMapping array in the NI user record.

The API accepts a bearer token (from token delegation).
The API provides GET, POST, and DELETE functions to retrieve the list of external IDs, create a new one, and delete one.
The API can only access the external system(s) that the client has access to. This is handled by checking the client setting to get the external system ID and then checking the user record, allowing access only to that specific entry.
If a POST is called and the system ID already exists, the API responds with a failure to update a duplicate entry message. This should be clearly logged for future reference if needed.

For more information, refer to the External System API reference.