Migrate User Accounts, Roles and Business Units to the FintechOS Identity Provider

Starting with release 22.1, the FintechOS Platform uses the FintechOS Identity Provider for identity and access management. In order to facilitate user accounts, roles and business units migration from legacy systems to the FintechOS Identity Provider, an automatic user migration tool has been provided.

To use the migration tool, follow the instructions below:

1. Make sure .NET 5.0 Desktop Runtime is installed on your system.
2. From the FintechOS Platform installation kit, copy the User Migration Tool archive and extract it on your system.
3. In the extracted folder, run the User Migration Tool executable (FTOS.Tools.UserMigrationToIdpUi.exe).
   
4. Fill in the following information:

   Field	Description
   DB server	Required if Use a connection string instead is not checked. Database server address of your legacy FintechOS system.
   DB user	Required if Use a connection string instead is not checked. Database username used to connect to the legacy FintechOS database to download user accounts and user roles.
   DB password	Required if Use a connection string instead is not checked. Database user password for the above user account.
   DB initial catalog	Required if Use a connection string instead is not checked. Database name of your legacy FintechOS system.
   Use a connection string instead	Uses the database connection string provided in the DB Conn. string field to connect to the legacy FintechOS system database instead of the above settings.
   DB Conn. string	Required if Use a connection string instead is checked. Allows you to provide a database connection string which will be used to connect to the legacy FintechOS system database.
   IDP URL	Required. URL of the FintechOS Identity Provider instance.
   IDP realm	Required. FintechOS Identity Provider realm set up for the FintechOS Platform.
   IDP client id	Required. Client ID set up in the FintechOS Identity Provider for the Innovation Studio.
   IDP client secret (v22.1.1 and later)	Required. The client secret associated with the client ID.
   IDP admin API username (v22.1 only)	A user account set up in the FintechOS Identity Provider admin console with realm management role.
   IDP admin API secret (v22.1 only)	Password for the above user account.
   Save output to file (v22.1.1 and later)	Specify a .csv file where information regarding the users/roles/business units that have been migrated (together with the migration status) will be saved. If not specified, the output will be directed to the text area below.
   Command line & results (v22.1 only)	You can use the automatically generated command to run users/roles/business units migration from the command line.
   Save to log file (v22.1 only)	Allows you to define a text file where the migration results will be logged.
   Migrate roles	Specify whether or not the tool should migrate user roles. IMPORTANT!   In order the properly migrate the users, the roles must be migrated first. Either check both Migrate roles and Migrate users (the tool will first migrate the roles, and then the users) or run the tool first with the Migrate roles option checked, then run it again with the Migrate users option checked. If the tool tries to migrate the users before the roles are migrated, it will fail.
   Migrate users	Specify whether or not the tool should migrate user accounts. IMPORTANT!   User accounts without a valid email address will not be migrated. If another user account with an identical email address already exists in the FintechOS Identity Provider, the user will not be migrated (the legacy database authentication does not enforce unique email addresses for user accounts).
   Migrate BU	Specify whether or not the tool should migrate business units.
   Skip external users (v22.1 only)	Does not migrate external user accounts (users with a valid entry in the MembershipProviderUserId attribute).
   Overwrite roles	Specify whether or not the tool should overwrite matching user roles that already exist in the FintechOS Identity Provider.
   Overwrite users	Specify whether or not the tool should overwrite matching user accounts that already exist in the FintechOS Identity Provider.
   Overwrite BU	Specify whether or not the tool should overwrite matching business units that already exist in the FintechOS Identity Provider.

5. (v22.1.1 and later) Click Test Run!. This will not commit the results. This step performs a dry migration (the tool simulates the actual migration), but the results are not saved.
6. (v22.1.1 and later) After the test run is finished, check the output .csv file and look for roles/users/business units that have the ERROR status. This indicates that the corresponding users/roles/business units will have issues during the real migration. Check the Reason column to determine why a user/role/business unit is in an error state and fix the issue.
7. (v22.1.1 and later) If, during the previous step, you had to fix any errors, you can close the tool and run it again to make sure there are no more issues.
8. Click Run Migration! This action commits the results and the users/roles/business units are migrated to the FintechOS Identity Provider.

Check the Migration Output

The test migration cannot identify all the possible errors that might occur during the actual migration. Even if, based on the test migration output, all the users/roles/business units should be migrated successfully, make sure to also check the actual migration output file and verify the statuses of the users/roles/business units that have been migrated. If additional errors (that couldn’t be identified in the test run) are present, try to fix them based on the information in the Reason column.

Troubleshooting

During the test run, the following errors may occur:

• A role that needs to be migrated is found, but the Overwrite roles option is not checked. In this case, during the actual migration, the role will be skipped.
• There are users with duplicate emails or usernames in the legacy database. The legacy database and applications support multiple users with identical email addresses or usernames, but the FintechOS Identity Provider doesn’t! To fix this, make sure that there are no duplicate email addresses or usernames in the database. If the errors are not fixed, during the actual migration, only the first such encountered user account will be migrated successfully.
• The user does not have an email address. This is a required field in the FintechOS Identity Provider, so users that do not have a valid email address will not be migrated. Make sure that all the users have a valid email address prior to running the actual migration.
• The user does not have a username. This is a required field in the FintechOS Identity Provider, so users that do not have a username will not be migrated. Make sure that all the users have unique usernames assigned prior to running the actual migration.
• A matching username has been found in the FintechOS Identity Provider, but the email address is different.
• A matching email address has been found in the FintechOS Identity Provider, but the username is different.
• Two matches are found in the FintechOS Identity Provider for the user to be migrated: one that matches the username and one that matches the email address.
• A matching user is found in the FintechOS Identity Provider, but the Overwrite users option is not checked. During the actual migration, this user will be skipped.
• There is an issue connecting to the database or the FintechOS Identity Provider. This will be notified in the text area of the tool. The users/roles/business units migration will not proceed.
• There is an issue connecting to the database or the FintechOS Identity Provider. This will be notified in the text area of the tool. The users/roles/business units migration will not proceed.
• None of the Migrate roles, Migrate users, or Migrate BU options are checked. The migration will stop, as there is no actual migration to be done.
• The test run has finished (the Run Migration button is visible), then one of the migration options changes. The migration tool will reset and the Test Run button will be displayed again. This is to make sure that the test run results are accurate.