Ping Migration Guide

This guide is designed to help customers migrate from PingOne to Descope.

Descope’s migration tool streamlines the process of moving users, tenants, and roles between identity providers (IdPs), ensuring a smooth and consistent transition.

Because PingOne uses separate APIs for each environment, performing a full migration is the most efficient and reliable approach. The provided migration script leverages the Descope SDK to transfer users, tenants, roles, and permissions from PingOne into Descope, ensuring that users are correctly associated with their respective tenants and roles in the new system.

Full Migration

Prerequisites

Ensure you have the following before starting:

• Access to your Ping Admin Console
• Access to your Descope Console

1. Importing from Ping

Creating a Ping Worker Application

Follow these steps to set up a Ping Worker App, which you will need to complete the migration:

1. You will need to create a Worker app inside of your PingOne admin console. To do so, navigate to Applications --> Applications.

2. Click the + icon to create a new application, and select Worker as the application type.

3. In the Roles tab of your new application, select Grant Roles, and assign the Organization Admin and Environment Admin roles both at the Organization level.

The Roles tab of your application should now look like this:

For the next section, refer to the Overview tab of your application:

Configure Local Environment

You will need the following to set up your environment for migration:

1. Client ID assigned to your Worker app, found under the Overview tab of that application.

2. Client Secret assigned to your Worker app, found under the Overview tab of that application.

3. Environment ID of the Ping environment that contains the admin Worker application you created previously, found under the Overview tab of that application.

4. PingOne API authentication path for your particular geographical region. As an example, the PingOne top-level domain for the United States is https://auth.pingone.com/v1.

5. Descope Project ID, which can be found here.

6. Descope Management Key, you can create one here if needed.

Required Custom User Attributes

Before running the migration, you must manually create the following custom user attributes in the Descope Console under Users → Custom Attributes. These attributes are essential for supporting the migration process and ensuring smooth post-migration handling.

Setting Up the Migration Script

1. Clone the Repo:

git clone git@github.com:descope/descope-migration.git

2. Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

3. Install the Necessary Python libraries

pip3 install -r requirements.txt

4. Setup Your Environment Variables

You can change the name of the .env.example file to .env to use as a template. Then populate with the items generated within the prerequisites section of this guide.

# Required, this is the Client ID of your PingOne Worker app
PING_CLIENT_ID=<Your PingOne Worker app Client ID>
#  Required, this is the Client Secret of your PingOne Worker app
PING_CLIENT_SECRET=<Your PingOne Worker app Client Secret>
#  Required, this is the ID of the PingOne environment that contains your Worker app
PING_ENVIRONMENT_ID=<Your PingOne Worker app Environment ID>
#  Required, this is the top-level API domain for your geographical region
PING_API_PATH=<Your PingOne Top-Level Domain>
# Required, this is your Descope Project ID
DESCOPE_PROJECT_ID=<Your Descope Project ID>
# Required, this is your Descope Management Key
DESCOPE_MANAGEMENT_KEY=<Your Descope Management Key>

Running the Migration Script

You can use the -v or --verbose flags to enable more detailed output. This works for both live and dry runs, providing you with additional information.

Dry Run

You can dry run the migration script which will allow you to see the number of users, tenants, roles, etc which will be migrated from Ping to Descope.

python3 src/main.py ping --dry-run

The output would appear similar to the following:

Would migrate 112 users from PingOne to Descope
Would migrate 2 roles from PingOne to Descope
Would migrate MyNewRole with 2 associated permissions.
Would migrate Role with 0 associated permissions.
Would migrate 2 environments from PingOne to Descope tenants.
Would migrate Tenant 1 with 5 associated users.
Would migrate Tenant 2 with 4 associated users.

Live Run

To live migrate your Ping users, follow the below example.

python3 src/main.py ping

The output will include the responses of the created users, organizations, roles, and permissions as well as the mapping between the various objects within Descope. A log file will also be generated in the format of migration_log_ping_%d_%m_%Y_%H:%M:%S.log. Any items which failed to be migrated will also be listed with the error that occurred during the migration.

Starting migration of 112 users found via PingOne API
Starting migration of 2 roles found via PingOne API
Starting migration of MyNewRole with 2 associated permissions.
Starting migration of Role with 0 associated permissions.
=================== User Migration =============================
PingOne Users found via API 112
Successfully migrated 110 users
Successfully merged 2 users
Users migrated, but disabled due to one of the merged accounts being disabled 1
Users disabled due to one of the merged accounts being disabled 
Failed to migrate 2
Users which failed to migrate:
facebook|122094272078100956 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
facebook|10226222057950897 Reason: {"errorCode":"E011002","errorDescription":"Request is missing required arguments","errorMessage":"Missing email or phone","message":"Missing email or phone"}
Created users within Descope 108
=================== Role Migration =============================
PingOne Roles found via API 2
Successfully migrated 2 roles
Created roles within Descope 2
=================== Permission Migration =======================
PingOne Permissions found via API 2
Successfully migrated 2 permissions
Created permissions within Descope 2
=================== User/Role Mapping ==========================
Successfully role and user mapping
Mapped 1 user to MyNewRole
Mapped 2 user to Role
=================== Tenant Migration ===========================
PingOne environments found via API 2
Successfully migrated 2 tenants
=================== User/Tenant Mapping ========================
Successfully tenant and user mapping
Associated 5 users with tenant: Tenant 1
Associated 4 users with tenant: Tenant 2

2. Password Migration

PingOne does not support exporting of hashed passwords. As a result, you have two options when migrating to Descope, both of which can be handled through Descope Flows.

1. Require Password Reset on First Login You can configure a Flow to prompt users to reset their password the first time they sign in through Descope. After resetting, users will authenticate using their newly set password for future logins. Learn more on our Flows page.

2. Move to Passwordless Authentication Alternatively, you can adopt a fully passwordless approach. Descope supports a variety of passwordless authentication methods. Explore them on our Authentication Methods page.

3. Merging Identities Across Environments

If a user has multiple identities across distinct Ping environments, you can use Descope’s multi-tenancy capabilities to consolidate these identities into a single user identity.

During migration, the script will:

• Assign all associated loginId values to the consolidated Descope user.
• Map the unified user to multiple tenants, preserving the roles and permissions the user holds within each tenant.

As a note, if a user has roles assigned in a Ping environment but does not exist in that environment’s user directory, those role relationships will not be migrated to Descope, as they cannot be mapped to an existing user.

Post Migration Verification

Once the migration tool has ran successfully, you can review the migrated items from Ping in the Descope Console:

• Users,
• Roles
• Tenants

Be sure to verify the created records against the migration tool’s output.

Next, you can define your users’ login experience. By leveraging the freshlyMigrated custom user attribute, you can create conditional paths within your Descope Flows.

From this conditional, you can guide users through different experiences — for example, verifying their email or phone number, setting a password (or requiring a password update if passwords were migrated), or enabling passkeys.

Once you’ve finalized the user experience, remember to update the user’s profile by setting the freshlyMigrated attribute to false.