Use case: Migrate users from a previous solution into ForgeRock Identity Cloud

Setup
, , , , , ,
#1

Use case overview

This use case explores the migration of user data, including passwords, from an existing data store to ForgeRock Identity Cloud.

Depending on the type of identity data stored in your source identity solution, it may be possible to export the hashed password data in a format supported by Identity Cloud. With this approach, user data can be synchronized with ForgeRock in a “big-bang” manner, enabling seamless login with their identity data stored in ForgeRock when the access control plane is switched.

However, the big-bang approach may not always be feasible, especially when identities are stored in an identity repository such as Active Directory (AD) that doesn’t allow the extraction of password hashes. In such cases, you can take advantage of ForgeRock’s Pass-through authentication capability. This feature allows you to verify passwords against a remote data store such as AD, without needing to migrate the data or require users to reset their passwords.

You can use a pass-through method when migrating batches of users from the source solution in a staggered way. If the user has already been migrated their credentials are checked locally. If no local record is found, then the system validates against the remote data source. This approach can help you migrate user data gradually (trickle migration) whilst ensuring seamless authentication for users.

In this use case, we’ll look at both big-bang and trickle user migration into Identity Cloud.

Big-bang migration

This approach migrates users, including their passwords, in bulk from a previous solution to Identity Cloud. It may be executed on-demand and/or according to a configurable schedule.

An example big-bang migration approach has three configuration stages:

  1. Connect Identity Cloud with the external user store
  2. Create a mapping
  3. Synchronize the data

This use case assumes that you already have an LDAP directory data store.

Connect Identity Cloud with the external user store

Steps for connecting Identity Cloud with an external LDAP user store can be found here: Connect ForgeRock Identity Cloud with an LDAP user store. The example connector described in that article (PreviousCIAM) can be used for big bang migration.

Note that the userPassword property of the account object type is a string. This allows credential synchronization for bulk migration.

uc_ldap_connector_account
uc_ldap_connector_account1165×1010 98 KB

Create a mapping

Steps for creating a mapping can be found here: Map attributes from an external user store to ForgeRock Identity Cloud. The example mapping described in that article (systemPreviousciamAccount_managerAlpha_user) can be used for big bang migration.

uc_mapping_props_tab
uc_mapping_props_tab1043×868 110 KB

Note the following configurations:

  • A transformation script has been configured to decode the password property in base64 format. This is required to migrate users, including their passwords, from the remote Directory Services (DS) system.

    uc_password_script
    uc_password_script800×704 140 KB

    See Synchronize passwords for further information on synchronizing hashed user passwords from your DS deployment into Identity Cloud.

  • The various Situation entries are listed in the Behaviors tab. All records evaluated across the two systems are placed into one of these categories and the specified Action is taken.

    Note the Absent situation has the value Create. This will result in users from the source system being created in Identity Cloud.

    uc_mapping_behaviors_tab
    uc_mapping_behaviors_tab1602×1536 159 KB

Synchronize the data

Reconciliations can be scripted, manual or scheduled. They can be a one-off bulk synchronization or scheduled to perform a regular synchronization to keep two data stores in sync.

Reconciliations can be scripted, manual or scheduled. The mapping can be manually reconciled for a one-time data import by clicking the Reconcile button. Alternatively, the system can be scheduled to reconcile at an interval to process changes since the initial import, and keep the two data stores in sync.

See Schedule synchronization for further information on creating schedules for synchronization.

Trickle migration

Trickle migration allows for seamless account migration, even if passwords cannot be synchronized or decrypted. This is achieved in Identity Cloud using a Journey that includes pass-through authentication.

When using trickle migration, the previous system first validates the user’s credentials. It then creates the user’s account in the Identity Cloud tenant on-the-fly and validates whether the password policy in Identity Cloud is compatible with the user’s password from the previous system. If it’s not compatible, the system forces a password change.

Users can also be pre-migrated without their passwords. After the migration, users can confirm their data or make changes as they like. Alternatively, the system can ask users to provide the required information, and only their username and password will be synchronized to Identity Cloud.

In either case, users can keep their existing password, unless it violates the password policy of the Identity Cloud tenant. If the password violates the policy, the system forces the user to change their password.

An example trickle migration approach has four configuration stages:

  1. Connect Identity Cloud with the external user store
  2. Create a mapping
  3. Synchronize the data
  4. Create a user journey for pass-through authentication

This example use case assumes that you already have an LDAP directory data store.

Connect Identity Cloud with the external user store

Steps for connecting Identity Cloud with an external LDAP user store can be found here: Connect ForgeRock Identity Cloud with an LDAP user store.

