Replacing the authentication system of a live product is unusual among migrations in that the users are participants. A database migration can be invisible. This one runs through the one screen everybody touches, and the failure mode is a support queue on a Monday morning.
It is very achievable, and the difficulty is sequencing rather than code. The plan below is dull on purpose.
Inventory first, and it is longer than you think
Before anything moves, write down every way a person or a machine currently authenticates. Passwords, obviously — with the hashing algorithm and parameters, which decide whether they can be carried over. Then social sign-ins and their provider identifiers, second-factor enrolments, active sessions, API keys, invitations that were sent but not accepted, password reset links in flight, and the service accounts nobody remembers creating.
Each of those is a path that must either be migrated or deliberately ended, and the ones you forget are the ones that produce tickets. An invitation link that stops working is a small thing that lands on the person least equipped to explain it.
- Password hashes with algorithm and parameters — the deciding factor for a silent move
- Linked social accounts, keyed on the provider identifier rather than the email
- Second-factor enrolments, which usually cannot be moved and need a re-enrolment plan
- Sessions, API keys, pending invitations and outstanding reset links
Carry the hashes, or verify then rehash
If your hashes use a scheme the destination understands, they can be imported as they are and nobody has to do anything. If they do not, the workable pattern is lazy migration: keep the old verifier available, and on the next successful sign-in verify with it once, then immediately store the credential in the new form and never use the old path for that person again.
That converts the migration into something users complete for you, one at a time, with no interruption. Set a cutoff for the long tail, communicate it in advance, and put the remaining accounts through an ordinary reset at the end. A reset for a small dormant remainder is a normal event; a reset for everybody is a support incident with a launch date.
A reset for a dormant remainder is routine. A reset for everybody is an incident you scheduled yourself.
Dual-run, then cut over by cohort
Run both systems at once before you rely on either. Point a small internal cohort at the new path while everybody else stays on the old one, with the new system authoritative for those accounts and the old one still able to serve them. Watch the failure rate on the sign-in endpoint rather than a synthetic test, because the interesting failures come from real browsers and password managers.
Then move in cohorts: staff, then a friendly customer, then a percentage, then the rest. Keep sessions alive across the boundary if you possibly can — invalidating every session at cutover means signing out your entire user base simultaneously, which is a self-inflicted spike of exactly the traffic you least want to test under.
- Both systems live, one authoritative per cohort, for a defined window
- Monitor sign-in success rate and support volume, not just error logs
- Preserve existing sessions across the cutover where the design allows it
- Communicate before, not during, and only about things users must actually do
Have a rollback you have actually tried
The rollback plan is the part that gets written and never tested, and authentication is the worst place for that habit. Decide in advance what triggers a reversal, who may call it, and how long the old path stays capable of serving traffic — which is longer than the migration itself, because the decision to go back may come days later.
The complication is that data accumulates in the new system while it is authoritative: new sign-ups, changed passwords, fresh enrolments. Either the old system can accept that data back or your rollback window is genuinely bounded, and either answer is fine as long as it is the one you chose rather than the one you discover.
Everything here, already built
Sign-in, enterprise SSO, directory provisioning, roles and an audit trail behind one API. Start with the quickstart and have a working sign-in this afternoon.