Migrating Users in an Existing IAM System to WSO2 Identity Server

I have come across several customers, leads, and community developers who are willing to migrate from existing proprietary identity solutions or enterprise solutions to WSO2 Identity Server due to multiple reasons.

Why you should Migrate?

• Inhouse made proprietary solutions may no longer scale with the system evolvements
• Requirements for supporting standards such as OIDC and SAML
• Requirements for regulatory compliance such as GDPR
• The Identity Provider that you have in place does not have the required extensibility to implement your business-specific solution
• COST!!! you don’t want to break the bank to pay the bill.
• Love towards OSS; WSO2 Identity Server is fully Open-Source
• “Pretty Cool and more on the way” for developers and consumers, if you have joined our recent community call and keeping an eye on the slack channel; you’d know what I am talking about.

However, untying strings with a system in place is not easy. Especially when your system is in production, you don’t want to make consumers' lives hard even with the promise of a better-improved system.

Yes, software is prone heartbreaks and can cause severe hardships to all parties engaged.

Migrating users with their passwords

Out of many concerns and considerations on smooth migration, in this blog, I am going to focus on migrating the existing user-base to a WSO2 Identity Server-based platform. When discussing user-base as the subject there are several concerns that I think are important and useful.

• Make sure all the important user attributes from the existing system are available in the new system
• Get rid of any unwanted user entries or stale user attributes. This is a good opportunity to clean up and start fresh. So let’s get the best out of it.
• Ability to use existing credentials of the users to log in to the new system.
• In existing systems, user passwords are stored hashed or encrypted. When the passwords are hashed, it is impossible to migrate credentials to a new system without consulting the user.
• Depending on the business requirements, choose to notify the users that their system is upgraded and enforce password-reset and/or validate existing attributes.

LDAP or AD as the User Directory

If your existing system has an LDAP or Active Directory (AD) as the underline user directory, you are lucky. You can simply plug in the directory store with WSO2 Identity Server as the product has inbuilt connectors to work with LDAP or AD protocols. You can follow the simple steps in WSO2 IS product documentation to configure your directory as the primary user store or as a secondary user store. In this way, existing users can login to the new system seamlessly using the same credentials they have been using.

Users are in a Database System

If your current user base is stored in a database system and if you are not ready to give up this database yet or ever, still you can enable access to the existing users. I can think of multiple ways of achieving this.

1. Configuring SQL queries for each user related operation

If your existing user directory is implemented on top of a WSO2 supported database systems such as MySQL, PostgreSQL, MsSQL, or Oracle, you can plug this database as a database-backed primary user store or secondary user store. And since your schema is different from the WSO2 provided schemas you need to configure each user operation related SQL command under the user store configuration. Refer JDBC sample property with SQL queries section in the product documentation on configuring JDBC based user store properties.

2. Writing a custom user store manager

If it is too much to figure out each SQL command and/or if your schema doesn’t have the necessary table entries to support each operation, you can still plugin the same database as the user directory. You can write a custom user store manager overriding existing user operation related implementation and implementing tailor-made functionalities for your schema. Once you plug in the existing user base with a custom user store manager, you can seamlessly consume all the services available in the WSO2 Identity Server.

Federated Authentication and JIT Provisioning

Another approach is having a planned migration time for all the accounts with a grace period. If your existing system supports standard federation protocol such as SAML/OIDC or WSO2 3rd party federation system you can implement this mechanism. You can configure the existing Identity Provider as a federated IDP for the WSO2 Identity Server and configure login to your application via the WSO2 Identity Server. For your applications enable the option to federate to existing IDP via WSO2 IS for the authentication as well as user credentials in the local system(basic authenticator). At the same time enable Just-In-Time provisioning for these login flows with a `Prompt for username, password and consent` option.

With these configurations in place, when a user tries to log in to the application, he will be asked to provide new credentials to the system at the 1st login time and a new identity will be created in the WSO2 IS based system. Additionally, user can verify and update any attribute during this flow. Next time onward the user can use the new credentials provisioned to the WSO2 IS based system to log in to the application(s).

You can orchestrate this flow with custom Adaptive Authentication scripts to make a rich experience for your users. After a grace period, when all the users are provisioned to the new system, you can remove the option for federating to the existing Identity Provider from WSO2 Identity Server and deprecate the existing Identity Provider.

Tools to Manually Create users in the new System

You can write a simple tool or a script to invoke provisioning APIs of the WSO2 Identity Server for each user identity in the existing system. For example, you can wrap SCIM 2.0 User create REST endpoint in the WSO2 Identity Server with the Ask-Password option.

Optionally, if the passwords are encrypted in the system and you have the keys to decrypt them, you can programmatically decrypt and invoke SCIM 2.0 User create REST endpoint in WSO2 Identity Server, with the decrypted password.

I hope you got an idea of a couple of ways to migrate existing users to a new system built with WSO2 Identity Server. Further, you can read about Transition Strategies for IAM which discusses the migration of IAM solutions in different aspects.

Thanks for reading and stay tuned.