Rolling migration
With rolling migration, you can gradually transfer user data from your old system to Authgear. For example, you can move users with certain feature flags, like users from specific regions. Or configure your application such that all new sign-ups use Authgear.
In this guide, you'll learn how to migrate users from your old authentication system to Authgear using the rolling migration approach.
For this guide, we'll be referring to the source code for a demo Express.js app. The demo app is an application that is moving new users sign ups from an old authentication system to Authgear.
Step 1: Deploy Middleware to Support Authgear Session and Old Authentication System
The first step for setting up rolling migration is to implement a middleware or server-side logic that supports both Authgear session and your old authentication provider.
To do this, implement code to verify both access tokens (sessions) from your old authentication system and Authgear:
Step 2: Enable Authgear for Portion of your Users
Now that you have your app set up to use both Authgear and your old authentication system, you should decide what portion of your users you want to use Authgear.
For our demo app here, we'll be enabling Authgear for all users signing up after the 2nd of March 2025 (2025/03/02). You can use another feature flag, such as the location (region or country) of a user.
To be able to determine when a user signed up (or their region or country) before they log in, you may need to set up some external database with their loginID (username, email address, phone number, etc) and the feature flag (sign-up date, country, etc). For our example, we'll use a simple JavaScript object to create a demo user who registered on the 20th of March, 2025.
Enable Authgear sessions in middleware
For the demo app, we'll use a simple conditional statement to enable Authgear sessions for users who meet the condition for the feature flag (users who signed up after 2025/03/02).
Then, authenticateToken
can be used as a middleware to protect pages that should be viewed by authenticated users only.
Step 3: Set up your Application to Signup/Login with Authgear and your Old Provider
Update your application to allow users to sign up and log in using Authgear's authentication flow. It is also important to continue supporting your old authentication provider so that old users can still log in.
However, you should disable the signup feature on your old system so that all new user data goes to Authgear.
Now, using the feature flag again, we can determine what authentication flow to show a user:
We offer SDKs for the following platforms to integrate Authgear into your app seamlessly:
Alternatively, you can manually add Authgear to any app as an OAuth 2.0 provider.
Conclusion
The following points are also worth noting while implementing rolling migration:
For any users who already signed up using the old system and are moved to Authgear via User Import API, they need to be logged out and will be required to log in using the Authgear authentication flow in order to start using Authgear session. Remember to add your feature flag to these users so your application can select Authgear for them.
Users who are not feature-flagged will continue to see the legacy authentication system. They are not logged out and can continue using their existing session.
Disable new signups in the legacy system so that all new signups should go through Authgear.
For new users who go through the new sign-up flow using Authgear, a record in the legacy system should be in place to handle an edge case where the user tries to log in on another device with an older app version.
Last updated
Was this helpful?