Provider sign-in

Keep your provider libraries and connect their verified results to AddAuth account policy.

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.

Keep protocol ownership in the host

The host installs and configures its maintained provider libraries. It owns credentials, scopes, callback registration, CSRF validation, middleware order and failure handling. AddAuth does not implement OAuth/OIDC exchange or JWT cryptography, persist provider API tokens, monkey-patch libraries or take over unrelated provider routes.

Local acceptance covers real middleware using Google, Apple form_post and Microsoft OpenID Connect fixtures. Those synthetic providers do not certify your live registrations or physical devices. A password/email/passkey-only host does not need the optional provider dependencies.

Prepare optional persistence and routes

In the reviewed destination app:

bin/rails generate add_auth:external_identities
RAILS_ENV=test bin/rails db:migrate

Review config/initializers/add_auth_providers.rb. Its commented example shows correlation middleware before the host’s OmniAuth builder, a verified-result mapper, fixed issuer/audience and explicit provider registration. Adapt your existing registration rather than creating a duplicate builder. The feature remains disabled until configured.

Retain the provider library’s Rails CSRF protection and POST request phase. Map only a verified server-side library result; never pass an HTTP auth hash as verified evidence. Callback routing selects enabled registered providers; review precedence for providers with an existing callback. Custom callback paths need a deliberate host integration.

Preserve identity ownership

Import each reviewed provider subject to its original account and configured issuer/audience namespace. Email equality never merges accounts. Linking requires a signed-in account and fresh proof; unlinking checks that an allowed sign-in method remains, then revokes affected sessions atomically.

Provider-only enrollment collects the host’s allowlisted profile fields and independently confirms the entered email before admission. Do not treat a historical provider email flag as verified recovery provenance. Fresh provider reauthentication also requires actual provider authentication-time evidence; a recent callback timestamp is insufficient.

Handle Apple callback transport

Apple’s cross-site form POST uses a callback-only correlation cookie wrapper before OmniAuth. The generated initializer documents the integration. Preserve the normal browser cookie settings; do not weaken the entire application session cookie for one callback. Native Apple login uses a separate nonce challenge, described in mobile authentication.

Verify success and coexistence

Exercise the real request phase, CSRF, callback, wrong state/nonce, missing subject, changed issuer/audience, expired proof, unknown signing key, provider outage and duplicate callback. Test existing-account login, independent enrollment confirmation, link/unlink and denied accounts in all three browser modes. Verify unrelated OAuth routes still reach their original handlers.

If callbacks return a generic failure, inspect the fixed configuration and redacted provider-library error without logging tokens or complete auth payloads. Continue with migration recovery.