Migrating Data for Enabling Single Sign-On

Overview

The SSO migration utility of IBM PEM helps to migrate the existing data in IBM PEM.

To migrate the data, the utility exports existing IBM PEM system, sponsor and partner data in a CSV file and takes the updated CSV file to migrate data. After processing all the records, the utility generates a report on the status of data migration. In case of any failure, it generates an appropriate error message. The SSO migration process has the following steps:

Export: This step is performed by executing the utility with action as EXPORT. When executed, the utility will list organizations' and users' data in IBM PEM and export them to CSV files.
Update: This is a manual step and it is performed outside the utility. The CSV files that are exported as part of the Export step should be updated with the details in the external system (e.g. LDAP).
Migrate: This step is performed by executing the utility with action as MIGRATE. The utility takes the updated CSV files as input and migrate the organization’s and user’s data one by one in IBM PEM. Once the migration is complete, the utility generates the migration report in CSV format.

Prerequisite for Data Migration

Remember: The data to be migrated should be present in the external system (e.g. LDAP).

Before performing the data migration task, DevOps user should follow the instructions:

Inform the sponsor admin to approve or reject all existing organizations and users that are in approval pending or registration pending stage.
Inform the sponsor admin to update the API configurations for both PEM portal and PEM partner repository to authenticate with internally generated token.
Inform all system, sponsor and partner users about the maintenance period for the migration.
Note: The IBM PEM servers will be unavailable during the migration period.
Inform the DBA to take a back-up of IBM PEM database.
Note: The database back-up should be taken every time before you migrate the data for SSO as the migration process includes manual steps and the data cannot be recovered in case of an error.

Running the SSO Migration Utility

When you call the SSO migration utility, the data is either exported or migrated based on the configured migration action. To complete the data migration, at first call the utility with the Export action and then with the Migrate action.

To migrate existing system, sponsor and partner organizations' and users' data in IBM PEM, you need to follow the below steps:

Export the existing data in IBM PEM. To export, follow the steps:

Configure the SSO migration properties in Setup.cfg and set the migration_action property to EXPORT. For more information on setting the properties, refer to section Configuring the properties of Setup.cfg file.
Run the SSO migration utility. For more information on how to run the utility, refer to section Deploy the SSO Migration Utility.

Export action will export the following:

Organizations CSV file, refer to the table for details:

CSV column	Description
Company Name	Contains the name of the Sponsor or Partner company in IBM PEM.
Company External ID	Contains the unique ID of the company in the external system. The column will be empty for non migrated company.
Primary Admin User ID	Contains the User ID of the primary admin of the company.
Is Sponsor Company?	This column contains Y or N based on if the company is a Sponsor company or a Partner company.
Partner Unique ID	Contains the partner unique ID for Partner companies.
Company Key	Contains the company key in IBM PEM.
Migration Status	Contains the migration status of the company.
Description	Contains the description for migration status of the company. This column will be empty for export.

Note:

For Sponsors, only approved organizations are eligible for migration. Export action will export only the approved organizations in the CSV file.
For Partners, only approved and inactive organizations are eligible for migration. Export action will export only the approved and inactive organizations in the CSV file.

Users CSV file, refer to the table for details:

CSV column	Description
Email	Contains the User ID in IBM PEM.
User ID	For users that are migrated, this column contains the User ID in external system. The column will be empty for non migrated user.
User External ID	For users that are migrated, this column contains the unique ID of the user in the external system. The column will be empty for non migrated user.
First Name	Contains the first name of the user.
Last Name	Contains the last name of the user.
Company Name	Contains the name of the Sponsor or Partner company of the user.
Is Sponsor User?	This column contains Y or N based on if the user is a Sponsor user or a Partner user.
Company User Key	Contains the company user key in IBM PEM.
Migration Status	Contains the migration status of the user.
Description	Contains the description for migration status of the user. This column will be empty for export.

Note: Only Approved or Inactive users are eligible for migration. Export action will export only the approved and inactive users in the CSV file.

Update the CSV data with external system details. To update, follow the steps:

Each row in both CSV files should be validated and updated.

By referring the organization and user details in the external system for each file, update the following:

Organization CSV Column	Description
Company Name	Update the name of the company as per the external system.
Company External ID	Update the unique ID of the company as per the external system.

User CSV Column	Description
Email	Update the email address of the user as per the external system.
User ID	Update the User ID as per the external system.
User External ID	Update the unique ID of the user as per the external system.
First Name	Update the first name of the user as per the external system.
Last Name	Update the last name of the user as per the external system.

Migrate the data in IBM PEM. To migrate, follow the steps:
1. The migrate action will take the two updated CSV files as input to migrate the organization’s and user’s data.
2. Configure the SSO migration properties in Setup.cfg and set the migration_action property to MIGRATE and file name properties. For more information on setting the properties, refer to section Configuring the properties of Setup.cfg file.
3. Run the SSO migration utility. For more information on how to run the utility, refer to section Deploy the SSO Migration Utility.
4. Once the migration is complete, two CSV files will be exported with the migration status and description for each row.

Once the migration is complete, the DevOps user should inform all the system, sponsor and partner users that the maintenance activity is completed, and users can now use their SSO credentials to access IBM PEM.

Generating the Migration Report

The migration tool can be used to generate a report for all existing system, sponsor and partner organization’s and user’s data along with their status in IBM PEM. To generate a report of all existing system, sponsor and partner organization’s and user’s data in IBM PEM, follow the steps:

Configure the SSO migration properties in Setup.cfg and set the migration_action property to REPORT. For more information on setting the properties, refer to section Configuring the properties of Setup.cfg file.
Run the SSO migration utility. For more information on how to run the utility, refer to section Deploy the SSO Migration Utility.
The Report action will export two CSV files, one for the organizations and the other for users.