Give AI the current login, token, session, authorization, recovery, client, and deployment evidence. Ask it to map issuers and verifiers, describe the exact security delta, build a compatibility matrix for existing and new credentials, and split the migration into dual support, new issuance, observation, and retirement. Every phase needs negative-path tests, telemetry, a stop condition, and a recovery action.
Authentication Is a Distributed State Machine
Authentication is not one login endpoint. It includes credential enrollment, password or identity-provider verification, MFA challenges, session creation, token issuance, cookie policy, refresh, authorization context, logout, revocation, password reset, email verification, account recovery, and service-to-service credentials. Web, mobile, command-line, worker, and partner clients may each hold different proof of identity for different lifetimes.
That state crosses releases. A session created yesterday may reach tomorrow's verifier. A refresh token issued by the old service may be exchanged after the new issuer deploys. A password-reset link sent before the release may be opened afterward. Safe migration therefore means deciding which old artifacts remain valid, where they are accepted, how their privileges are reconstructed, and when they expire or are revoked.
Use AI to assemble repository evidence and expose missing cases. Do not use it as the source of truth for signing keys, active-session counts, identity-provider configuration, deployed client versions, revocation behavior, or acceptable security tradeoffs. Confirm those facts with configuration inventories, secret-management metadata, logs, dashboards, provider consoles, and responsible owners. Never paste secret values into a prompt.
The Five-Part Migration Plan
Locate every issuer, verifier, session store, user store, middleware layer, authorization mapper, identity provider, callback, client, worker, and administrative path. Record token and session lifetimes, cookie names and attributes, key identifiers, accepted issuers and audiences, revocation mechanisms, and currently deployed client versions from evidence. Include password-reset links, email-verification links, MFA enrollment, recovery codes, API keys, and service credentials where they share the migration boundary.
Write current and target behavior side by side. Cover credential format, signature or session validation, issuer, audience, claims, subject mapping, expiry, refresh rotation, cookie scope, CSRF protection, MFA policy, logout, revocation, error behavior, rate limits, and authorization context. State which properties become stricter, which artifacts change, and which existing sessions must remain valid. A format change that silently drops tenant or role context is not compatible even if login succeeds.
Evaluate old and new clients against old and new login services, then evaluate credentials issued before and after the change against every verifier that can receive them. Add refresh, logout, revocation, reset, verification, MFA, and SSO callback rows. Mark combinations as expected, impossible by deployment order, or unsafe. Every accepted combination needs an explicit validation rule and test; every impossible one needs a release gate that makes it impossible.
Accept the old and target formats only where a deliberate compatibility window requires both. Issue the target artifact to controlled cohorts after all relevant verifiers understand it. Observe login, refresh, authorization, revocation, and recovery outcomes while measuring remaining old-format use. Retire old issuance first, then old validation only after the maximum lifetime, revocation policy, client adoption, and rollback window have cleared. These are separate security decisions, not one deployment checkbox.
Specify automated and manual proof for successful and rejected flows, the first cohort, monitoring window, owner, approval gate, error and abuse thresholds, and pause signal. Decide the recovery action for each phase: stop target issuance, route login back, keep dual verification, revoke a compromised credential class, restore a configuration version, or require reauthentication. A generic “roll back the deploy” is insufficient once new credentials have been issued.
A Minimal Compatibility Matrix
Separate issuance from verification. That distinction makes the dangerous overlap visible: a service can be rolled back while credentials created by its newer version remain in users' hands.
| Artifact or flow | During migration | Required rule | Proof |
|---|---|---|---|
| Existing session → new verifier | Expected | Preserve identity and authorization context until the stated expiry or revocation event | Pre-migration session fixture against the new verifier |
| New credential → old verifier | Prevent or support explicitly | Do not begin target issuance until every reachable verifier can handle it | Deployment gate plus mixed-version integration test |
| Old refresh token → new issuer | Expected during window | Exchange once under the intended rotation and replay rules | Refresh, replay, expiry, and revocation tests |
| Old reset link → new recovery flow | Policy decision | Honor or invalidate deliberately without bypassing single-use and expiry checks | Pre-release link fixture plus reuse and expiry tests |
| Logout or revocation → all verifiers | Required | End access within the documented propagation window | Cross-service revocation and stale-cache test |
Ask what happens if target credentials have been issued to 10% of users and the issuer must roll back while several verifier instances are still on each version. Then ask whether logout, role removal, password reset, and account disablement still terminate access as promised. If the plan only covers a fresh login, it does not cover the migration.
Dual Validation Must Not Mean Downgrade
A compatibility window sometimes requires two credential formats or key generations. Route them through explicit, bounded validation rules based on unambiguous metadata such as the configured issuer and key identifier. Apply the intended algorithm, audience, expiry, nonce, and authorization checks for that class. Do not let a failed target-format check fall through to a weaker legacy parser, and do not accept a broader set of claims merely because both paths are enabled.
Keep issuance and acceptance controls separate. Stop old issuance before removing old acceptance, measure both paths independently, and attach an owner and removal condition to every temporary verifier. If the two systems map users, tenants, roles, or assurance levels differently, define and test that translation rather than treating matching email addresses as proof of identical identity.
Test the Lifecycle, Not Just Login
The useful test suite begins with baselines created before the migration: active browser sessions, mobile refresh tokens, pending recovery links, enrolled MFA factors, disabled accounts, recently changed roles, and revoked credentials. Exercise them against the mixed versions that can coexist. Verify successful flows and exact rejection properties without asserting sensitive values in logs or test output.
Cover invalid signatures, wrong issuer and audience, expiry, clock boundaries, replay, revoked sessions, reused reset links, missing or excessive claims, tenant separation, privilege changes, logout propagation, and rate limiting. Confirm that logs and metrics distinguish expected legacy traffic from attacks without recording passwords, raw tokens, cookies, recovery codes, or unnecessary personal data.
Copy-Paste Prompt: Auth Migration Analysis
"Plan this authentication migration before editing files. Desired outcome: [outcome]. Current login, token, session, authorization, recovery, and identity-provider code or configuration paths: [paths; never include secret values]. Known web, mobile, service, worker, and administrative clients: [details]. Deployment topology and version overlap: [details]. Known credential and session lifetimes, active-version evidence, and revocation behavior: [evidence or unknown]. First inspect repository evidence and list production or provider facts that require owner confirmation. Then output: (1) trust-boundary inventory with issuers, verifiers, stores, clients, and artifacts, (2) current-to-target security and behavioral delta, (3) compatibility matrix for old/new clients, issuers, verifiers, sessions, refresh, logout, revocation, reset, MFA, and SSO where relevant, (4) accept-issue-observe-retire phases, (5) positive, negative, mixed-version, authorization, and lifecycle proof per phase, (6) cohorts, telemetry, gates, and stop conditions, (7) recovery action per phase including credentials already issued, and (8) old-path removal criteria. Flag downgrade paths, ambiguous identity mapping, secret exposure, and invented production assumptions. Do not implement yet."
Resolve the unknowns before requesting a patch. Then implement the smallest reversible phase and review code, provider configuration, infrastructure, documentation, dashboards, and operational procedures together. Authentication behavior often changes outside the application repository, so a locally correct diff is not complete migration evidence.
Common Failure Modes
The first is updating login while forgetting refresh, logout, recovery, or service credentials. The second is issuing a target credential before every reachable verifier accepts it. The third is retaining a legacy validator that silently weakens checks. The fourth is preserving authentication but losing tenant, role, or assurance context. The fifth is relying on deploy rollback after target credentials already exist. The sixth is logging raw credentials to make migration debugging easier.
The correction is an evidence-backed sequence: map the full lifecycle, state the security delta, prove mixed versions, separate issuance from acceptance, observe both old and new paths, preserve a recovery route for already-issued artifacts, and remove compatibility code only after its explicit gate clears.
Conclusion
AI is useful for tracing authentication surfaces, comparing validation paths, generating lifecycle tests, and challenging rollout order. The safety comes from verified trust boundaries and deliberate compatibility. Treat an authentication change as a migration of live identity artifacts across independently deployed issuers, verifiers, and clients—not as a rewrite of the login handler.
Continue with Case Study: Refactoring Legacy Authentication with AI, The AI API Contract Change Plan, AI Regression Test Plan Template, and AI-Assisted CI/CD.