User Migration

The user migration is often the first part of setting cidaas live. Therefore it is important to have a step by step guide, how to start to migrate the users, how to map the data and what are the issues you need to address during migration.

info

Migration Procedures

For decision making how to go live, the documentation for one-time-migration, bidirectional-sync or long-term migration is more helpful.

Term	Description
API Link	Bulk User Migration API
Security by Scope	To secure the API you need to use cidaas:bulk_user_create
Security by Config	Furthermore there is a configuration called migrationMode. Only if this is set to true you are allowed to overwrite passwords a second time

Step 1. Determine the information to migrate

Verify the information you would like to migrate.

Question	Description
Which information are you going to migrate	e.g. email, mobile_number, password_hash_info, createdTime, lastLoggedInTime. Those are so called system fields. You need to ensure those are enabled in the field setup
Do you also migrate account timestamps?	Optional: createdTime (original registration date) and lastLoggedInTime (last login in the source system) on the user account. See Account timestamps below.
Do you also migrate customFields?	If you have custom information that is not covered by the system information you can create your own custom fields. This you need to provide in the customFieldsas key-value Pair.
Do you want to migrate users, that have multiple providers?	If you want to migrate users which can have two or more providerinformation e.g. facebook, google and a password, you need to use the identities array. UserEntity

Step 2. Create a Token using the client credentials Token

To Create a Token using the Client Credentials OAuth2 Flow, you can find a flow chart and API Explantion here

Please ensure that your App is having the proper scope cidaas:bulk_user_create and create a NON_INTERACTIVE App, which can be called user-migration. To create your first App, you can use this guidance.

Step 3. Integrate the User Bulk API

1. You will need to get the data from your data source
2. Map the incoming (source) data to a structure described in the Bulk API
3. Add the Token generated in Step 2. as Authorization: Bearer eyxxxx Header
4. Call the API via Post Call

The simplest json is this one:

{
  "userStatus": "VERIFIED",
  "sub": "8dfc4306-9f3b-4a33-95d0-98c8954da2c1",
  "email": "[email protected]",
  "password_hash_info": {
    "algorithmTypeId": "BCRYPT_10",
    "passwordHash": "$2b$10$EfrjjYYGih4j4AbnpIWT2OEjvvRoYNBDJ0Wv2E.MwE/oZ87hasAHi"
  },
  "provider": "self",
  "createdTime": "2019-08-24T14:15:22Z",
  "lastLoggedInTime": "2023-06-15T15:24:19.378Z"
}

Account timestamps

When your source system stores registration or last-login dates, include them on each user entity so admin views and reporting stay accurate after migration.

Field	When to send	Behavior
createdTime	Original account registration date from the legacy system	Applied when the user account is created. Mainly relevant for first-time migration of a user.
lastLoggedInTime	Last successful login in the legacy system	Create: uses your value when provided; otherwise cidaas sets the current time. Update: uses your value when provided; otherwise the existing value in cidaas is kept (not reset to the current time).

Use ISO 8601 date-time strings (for example 2023-06-15T15:24:19.378Z).

Validations	How to enable those
Missing required Fields	A useraccount must have a valid user identifier e.g. an email. Else the API will return a BAD_REQUEST (400)
Allow Disposable Emails and Validate Mobile Numbers	It is possible to enable or disable email/mobile number validation via the App configuration settings. If allow_disposable_email is set to false (default) on the App, any disposable email address in the import batch will fail validation, causing the API to return the error "invalid email passed" (error code 507, HTTP status 400). You can bypass this validation by setting allow_disposable_email: true in your App settings. Similarly, you can adjust mobile validation settings (validate_phone_number) to control phone number verification.
Invalid Datatype	Please ensure that you are providing the fields (custom and sytem fields) in the same datatype format that is set in the field setup. Any invalid value for datatype or invalid format can lead to failures during migration. Also disabled fields will be skipped
Invalid timestamp format	createdTime and lastLoggedInTime must be valid date-time values. Unparseable values may be ignored, and cidaas may fall back to default timestamp behavior for that field.

Troubleshooting Migration Failures

During user migration, the Bulk API performs validation checks on all incoming user records. If a record fails validation, the individual user migration attempt will fail with a FAILED process state and include a detailed error message in the message field.

Resolving "invalid email passed" Error

A common error encountered during batch imports is the following:

{
  "code": 507,
  "status": 400,
  "error": "invalid email passed"
}

Potential Root Causes

• Disposable/Temporary Email Domains: The email address contains a disposable email domain (e.g., mailinator.com, yopmail.com), and your Cidaas application is configured to reject disposable emails.
• Incorrect Email Syntax: The email address is not well-formed according to RFC standards (e.g., missing @ symbol, spaces in the address, invalid characters).
• Domain DNS Validation Failure: Cidaas is configured to verify the domain DNS MX/A records, and the domain of the email address is invalid or unresolvable.

Step-by-Step Resolution Guide

Follow these steps to verify and update your Cidaas configuration or migration data:

Step 1: Verify and update App Configuration (Recommended for test users) If you are using temporary or test emails in your migration batches, you must configure your application to allow disposable emails:

1. Log in to your cidaas Admin Portal.
2. Navigate to Apps > App Settings and select the application (client ID) used for migration.
3. Scroll down or go to the Security/Verification Settings section.
4. Locate the Allow Disposable Email toggle and switch it to Enabled (or set it to true if configuring via the API).
5. Alternatively, you can programmatically update this setting on your client application by making a request to the Update Client API and passing "allow_disposable_email": true in the request body.

Step 2: Sanitize migration batch data For production migrations, we recommend sanitizing email records before initiating the migration:

1. Ensure all email addresses conform to standard formatting (e.g., no leading/trailing spaces, contains a single @ sign, and has a valid top-level domain).
2. Filter out disposable/temporary email addresses from the export if your application restricts them for security.
3. Validate that the domains of the email addresses are active and have valid DNS MX or A records.

How cidaas uniquely identifies and updates the user if already migrated

Description	Example
Update users via sub	To update a user via sub, which remains stable, is the best way to re-migrate/update the useraccount and identities
Update via useridentifier combined with provider	If the sub is not provided, the incoming useridentifier like email as well as the provider e.g. facebook is search and the retrieved users sub will be set automatically by cidaas.

warning

Add further identities to an existing user

If you migrate users with multiple providers, please ensure that you provide a sub, else it will lead to conflicts.

To prevent a conflict, if the user already exists you can do following:

1. Call the existence api by userId Link to API
2. Take the sub and set this in the requestBody for the bulk API.