Auth migrations get scoped twice. The first scope is the one written when the project starts, and it is almost always wrong. The second scope is the one the team learns about by week three, when they discover what the existing system was actually doing for them. The gap between the two is where every auth migration burns its budget.
This is a working list of the things that should be on the scope from day one but rarely are. None of them are clever. They are the boring questions that, asked early, prevent the embarrassing surprises that show up too late to absorb.
Inventory before you plan
The first move is not designing the new system. It is taking honest inventory of what the current one does. Most teams skip this and pay for it later.
Walk through every place in the codebase that calls the auth provider's SDK. List every webhook the provider currently sends you, including the ones nobody on the team remembers wiring up. Pull a list of every social provider, every SAML connection, every custom MFA configuration, and every API user. Find the support tickets from the last twelve months that touched auth in any way and read them.
The list will be longer than expected. That is the point. The migration plan that was sized off a quick code search is the migration plan that runs over by months.
Distinguish identity from authorization from session
These three things often live in the same provider but they are very different problems.
Identity is who the user is. Authorization is what the user is allowed to do. Session is how a logged-in browser proves continuing access to your servers.
A migration that lumps them together usually ends up rebuilding all three at once, which is the most expensive way to do it. A migration that separates them can move identity to a new provider while keeping the existing authorization model intact, or move session handling without touching identity. The smaller scopes finish in weeks. The combined scope finishes in quarters.
Decide explicitly which of the three you are migrating, and which you are leaving alone for now. The decision is harder than it sounds, because the three are usually entangled. The conversation that separates them is the most important hour of the project.
The password migration problem
Every migration eventually hits the same wall. The hashed passwords from the old provider are stored with the old provider's algorithm and salt. Most providers will export them. Some will not.
The choices for handling this are limited and each has a tax.
A bulk re-hash on import. Possible only if the old provider exports both the hash and the algorithm in a form your new system understands. Some do. Some do not. Even when possible, it requires careful handling because a leak of the export is a leak of every password.
A just-in-time re-hash on first login. The user logs in once on the old hash format, your system verifies it, then writes a new hash in the modern format. Clean for users, slightly more code, requires keeping the old verification path around until enough users have migrated.
A forced password reset for everyone. The simplest from an engineering perspective and the worst from a customer perspective. For consumer products this is rarely acceptable. For enterprise products with technical buyers it can be fine if framed clearly.
Pick one explicitly, communicate it explicitly, and set a real deadline for sunsetting the legacy path. Migrations that leave the old hash format running indefinitely accumulate technical debt that will outlive the project that created it.
MFA and recovery deserve their own plan
The most common bug in auth migrations is users who lose their MFA on cutover and cannot recover their account. Recovery flows are the part of auth that gets the least testing in normal operation, because they fire rarely and on real users.
Plan the MFA migration as a separate, named workstream. Decide whether MFA seeds carry over (they often cannot), whether users will need to re-enroll, whether recovery codes survive the migration, and how support handles users who cannot prove identity through the new flow.
Run the recovery flow yourself, end to end, on a real account, before the migration ships. The amount of time this takes is not the budget you should plan for. The number of meetings between deciding to do it and actually doing it is the real cost. Push for it on day one.
SSO is a customer-by-customer migration
If you have enterprise customers using SAML or OIDC SSO into your application, each one of them is a small project. The customer's identity provider has its own configuration, its own claim mappings, its own quirks. The configuration in your old auth provider was tuned over time and is rarely documented.
The right approach is to enumerate every SSO connection, decide which customers get migrated together, and schedule a maintenance window with each one individually. The wrong approach is to assume that "we'll just port the connections" is a single sprint. It is not. Each connection is a small relationship-management exercise as much as it is an engineering task.
Plan the cutover before you build
Most auth migrations get to the cutover plan after the new system is built, which is two months too late. The plan should exist on day one, even if it is rough.
Decide explicitly whether the migration is a single-day cutover or a parallel-running period. Decide what happens to in-flight sessions. Decide what the rollback looks like in the first hour, the first day, and the first week. Decide who can declare a rollback and what the criteria are.
The cutover plan informs the design of the new system. A system that cannot run in parallel with the old one for two weeks is a system that has to land on a single weekend, which is a different and harder engineering problem.
Sunset the old provider explicitly
The last and most often skipped piece. After the new system is running, the old provider is still on a contract, still seeing some traffic from forgotten code paths, and still costing money.
Set a date for the legacy provider's account to be closed. Walk every code path that still touches it and migrate or delete it. Run a real test where you revoke the legacy credentials in a staging environment and confirm nothing breaks.
The migration is not done when the new system goes live. It is done when the old system is gone. Teams who skip this last step are the teams whose CTOs find out twelve months later that they have been paying ten thousand a month for an auth provider nobody is using.
A scope that survives contact with reality
A reasonable scoping document for an auth migration includes inventory of the current system, an explicit choice of which of identity, authorization, and session is in scope, a plan for password and MFA handling, a customer-by-customer SSO plan, a cutover and rollback plan written before the build starts, and a sunset plan for the legacy provider.
A team that drafts that document on day one tends to land within thirty percent of the original budget. A team that drafts it on week six tends to land at twice the budget, on a date that keeps moving.
The work to get the scope right is much smaller than the work to recover from getting it wrong.