Have you ever wondered what steps you need to take to migrate data from one Identity Provider to another? You’re not alone, we got you covered. While the details presented here are for the specific case of Forgerock to Cognito migration, the general idea remains the same for all migrations: extract, transform and load.
In this tutorial, we’ll walk you through the steps of migrating an existing Forgerock identity provider userbase to AWS Cognito. We’ll see how to extract the user data, transform it to meet our needs and then import it to a new Cognito user pool. We have a lot of ground to cover, so let’s get started.
Extract data from Forgerock
First off, we’ll need some users from Forgerock.
We can do an export with the following command:
Forgerock provides a lot of columns for the users but in this tutorial we’ll focus on the following ldif export:
As you can see, the userPassword is not clear. We’ll come back to this later in this article
Create a DynamoDB table
In this table, we will store the users we exported from Forgerock. Since we don’t know the user passwords from the export, we’re going to use this dynamo table to store the user data, including the hashed password. We’ll also have to create a Lambda function to be able to check the hash at runtime. More on this later. For now, let’s create the dynamo table:
Transform to DynamoDB format
Now that we have the migrationTable created, we need to import the ldif data into our table. For this we used java, see below a rather large snippet of code:
Click to see code
So far we haven’t really done anything Cognito related, just preparation work. Now we get to the fun part.
While the export was fairly simple, there are a couple of steps we need to perform to ensure successful just in time migration. Meaning that we will migrate the user at the moment he tries to log in. The overall flow would look something like this:
- Create a Cognito User Pool
- Add code that will do the migration(UserMigration Lambda function)
- Check that migration was done and users are able to log in
Let’s add some details on each of the steps.
Create a Cognito User Pool
This can be done in more ways, but we’ll use the aws ui to accomplish this. If you go through the steps to create a user pool, in the end you should reach to a screen that looks more or less like the following:
One interesting fact is that in the user pool you can add custom attributes. Let’s say that we need the uid from the old identity provider. We can add this custom attribute to our Cognito user pool with the following command:
User pool id can be taken from the aws cognito ui.
Great, now we have a user pool, which can have a custom attribute created when we do a user migration.
Load data using UserMigration Lambda
Now we need to create a function that will do the migration of the user from our dynamo table to the cognito user pool. Below is a snippet of the migration function:
Check user migration
Great, we have everything set up, it’s time to test if the user is able to log in and if the migration is done properly. If all went well, you can go to your cognito pool App Client Settings and launch the Hosted UI. You should be presented with a screen like below:
In this screen you need to enter a user/password combination that you have imported in the dynamo table. For our example, the hashed password is Password@123
Now, let’s go to the Users tab and check if our user was migrated.
Seems all is in order. Now let’s check the details for the user, particularly, the custom uid attribute:
All seems in order, our custom attribute was imported successfully and the user is now managed by AWS Cognito.
One thing to point out is that the UserMigration Lambda will also run on subsequent user logins. With the current setup in place, we cannot tell when all users have been migrated. One approach to figure out which users have already been migrated is to set a flag in the dynamo table each time we migrate a user. That way when all users have been migrated, we can just remove the UserMigration lambda trigger.