Use identity developer APIs to migrate users into Arc XP Identity

Arc XP Identity migration API allows you to seamlessly transfer your current customer profile and login information from your previous identity provider. After a successful migration, your users can log in to your content hosted on Arc XP, without needing to create new user accounts.

Arc XP Identity provides two migration options. The path you choose depends on your plans and business.

• Batch migration of all your users at once
• Migrate users over time as they sign into your Arc XP site

In this guide, you will learn how to use the Arc XP Identity developer migration APIs to move your users from your current identity provider into Arc XP.

Prerequisites

Before you can begin the migration of records into Arc XP, you must have:

• Arc XP Subscriptions has been fully provisioned for your organization.
• Ensure you meet the prerequisites defined for Manage User Accounts: Developer Interface.
• All API tokens for access to current identity provider data have been collected.
• An exports of existing users. If it is determined that this data cannot be exported, then the users can be migrated in over time.
• A Keybase account set up so sensitive data can be sent to Arc XP engineers and Technical Account Managers. API tokens and user exports can contain sensitive information and should be sent securely through Keybase.

Setting the Password Algorithm

For users to be migrated to Arc XP Identity and to not need to change their passwords, you must use the same cryptographic hash function in Arc XP as your current identity provider. Identity can accept hashed and, optionally, salted passwords with the following algorithms:

• MD5
• SHA-256
• SHA-384
• SHA-512

When maintaining the previous password algorithm is not possible or desired, you can migrate existing users to Arc XP without maintaining their existing passwords. When these users visit the site after the change to Arc XP occurs, they are prompted to create a new password. In this situation, you must set the password algorithm to reset.

Which Password Algorithm Should I Use?

All organizations are provisioned with sha2 and the SHA-1 cryptographic hash function by default. Once you determine how you would like to migrate your user passwords, you will need to communicate your choice of password algorithm and cryptographic hash function to your Technical Account Manager prior migrating any users into Arc XP Identity if you don’t want to use the default settings. You cannot change your selection once user migration has begun.

Setting	Description	Workflow Options
reset	User must use the forgot-password functionality to log in for the first time	Use forgot password workflow
copy	User is created without a password	Credentials Field Options in migration API request: Empty - Users will need to do a password reset on first login using forgot password workflow Plan text password - Users can continue to use this password or use the standard password reset workflow
sha2	Hashed passwords must be provided by client with the user migration API	If you select sha2, ArcXP will use the password migration algorithm you specify to validate migrated passwords. The password migration algorithm could take one from several options: passwordMigrationAlgorithm: MD5 | SHA-256 | SHA-384 | SHA-512

Having trouble deciding on how to migrate your users to Arc XP identity?

If you have:

• Full export of all users
• Passwords can be migrated

Then a batch migration might make sense for your organization.

If you have:

• All users are not available in an extract
• Passwords cannot be exported or migrated
• Risks/Issues: Passwords can some times be captured during sign-on but there is a risk that they will need to be reset

Then you should probably use the password reset flow of the reset option and plan to migrate users when they log in.

Getting Started

Once you have identified how you want to migrate your users into Arc XP, you must request to have migration enabled for each site you will be migrating users for. This request can be made through your Technical Account Manager. You should double check that Arc XP Subscriptions has been provisioned before going any further.

To verify that the Subscriptions application has been properly provisioned:

• Log in to Arc XP and click on the Subscriptions tile.
• View the Customer tab.

If you see the Customer page, then Subscriptions has been provisioned for your site.

Verify Identity APIs

To verify that the Identity APIs have been properly provisioned, test that you are able to perform a simple GET request to an Identity endpoint API. The following API call should return a 200 success message, even if the result sets are empty.

curl --request GET \
  --url 'https://{base_URL}/identity/api/v1/user?search=firstName%3Djohn%7ClastName%3DDoe' \
  --header 'Authorization: Bearer {ARC_ACCESS_TOKEN}'

You might not get any results back from this curl, but the important thing is the HTTP response code received is HTTP 200 success.

Enabling The Migration APIs

