Approaches to user account migration

  • Migrate everyone at once. This is also known as a “big bang” migration. Here, you have one cutover. At one point in time everyone is authenticating against the old system. Then the migration occurs, and everyone is then logging into FusionAuth.
  • Segment your user base and migrate each chunk, one at a time. This approach requires multiple cutovers. First, you move the engineering team from the legacy system to FusionAuth. Then, you move the QA team. And so on and so forth.
  • Migrate when a user logs in, also known as a “slow migration”. There are two cutover points with this choice. First, you cut over the application (or applications). Next at authentication, the user account data migrates and it is now stored in FusionAuth. There are many data migration events, as users migrate one by one.

The big bang migration

  • Map user attributes from the legacy system to FusionAuth. As part of this, decide which applications and tenants will need to be created in FusionAuth beforehand.
  • Build and test a set of migration scripts. Ensure that migration accuracy meets your needs. Figure out how long a migration takes.
  • Test application changes required to point users to FusionAuth for login, registration, and other auth needs.
  • When you are ready to migrate, bring your systems down or to a mode where authentication is disallowed.
  • Run the previously tested migration scripts.
  • Release the application changes, which perform the cutover. Now the system of record for all your users is FusionAuth.
  • If you manage the window when login will not be available, and your user base isn’t global, the migration can have minimal impact on user experience. We all want to avoid those angry emails, right?
  • This approach has a known duration. When you have completed the migration, you’re done. You may keep the original system up for a while to make an emergency rollback possible, but beyond that you can shortly shut it down.
  • In a similar vein, with the “big bang”, you run two production systems for a short period. Only long enough to assure yourself that you don’t need to roll back, basically.
  • If the old system needs to be migrated away from by a certain timeframe, due to an upcoming license renewal or other business factor, this migration provides assurances that the deadline will be met. Don’t forget to allow some buffer for unexpected issues, though!
  • Anyone accessing account data, be they employees or contractors, will need to switch their working routines only once. There’s one system of record at any moment in time for all your users.

Segment by segment migration

  • The type of user; for example: administrator accounts, employee, free user, premium account.
  • The source of the account data. This is common when you are migrating users from multiple siloed user data stores into one.
  • Applications. You may have a variety of different applications and you might want to move over all the users of each application at a time. The cutover changes will be limited to each application and take place when the account data migration completes.
  • Instead of one project, you have multiple, with N downtime periods and cutovers to manage.
  • In some cases, there may be no useful natural divisions among your user accounts.
  • If the segment numbers are unbalanced, the extra effort to migrate some first may not be worth it. If you have one popular application and two nascent apps, migrating the latter won’t really help remove risk from the migration of the former.
  • Because you have multiple migrations, this approach takes more calendar time to complete. Depending on what you are migrating from, you might end up running FusionAuth and the legacy system or systems for a longer period of time.
  • Depending on user segmentation, the application cutover might be complicated. For example, if you divide your users by type and initially migrate admin users, the application needs to be smart enough to dispatch admin users to FusionAuth and other users to the old system.

Slow migration

  • Map your user attributes from the old system to the new system.
  • Set up a connection between the legacy system and FusionAuth. This could be an API call or some other way to pass authentication information from FusionAuth to the old system, and get back an authentication response.
  • Modify the application or applications to send users to FusionAuth for authentication. Test these changes before rolling them out, including that the connection created above works. If you previously used OIDC or SAML to connect to the legacy system, this effort may be minimal.
  • At this point, FusionAuth receives all user authentication requests. It delegates the initial authentication for each user to the legacy system.
  • When the first call happens, the old system returns account data if the user presented valid credentials. FusionAuth creates a new user with the data.
  • When this user logs in subsequently, FusionAuth responds; it is now the system of record, the user has been migrated, and the old system no longer has that particular user’s information.
  • You are passing a plaintext password or other credential from FusionAuth to the legacy system. Make sure you take care of this precious cargo using TLS or some other form of on the wire encryption. If possible, keep it from traveling over the internet by placing FusionAuth and the legacy system on the same network.
  • The legacy user management solution has to be able to provide an authentication API or support LDAP. You may need to extend it to do so, and this may not always be possible.
  • The timeline is a lot longer for this kind of migration. You also must run both FusionAuth and the original system for that period of time. If you have a deadline or the old system is creaky, this may be painful.
  • Internal users accessing user account data will need to look in both places to find a user during the migration, though you can write tooling to check both systems from one application.
  • Rollback is more complex. There are two systems of record, one for users who have been migrated and one for users in the legacy system.




Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store



FusionAuth solves the problem of building essential user security without distracting from the primary application.