The following example shows an LDAP connector called trickleMigration:

uc_trick_migration_connector
uc_trick_migration_connector1160×939 104 KB

Once you have connected your user store, review the account properties:

  1. Sign in to the Identity Cloud admin UI using your admin tenant URL, in the format https://<tenant-name>/am/XUI/?realm=/#/.

  2. Go to Native Consoles > Identity Management > Configure > Connectors.

  3. Click the connector you are using for the migration, in our example the connector is called trickleMigration.

  4. Click the Object Types tab to review the object properties.

    In our example, we have an Object Type called account. Note that the userPassword property is missing.

    uc_account_tricke_connector
    uc_account_tricke_connector1184×942 88.3 KB

Create a mapping

Steps for creating a mapping can be found here: Map attributes from an external user store to ForgeRock Identity Cloud.

The following example shows a mapping from system/TrickleMigration/account to managed/alpha_user.

uc_trickle_mapping
uc_trickle_mapping1186×460 75.5 KB

Once you have created your mapping, review the following configuration:

  1. Sign in to the Identity Cloud admin UI using your admin tenant URL, in the format https://<tenant-name>/am/XUI/?realm=/#/.

  2. Go to Native Consoles > Identity Management > Configure > Mappings.

  3. Select the mapping you created for the migration. In our example, the mapping is called systemTricklemigrationAccount_managerAlpha_user.

    uc_trickle_migration_mapping
    uc_trickle_migration_mapping1200×939 101 KB

    Note the mapping of the source uid to the target attribute userName, which will require the user to log in with their user ID.

    Note that there is no mapping for the password attribute.

  4. Click the Behaviors tab and review the various Situation entries listed. All records evaluated across the two systems are placed into one of these categories and the specified Action is taken.

    Note the Absent situation has the value Create. This will result in users from the source system being created in Identity Cloud.

    uc_mapping_behaviors_tab
    uc_mapping_behaviors_tab1602×1536 159 KB

Synchronize the data

Reconciliations can be scripted, manual or scheduled. The mapping can be manually reconciled for a one-time data import by clicking the Reconcile button. Alternatively, similar to the big bang approach, the system can be scheduled to reconcile at an interval to process changes since the initial import.

See Schedule synchronization for further information on creating schedules for synchronization.

Create a Journey for pass-through authentication

Identity Cloud provides a Pass-through Authentication node to capture hashed passwords when they cannot be synchronized.

With the Pass-through Authentication node, Identity Cloud performs authentication through a connector and stores the captured password securely using a strong, one-way hash algorithm. Identity Cloud can then act as the service of record for the authentication of that account.

The following example journey demonstrates password capture and storage using pass-through authentication, which can be used for trickle migration. The journey can be used for both pre-migrated users and users who have not been migrated yet:

uc_passthrough_journey
uc_passthrough_journey3212×1492 256 KB

The default path for pre-migrated users is as follows:

  1. The login page prompts the user for a username and password.

  2. The user’s credentials are evaluated against the data store in Identity Cloud. This will fail because no password has been synchronized yet.

  3. The Passthrough Authentication node tries to verify the credentials against the endpoint of the configured connector, which will pass if the user-provided credentials match. In our example, the connector is called trickleMigration.

    uc_passthrough_node
    uc_passthrough_node568×1112 83.9 KB

    See Passthrough Authentication node for further information.

  4. The flow then follows the authenticated flow, with the Identify Existing User node outcome of True.

  5. Assuming that all required attributes were already migrated, the Required Attribute Present node should return True.

  6. If the user-provided password is compliant with the password policy in the Identity Cloud tenant, the password is stored in the migrated identity object. The Patch Object node returns Patched, the login counter is incremented, the progressive profiling is requested (if necessary), and the user is logged in.

  7. If the user-provided password is not compliant with the password policy, the Patch Object node returns Failed, and a new compliant password is requested before continuing the flow as described above.

The default path for users who have not been pre-migrated is very similar. The main difference is that the identity object has to be created (8). This will fail if the previously used password is not compliant with the password policy of the Identity Cloud tenant. Then a new, compliant password is requested from the user (9), the new identity object is created (10) and the flow continues as described above.

After the user has authenticated successfully through this journey, the user can authenticate locally in Identity Cloud. The user no longer needs to authenticate using the remote service.

See Journeys for information on creating Journeys in Identity Cloud.

Additional resources

Documentation:

Training videos:

Community articles:

1 Like
ForgeRock Identity Cloud: Adding new users to an identity system
A comprehensive approach to CIAM vendor selection