The migration APIs are disabled by default. When you are ready to begin the migration, you must request that this endpoint is enabled and also provide the length of time that you require for your migration. The expected length of time depends on if you have access to all of the identity users that are migrating at one time, or if you need to capture the identity users over time as the users naturally visit the site (as with users logging in from Cognito, Facebook, or an OIDC provider). Discuss these details with your Technical Account Manager so that the subscriptions team knows how long to keep the Migration API endpoint active.

Configure The Identity Providers

At this time you should verify that the identity providers are configured for each site for your organization. When external identity provider is used, like Google or Facebook, you will need to provide the API Keys for the external service. The API keys can be configured in the Settings Admin. There may be times, when required key fields are not available in the Admin. A Subscriptions engineer will need to help configure the providers in the Subscription application. You must provide these API keys to Arc XP through Keybase, to protect them from being exposed or leaked.

Configure WebSocket Listener

The Data coming into Arc XP Subscriptions can be viewed by configuring a WebSocket connection. The WebSocket listens to events coming from one website at a time and allows you to perform custom actions. Your WebSocket handlers can perform any additional actions you need when a customer is migrated.

Testing Migration In Sandbox

Before proceeding with testing your migration process in our sandbox environment, you must have completed:

• Configuring your password migration scheme with either reset, copy, or sha2
• You’ve contacted your Technical Account Manager to enable migrations APIs for your organization
• Setting up your connection to WebSocket events to receive events from the migration
• Confirm that your test users in your extracts in the sandbox environment don’t contain any PII from your production system.

Now you should be able to begin testing our user migration APIs in the sandbox environment.

curl --request POST \
  --url 'https://{base_URL}/identity/api/v1/migrate' \
  --header 'Authorization: Bearer {ARC_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "records": [ { "identities": [ { "userName": "john.doe@donotreply.com", "credentials": "0a4d55a8d778e5022fab701977c5d840bbc486d0", "grantType": "password" } ], "profile": { "firstName": "John", "lastName": "Doe", "secondLastName": "Doey", "displayName": "john.doe@donotreply.com", "gender": "MALE", "email": "john.doe@donotreply.com", "birthYear": "1999", "birthMonth": "11", "birthDay": "15", "attributes": [ { "name": "is_professor", "value": "true", "type": "Boolean" }, { "name": "job_title", "value": "Manager", "type": "String" } ], "legacyId": "AA132CF97" } } ] }'

Note

When existing user accounts come from an existing Identity provider, such as Cognito, you cannot batch-import them. Your migration process must be written in such a way to allow these users to be created in Arc XP Identity as the users naturally visit the site on Arc XP.

User accounts that are created with the Migration API endpoint are recognizable in the Arc XP Identity as different from other Identity users for testing purposes. Migrated identity users need to have correct values set for fields related to their IDs, passwords, and spending tokens. Technical details on how to proceed with individual user migration is in Cognito migration in Arc XP Identity guide.

Verify User Migration Data in Sandbox

When you’ve migrated some users into Sandbox, you must ask that the subscriptions engineers validate that the users have been created successfully. Provide the previous identity provider’s password hash and salt along with an example testing password to your Technical Account Manager so the subscriptions engineers can test if users’ sessions can be maintained.

Subscription engineers must review the migrated users to see if they can spot data that seems wrong or inconsistent with what will be successful in Arc XP Identity.

Enable User Migrations in Production

After you have confirmed that you successfully migrated users in the Sandbox environment, you will need to test a small sample set of users in Production through your migration process so that the subscription engineers can do a quality check on the migrated user data. We require this small test in Production because it’s hard to fix wrong user data once it is in our production environment.

Completing Migrations

When the migration of users and subscriptions are complete, the Subscriptions Migration API and any additional back-end process the engineers had instantiated to support the migration is turned off. The Subscriptions Migration API endpoint will no longer accessible.

Users who are created through OIDC or social login are not associated with the use of the Subscriptions Migration API endpoint, and so are not subject to this deadline.

Troubleshooting

When you encounter an issue, please provide an example of the complete curl request showing the API endpoint that is being requested, along with the payload, query parameters, HTTP request headers (except the Bearer token - which must not be included). Including a complete example of your request will allow issues to be resolved faster.

• If you need to know the base_URL and ARC_ACCESS_TOKEN to use, please refer to Manage user accounts: Developer interface.
• For details about the allowed values for user account parameteres, please refer to Parameters: Regex Expression and validation for Arc XP Identity APIs.