Next Identity Adopt offers the following methods of migrating users from a legacy directory to a new home director:

Bulk Migration

📘

About bulk migration

Your Next Identity Solutions Architect can discuss options for migrating all of your users—whether it's hundreds or millions—from your legacy directory to your new directory. If passwords are included, they can either be maintained to provide a seamless migration experience for users, or they can be reset and all users will be sent password reset emails or SMS.

Just-In-Time Migration

📘

Just-in-time migration terminology

local IDP - Next Identity IDP
home IDP - external IDP (ex. third party IDP such as salesforce or a homegrown IDP)
externalSystemsMapping - object in NI record that stores home user ID and IDP and marks user as migrated

Next Identity Adopt'sJust-in-Time migration feature take an incremental approach to migrating data. Rather than aim to complete the whole event in a short time window, a Just In Time migration (also sometimes referred to as trickle migration or lazy migration) involves running the old and new systems in parallel and migrating the data as the consumer authenticates. This approach can be completed either by allowing a home IDP to interact with the local IDP via API, or by providing connection to the home IDP through a managed interface.

JIT migration also creates a flag in the user record to indicate where the home IDP of the consumer is - amongst other use cases. One of the benefits of JIT migration is that the home IDP password hash doesn’t have 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. There are various scenarios that need to be accounted for with JIT migration, including a user who has already been migrated and exists in a second home IDP or if a user already exists in the local IDP (merge flow).

JIT migration will be initiated for clients that have it enabled and have a home IDP configured, only one (1) home IDP is supported at a time.

Migration Preference

If your application needs to perform a user migration, the following list is the order that we recommend. Note, this is a process, it is not automated or configured below.

1. Bulk migration

2. Password reset

3. Just In Time Migration (JIT)

4. Just In Time Migration (JIT) API

Just-in-Time Migration Overview

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

1. The end user visits the website or app and is prompted to sign in with the home IDP credentials.
2. End user credentials are used to check if the record exists and matches in the home IDP and/or local IDP.
3. Depending on the results of those two 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 will happen to see if the key user attributes are the same, or different, and the user may be prompted to choose a “primary” set of data to be written into the local IDP (also known as a merge workflow). Details of both the Journeys and API flows are below.

External ID Providers Storage

The external systems mapping object is stored and is a place to determine whether the user has been migrated or not, marks where the user was migrated from, and saves the user’s external UUID. This is an object since there can be more than one external provider.

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 - uniqueness is important since there can be more than 1 external IDP that are the same platform. Suggested format:

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 the migration from home to local IDP. Conversely, Next Identity supports integrations into external providers in order to seamlessly migration consumers with only a few simple configurations.

📘

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 external system to local IDP via API

Entrance criteria: JIT migration enabled for the property.

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

• if user exists in the local system and externalSystemMapping is set credentials are checked against local IDP
  • If credentials are correct, logic process continues as standard resulting in auth code [end]
  • If credentials are incorrect
    • If it's the first time logging in since JIT migration, user is shown a message and an email is triggered to inform them of which credentials to use [end]
    • else, respond with invalid credentials message per standard [end]
• if user exists in local system and externalSystemsMapping is NOT set, home IDP is called and credentials are verified
  • If credentials are not valid, API response with invalid credentials [end]
  • If credentials are valid
    • If user is verified in home IDP
      • If user is verified in local IDP response is that the user has an existing account that they can log into. [end]
      • If user is not verified in local IDP, the password that was passed in is set in local IDP, system responds with message and auth code [end]
    • If user is NOT verified in home IDP
      • If user is verified in local IDP response is that the user has an existing account that they can log into. [end]
      • If user is not verified in local IDP, set password in local IDP with the one that was passed in and inform user that account needs to be verified. [end]
• If user does not exist in local system, home IDP is called and credentials are verified
  • If credentials are not valid, API response with invalid credentials [end]
  • If credentials are valid, user details are migrated and account is created in local IDP
    • If user was verified in home IDP, login proceeds and completes with auth code [end]
    • If user is not verified in home IDP, user is informed that migration happened and to verify their account [end]

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

Entrance criteria: Client has home IDP realm configured and JIT enabled. User is logging into hosted login screen.

Start: User lookup in local IDP

• if user exists in local IDP, externalSystemsMapping is checked
  • if externalSystemsMapping exists and indicates user merge has occurred, credentials are verified only in local IDP [end]
  • if externalSystemsMapping doesn't exist, home IDP is checked
    • if user exists in home IDP, credentials are verified against home IDP, credentials and user details are compared with local IDP
      • if password and user details match (email, firstname, and lastname all must match) in local IDP, externalSystemsMapping is set, end-user experience is not impacted in this use case and sign in appears seamless [end]
      • if user details match (email, firstname, and lastname all must match), but password does not match
        • if client configuration is set to automated merge, the user is shown a screen that they can use their local IDP to login, externalSystemsMapping is set [end]
        • if client configuration is set to user driven merge, user gets 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 email matches but first or last name do not match (both must match), user is prompted to choose an account as primary
        • if user chooses local IDP as default
          • If user credentials did not match, user is prompted to enter local IDP credentials, credentials are verified, credentials from home IDP are not migrated and user details are not migrated to local IDP and externalSystemsMapping is set [end]
          • If user credentials did match, credentials from home IDP are not migrated and user details are not migrated to local IDP and externalSystemsMapping is set. [end]
        • if user chooses home IDP as default, user credentials and user info is migrated to local IDP and externalSystemsMapping is set [end]
      • if user credentials fail against home IDP (either password is incorrect or they do not have an account - local IDP will not know the difference), user is credentials are checked against local IDP [end]
    • if user doesn't exist in local IDP, home IDP is checked
      • if user credentials are checked with home IDP, and is successful, the user is migrated and externalSystemsMapping is set [end]
      • if user credentials are checked against home IDP, and fails, the user is shown usr/pw error (since they don't exist anywhere and need to register) [end]

Exit criteria assumptions:

• If user exists in a second home IDP and has already been migrated, the system will not check or migrate the user from the second home IDP.
• 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 get 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 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 they need an endpoint to update the externalSystemsMapping array in the NI user record.

• The API will accept bearer token (from token delegation)
• The API will have a GET, POST, and DELETE function to get the list of external ids, create a new one, and delete one.
• The API will only be able to access the external system that they have access to so this will be handled by checking the client setting to get the external system id and then checking the user record and only allowing access to that entry.
• If the POST is being called and the system id already exists, the API will respond with failed to update a duplicate entry response. This should be clearly logged to be able to access later if needed.

See the External System API reference HERE