See blog Menu
Smart Hooks: What is a User Migration Hook?

richard.chetwynd | March 23rd, 2021

Over the past few years, there’s been a significant increase in the number of consumer-facing companies looking to outsource identity storage and authentication for users of their software applications. In the identity industry, this is commonly known as Customer Identity and Access Management (CIAM).

The CIAM shift is primarily driven by increasing complexities to maintain and secure user directories, as well as staying current with the latest authentication trends and technologies. Think social or passwordless logins, risk-based adaptive multi-factor authentication, and biometrics, such as Face ID.

Rather than grow an inhouse identity team, many consumer-focused companies elect to outsource this function to a cloud identity provider, like OneLogin, so they can focus on building and selling their core competency. Focus is the key to success, so clearly outsourcing makes a lot of sense.

As companies embark on their identity and authentication upgrade journey, there are many aspects to consider such as branding and customer experience, but the often overlooked elephant in the room is the question - how do we migrate all of our users? As they dig into this question, they quickly realize that migrating user passwords is quite possibly the most complex part of the project.

What are my user migration options?

Generally speaking, there are two options for migrating users. It can be done in a single bulk upgrade or progressively over time. The choice of which path to take is often dictated by how user passwords are stored.

For example, if for some unforgivable insecure reason, passwords are stored in plain text, then it makes it very easy to perform a bulk migration. However, if passwords are stored using a proprietary hashing algorithm that is not supported by the destination CIAM provider, then a progressive user migration is required.

OneLogin has solutions for both bulk migration (when the password has been hashed in one of a selection of supported formats) and progressive migration by utilizing a User Migration Hook.

How does a User Migration Hook work?

The User Migration Hook is part of OneLogin’s serverless Smart Hooks platform. It allows for a customized connection to any external database or Identity Provider (IDP) when users authenticate. This is extremely useful as it allows you to validate user passwords against another system before creating them in the OneLogin directory and continuing with the login.

How a user migration hook works

After a user enters their username and password, a check is performed against the OneLogin user directory. If the user is not found in OneLogin, then the User Migration Hook is triggered.

Given that the User Migration Hook is part of the Smart Hooks platform, this means a customizable script can be executed to validate the username and password in an external system. The User Migration Hook only runs once for each user, meaning that the next time the user authenticates, they’re added to the OneLogin user directory and the user migration is complete.

What about other user attributes?

It’s often the case that you want to store other information about the user, perhaps their first and last name, email address, or phone number.

The User Migration Hook also supports the migration of these standard user attributes as well as any custom attributes such as: a customer ID, preferences, or any other reference information.

Optimizing for experience

You can only imagine the mess of support tickets from confused customers if you migrated users without their passwords and sent out a blanket email asking them to change their password.

The goal is always to upgrade without impacting the user experience, which means no downtime, and no unexpected prompts to change a password. This would be the case if you were not able to migrate passwords over to your identity provider.

OneLogin’s User Migration Hook is an extremely powerful tool to use when you embark on a CIAM upgrade project. It provides an efficient way to validate a username and password in an external system, and then creates a new user record in a modern cloud-based directory when users authenticate. The best part is when the entire migration process is seamless and the user has no idea they were moved to a new directory.

Interested in learning more about Smart Hooks? Check out our Smart Hooks product page or get in touch – we would love to work through your use case and help solve problems using Smart Hooks.

OneLogin blog author

Rich Chetwynd founded Litmos, the market-leading learning technology company, as well as ThisData, a data security company leading the way in Account Takeover (ATO) attack detection. After ThisData was acquired by OneLogin in Summer 2017, Rich began working with the OneLogin engineering team with a focus on adaptive authentication.