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.
Keep each existing account and replace its authentication wiring in a rehearsed sequence.
In the Rails app’s Gemfile, select the reviewed 0.3 release line:
gem "add_auth", "~> 0.3.0"Run bundle install from the app’s root. Confirm bundle exec ruby -e 'require "add_auth"; puts AddAuth::VERSION' reports the selected version before generating files.
Establish the source profile
The initial verified source is Devise 5.0.4. The destination uses Rails 8.0 or 8.1, Ruby 3.3, 3.4 or 4.0, and SQLite or PostgreSQL with one authentication connection pool. Earlier runtimes need their own framework upgrade first. UUID and integer account IDs are covered; arbitrary key and multi-scope conversions need separate work.
Inventory controllers, account restrictions, mail, workers, provider libraries, native clients and every credential reader. Confirmation, lock state and identity ownership need explicit mappings. Do not treat an email match as permission to combine accounts.
Run both inventories
In an isolated copy of the source app, with AddAuth 0.3.0 installed:
bundle exec add_auth-preflight --root .
RAILS_ENV=test bin/rails add_auth:devise_preflightThe static command reads source without booting Rails. Effective inspection boots the isolated host and inspects its actual schema and options. A complete report still says migration_ready: false: inventory is evidence for review, not permission to switch. Resolve reported unsupported modules, custom verifiers and identifier collisions.
Choose the conversion path
| Source | Work to review |
|---|---|
| Already aligned with Rails authentication | Retain the existing User, Session and Authentication contracts; compare inclusion order, cookie readers and custom controllers with the generated Rails baseline. |
| Standard or customized Devise | Prepare additive canonical account/session fields. Generate the Rails authentication baseline in a disposable reference app and adapt its files selectively; never overwrite populated models and custom controllers blindly. |
Expand without switching
In the isolated source host:
bin/rails generate add_auth:devise_accountsReview the generated migration before RAILS_ENV=test bin/rails db:migrate. It adds canonical account fields and a unique normalized email index, preserving source columns and account IDs. It does not convert accounts, change models or select authority. Verify the old app still boots and authenticates after expansion.
Rehearse the complete destination
Use the password procedure, then enable only the account, provider and mobile features the app needs. Reconcile IDs, associations, current credentials, restrictions and provider subjects before switching all routes and workers together.
The default switch invalidates Devise/remember cookies, legacy API tokens, pending provider transactions and old reset/confirmation/unlock proofs. Keep old URLs as expiry/reissue landings. Do not forward old proof parameters. No Devise cookie importer or permanent Warden coexistence is promised.
Verify ownership and recovery
Test existing passwords, denied accounts, delivered mail, sign-out, provider-only recovery, native clients and account changes. Run browser journeys with Turbo, JavaScript without Turbo, and permitted no-JS. Boot and run the full application suite with Devise removed. Preserve a reviewed compatibility build and recovery snapshot before any real switch.
If counts diverge or a former credential still works, stop promotion and follow migration recovery.