Migration rollback plan

You're migrating from Auth0 (or Cognito, Clerk, etc.) to Olympus. Things go wrong. Rollback plan.

Why you need one

Common migration failures:

Users can't sign in (password hash incompatibility).
Federated providers misconfigured.
App tokens incompatible.
Performance issue at scale.
Data corruption during import.

Without rollback: extended outage, support load, churn.

With rollback: revert, debug, retry.

Pre-migration setup

Run in parallel

Don't decommission Auth0 immediately. Run both systems for 30+ days.

New signups: go to Olympus only.
Existing users: federate Olympus to Auth0 for transition.
Optional: dual-write user changes to both systems.

App routing

// Your app: choose which auth system to use
const useOlympus = featureFlag("olympus_auth");
if (useOlympus) {
  redirect(`${OLYMPUS_URL}/login`);
} else {
  redirect(`${AUTH0_URL}/login`);
}

Feature-flag controlled. Flip flag to revert.

Roll-back triggers

Pre-define what triggers rollback:

rollback_if:
  - login_success_rate < 95%
  - api_error_rate > 5%
  - support_tickets_per_hour > 50
  - manual_decision_by: [oncall, eng-lead]

Don't debate during the incident. Trigger met → rollback.

Rollback steps

# scripts/rollback-to-auth0.sh
set -e

# 1. Flip the feature flag
curl -X POST $FLAG_API/flags/olympus_auth -d '{"enabled": false}'

# 2. Apps now route to Auth0
# 3. New OAuth tokens are Auth0 tokens
# 4. Old Olympus tokens still work for ~30 min (until they expire)

# 5. Communicate
echo "Rollback complete. Auth0 is primary again." | mail oncall@your-domain.com

# 6. Verify
curl https://your-app.com/api/health  # should succeed

Should take ~1 min.

What's affected during rollback

Users who just signed up in Olympus: are they in Auth0 too?
- Dual-write helps here.
- Without: they can't sign in post-rollback. Manual reconciliation needed.
Active sessions in Olympus: still valid until expiry.
- After rollback, no new Olympus tokens. Users gradually fall off.
Recovery flows in-flight: complete or abandoned.
- Document policy: redirect users to start over with Auth0.

Data sync during rollback

If users registered in Olympus during migration:

// Export Olympus identities created during migration
const newUsers = await db`SELECT * FROM identities WHERE created_at BETWEEN $startMigration AND $rollback`;

// Import into Auth0
for (const u of newUsers) {
  await auth0.users.create({
    email: u.traits.email,
    name: u.traits.first_name + " " + u.traits.last_name,
    // No password, they'll need to reset
  });
  await auth0.users.sendChangePasswordEmail(u.email);
}

Users get "reset your password" emails. Friction, but recoverable.

Communication during rollback

Subject: Brief authentication issue resolved

We experienced authentication issues earlier today. We've rolled back to
our previous system. Some users may need to reset their password.

If you can't sign in: click "Forgot password" to reset.

Sorry for the inconvenience. Full details: https://status.your-domain.com/...

Don't say "we tried to migrate and failed." Save details for postmortem.

After rollback

Don't immediately retry. Debug:

Postmortem: why did migration fail?
Test fixes in staging.
Practice migration again in staging.
Schedule second attempt with fixes.

May take weeks. Don't rush.

Permanent vs temporary rollback

Temporary: fix and try again.
Permanent: maybe Olympus isn't right. Stay on Auth0. Document why.

Either is OK. Don't migrate just because you "started." Migrate because it's better.

Test the rollback

Before migration go-live:

Pretend migration succeeded.
Pretend it broke.
Run rollback script.
Verify Auth0 is serving.
Compare logs.
Time the process.

Practiced rollback is reliable. Theoretical isn't.

Hidden gotchas

OAuth client config

If your apps' OAuth clients have changed during migration (new client_id, etc.), rolling back to Auth0 means:

App configs need to revert too.
Or maintain dual configs throughout.

Versioned config helps.

Tokens issued

Tokens issued by Olympus are signed with Olympus's keys. Auth0 won't validate them.

After rollback, Olympus tokens become invalid sooner. Plan for ~30 min of brief "your session expired" UX.

Email courier

Both systems shouldn't send overlapping emails. During parallel run, choose one for transactional. After rollback, ensure that one is alive.

Budget for rollback

Plan a few hours of dev time after rollback for:

Communication.
Data sync.
Postmortem.
Customer support.

Not just "press button." It's coordinated work.

Migration rollback plan

On this page