User repository migration

Edit online

IBM® Verify provides a simple way of migrating user repositories. The standard process for onboarding Verify users is to use the provided REST API. You can use the CSV import method to onboard users quickly.

IBM Verify supports the following ways to import user data.

Manual entry
CSV import API
User API (single)
Bulk load API (multiple)

The CSV import method is the most common approach.

Data information

Format of the data

To import users with the CSV method, Verify you must convert your user repository, either an LDAP or an SQL database, into a UTF-8 compatible CSV format. Ensure that the method that you plan to convert your data into supports this format.

Type of user

It is important to note the type of users you are importing. If you're not familiar with the Verify Cloud Directory model, read the article on the structure of the Verify directory. For this task, users that are being imported are given a standard cloud directory user account, with a local password, that is generated upon user creation. The regular user type determines this type of user. If you want to import just the metadata of the user without a local password, you must replace the attribute values for realm and userCategory.

Access token

The API client used to import users must have at least one of the following permissions in IBM Verify.

Manage users and groups
Synchronize users and groups
Manage users and standard groups

The application must acquire an Access Token by using the Client Credentials flow.

Get CSV headers

To properly structure your CSV file for import, you need to first understand what header options there are. If you're familiar with the user schema, the header name equals the attribute's identifier in SCIM. If you are using a custom attribute, then the value that was specified during attribute creation.

curl -X GET "https://${tenant_url}/v2.0/CSV/headerNames?filter=user" -H "Authorization: Bearer ${access_token}"

This response includes all possible header names. The name that you use in the a column in the CSV is in the name object name. In the call example, a user filter was added to prevent the return of the attribute names for Groups.

Create the CSV file

To build a quick and minimum CSV file of the basic user fields, with an auto-generated password, use this example.


`preferred_username`	`given_name`	`family_name`	`email`
user1	John	Doe	`jdoe@example.com`
user2	Jane	Smith	`jsmith@example.com`
user3	John	Jones	`jjones@example.com`

Append more columns as necessary. Attribute values can always be updated after the fact in the admin console. Save this file as a UTF-8 encoded CSV text file. The maximum file size is 10 MB. If your file is larger, break it up into multiple CSV files.

Note: If you exported your CSV from excel, the encoding oftentimes includes some odd characters at the beginning of the file. Open the file in a raw text editor and delete the characters. The characters look like: ï»¿ and is known as a Byte Order Mark (BOM). If you don't see the characters in the text editor, copy and paste the text into a new text editor and save as a new file.

Password migration

Verify supports onboarding existing Password migration and passwords that are given in plain text. If you want to create users with a known or hashed password, add a column that is called password to each user row, Verify creates a user with that password. If your database or LDAP provides the one-way hash in one of the supported formats, then you must get the value and prefix it with {TYPE}. For example, if you are using Salted-SHA256, the value must be prefixed with {SSHA256}.

Note: If your password has a '+' sign, escape any “+” signs by replacing them with “%2B”.

Example CSV file

This example is a CSV file with minimum information.

preferred_username,given_name,family_name,email
user1,John,Doe,jdoe@example.com
user2,Jane,Smith,jsmith@example.com
user3,John,Jones,jjones@example.com

Note: Spaces after commas break the import.

Import the file

After your file is created, a few more configurations exist that are supported. In the following call, all email notifications of new accounts are suppressed through the parameter notifyType=NONE. A random password is created on the first login, but the user does not have to reset it (the user can reset it later). To suppress the change password requirement on the first login, add the header

usershouldnotneedtoresetpassword:
true

curl --location -X POST "https://${tenant_url}/v2.0/CSV/importUsers?notifyType=NONE" \
--header "Authorization: Bearer ${access_token}" \
--header 'usershouldnotneedtoresetpassword: true' \
--form 'file=@/path/to/file/user_import.csv'

If the file was formatted correctly and accepted, you receive an ID back. This ID can be used to poll the status API to see whether everything is working OK. Users are processed linearly. A max file size (10 mb) file might take around 15-20 minutes to process.

Note: In the case of a random password, the user always gets an email, regardless of notify setting. If the password is specified in the CSV file, then notify set to NONE applies and the user does not get an email.

Check import status

While users are being processed, you can see the current status of the import by calling the CSV jobs API.

curl --location --request GET "https://${tenant_url}/v2.0/CSV/jobs/${id}" \
--header "Authorization: Bearer ${access_token}"

The response provides the current state and the statistics on the number of users that are unprocessed (unprocessedCount), and those users that were processed and added (processedCount). If any errors occur, a count is provided (errorsCount).

Bulk load

You can migrate millions of users by using the bulk APIs. See https://docs.verify.ibm.com/verify/reference/bulkrequest. However, it is more efficient to work with your Verify team to schedule the bulk load for you. You can open a support ticket with IBM support by using the web-based IBM Support Community or by telephone (1-800-IBM-SERV (800-426-7378). The service management team provides you with a secure upload location. You can then upload your user data to this location and the service management team loads your data in Verify.