Install the published add_auth package through your Rails app’s Gemfile, then rehearse these changes in an isolated copy of the app. Enable only the capabilities you need. Review the release status and upgrade procedure first.
Stop on ambiguity and recover from the last reconciled checkpoint.
Keep a reviewable execution record
Record the owner, exact source/configuration/package/app/client revisions, target environment, expected account/association counts, last successful batch cursor, recovery snapshot, compatible rollback artifact and stop procedure. Keep detailed record references in protected operator storage. Do not include hashes, tokens, cookies or provider payloads in the report.
Diagnose the observed symptom
| Symptom | Action and verification |
|---|---|
| Preflight is incomplete or unsupported | Resolve its bounded inventory/module/verifier finding. Run static and effective inspection again in the isolated source; a complete inventory still does not authorize migration. |
| Normalized email collision | Stop the batch. Resolve ownership using the host’s protected operator process; never merge by normalized email. Repeat the same checkpoint and reconcile IDs and associations. |
| Process stopped after account writes | Resume the same reviewed manifest from the saved cursor. A committed batch may repeat; unchanged accounts must remain unchanged and no mail may be sent. Source edits or conflicts must retain the previous checkpoint. |
| Source password changed during conversion | Keep source authority, install the reviewed source-write bridge and drain incompatible workers. Retry only after rechecking current source values under the account lock. |
| UUID foreign-key migration fails | Check actual User primary-key and generated reference types before migration. Preserve the original IDs. Do not cast UUIDs to integers or remove constraints to make the migration pass. |
| An old reset, confirmation or unlock link fails | Use the new request form and send a fresh proof to an independently eligible address. Old URLs may redirect to that form; old query proofs must not be forwarded or accepted. |
| Provider callback or native handoff fails | Check the retained library registration, issuer/audience, CSRF/state/nonce, exact callback and current client verifier. Retry a new transaction. Never bypass verification or auto-link by email. |
| An expired native session still appears signed in | Verify the next authenticated API call rejects it and the client clears only that session’s secure storage/cache/widget state. A newer account must survive an older request’s 401. |
Roll back to compatible code
The rollback target must retain canonical credential, policy and revocation readers. Restoring a previous page or worker build is safe only if it understands the current authentication schema and retired-source write fence. Do not switch migrated accounts back to an arbitrary Devise deployment.
After password reset, address confirmation, provider unlink, deletion or global revocation, start the compatibility build in a fresh process. The current password/address must remain current; old passwords, consumed proofs and revoked browser/mobile credentials must remain invalid. Removed provider bindings and deleted users must stay removed.
If the earlier build cannot represent current state, stop authentication intake and use forward repair with fresh sign-in. A full database restore is disaster recovery requiring reconciliation of later changes and revocation records, not a routine code rollback.
Retire compatibility only after observation
Choose an explicit observation and client-retirement horizon before a real switch. Exercise scheduled auth mail, push workers and installed clients during that period. Remove unreachable code/dependencies first; deleting compatibility columns or signing keys is a separate reviewed change after the horizon closes.
Next, rerun the full migration verification and preserve its receipts. Use private security reporting if a retired credential regains access.