skip to content

With Devise 5's :omniauthable, how does OmniAuth setup in a Rails app differ from mounting OmniAuth::Builder yourself?

level: middleimportance: should knowfreq 40%

answer

  1. config.omniauth in the Devise initializer
  2. omniauth_providers: [:github] on the model
  3. /users/auth/github and its callback
  4. one action per provider name
  5. only one omniauthable model

basics

~20 s

Devise builds the strategies from config.omniauth in its initializer instead of OmniAuth::Builder, scopes the paths under the model (/users/auth/github), routes the callback to an action named after the provider, and handles failures in its own controller.

solid answer

~40 s

With Devise you declare providers with `config.omniauth :github, id, secret` in `config/initializers/devise.rb` rather than a `OmniAuth::Builder` block, and add `:omniauthable, omniauth_providers: [:github]` to the model. `devise_for :users, controllers: { omniauth_callbacks: "users/omniauth_callbacks" }` then routes `/users/auth/github` (to a `passthru` action that answers 404 if the middleware did not intercept the POST) and `/users/auth/github/callback` to a `github` action in your subclass of `Devise::OmniauthCallbacksController`. That action reads `request.env["omniauth.auth"]`, finds the user and calls `sign_in_and_redirect`. Devise sets `OmniAuth.config.on_failure` to its controller's `failure` action, which flashes "Could not authenticate you from Github…" and redirects to the sign-in page. It also sets the path prefix from the mapping, so only one model can be omniauthable. The POST-only rule and the CSRF gem still apply.

go deeper

for a junior

Know that Devise declares providers with config.omniauth, adds :omniauthable to the model, and calls an action named after the provider.

for a middle

Map each piece of a hand-built OmniAuth setup to its Devise equivalent: paths, callback action, failure handling and helpers.

for a senior

Diagnose passthru 404s, the one-omniauthable-model limit and scoped-route conflicts, and keep the CSRF and POST rules in place under Devise.

for a principal

Decide whether third-party sign-in rides on Devise's conventions or stays a thin OmniAuth layer, given how many user types and providers the product expects.

## Same middleware, different wiring Devise's `:omniauthable` module does not replace OmniAuth; it **configures** it. The strategies still run as Rack middleware with the same request and callback phases. What changes is where providers are declared, which paths they use, which controller receives the callback and who handles failures. | Concern | OmniAuth alone | Devise 5 with `:omniauthable` | |---|---|---| | Declaring a provider | `provider :github, ...` in `OmniAuth::Builder` | `config.omniauth :github, ...` in `config/initializers/devise.rb` | | Model | nothing | `devise ..., :omniauthable, omniauth_providers: [:github]` | | Request path | `/auth/github` | `/users/auth/github` (from the `devise_for` mapping) | | Callback route | you write `auth/:provider/callback` | `devise_for` adds `/users/auth/github/callback` | | Callback action | any action you route to | a method named after the provider, e.g. `github` | | Failure | `/auth/failure`, your route | `Devise::OmniauthCallbacksController#failure` | | Link helper | a literal path | `omniauth_authorize_path(:user, :github)` | Declaring the same provider in both places adds the strategy twice, so a Devise app keeps provider configuration in the Devise initializer only. ## The routes devise_for adds For each provider in `omniauth_providers`, `devise_for :users` adds: 1. `/users/auth/github` to `passthru`, matched with the verbs in `OmniAuth.config.allowed_request_methods` (POST only under OmniAuth 2) and named `user_github_omniauth_authorize`. The middleware normally intercepts this POST, so `passthru` runs only when it did not, for example a provider listed on the model but missing from `config.omniauth`, and it answers **404** "Not found. Authentication passthru." A GET matches no route at all. 2. `/users/auth/github/callback` to `github`, for both GET and POST, named `user_github_omniauth_callback`. Devise also sets `OmniAuth.config.path_prefix` to `/users/auth`. Because that setting is global, a second omniauthable model with a different prefix makes Devise raise "Wrong OmniAuth configuration", listing "You are setting :omniauthable in more than one model" among the causes. Handle several user types through one omniauthable model. ## The callback controller ```ruby # config/routes.rb devise_for :users, controllers: { omniauth_callbacks: "users/omniauth_callbacks" } # app/controllers/users/omniauth_callbacks_controller.rb class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController def github @user = User.from_omniauth(request.env["omniauth.auth"]) sign_in_and_redirect @user, event: :authentication set_flash_message(:notice, :success, kind: "GitHub") if is_navigational_format? end end ``` - `User.from_omniauth` is **your** class method, the find-by-provider-and-uid logic; Devise does not supply it. - `sign_in_and_redirect` signs in through Warden and redirects to the stored location or `after_sign_in_path_for`. - The `:success` and `:failure` messages live under `devise.omniauth_callbacks` in Devise's locale file. ## Failures When Devise loads OmniAuth support it sets `OmniAuth.config.on_failure` to a proc that finds the Devise mapping from the path and calls the callbacks controller's **`failure`** action. That action flashes `"Could not authenticate you from %{kind} because \"%{reason}\"."`, with `kind` the camelised strategy name (so `Github`), and redirects to `after_omniauth_failure_path_for(scope)`, which defaults to `new_session_path(scope)`. Override that method in your subclass to send failures elsewhere. ## Choosing between the two - **The app already uses Devise for passwords.** `:omniauthable` reuses Devise's sign-in, flash messages and failure handling, so one stack serves both kinds of sign-in. - **The app uses the Rails authentication generator or its own sessions.** Mounting `OmniAuth::Builder` directly keeps the callback as an ordinary controller action that calls your own session code, without adopting Devise for one feature. - **Several user types need social sign-in.** Devise's single omniauthable model is a constraint to plan around; a hand-built OmniAuth layer has no such limit. ## What does not change - **POST only.** The path is under `/users/auth`, but OmniAuth 2 still accepts only POST there. Devise's own shared links render `button_to "Sign in with Github", omniauth_authorize_path(resource_name, provider), data: { turbo: false }`. - **CSRF.** The request phase is still checked by `OmniAuth.config.request_validation_phase`, so a Rails app still adds `omniauth-rails_csrf_protection`. - **The auth hash.** The action reads the same `request.env["omniauth.auth"]` with the same provider-and-uid rule.

  • Why might a Devise app call devise_for :users, only: :omniauth_callbacks separately?
    Devise refuses OmniAuth callbacks under a dynamic segment such as `scope "/(:locale)"`, because the middleware needs one fixed path prefix. Its routing error says to pass `skip: :omniauth_callbacks` to the scoped `devise_for` and add `devise_for :users, only: :omniauth_callbacks, controllers: { ... }` outside the scope.
  • What does Devise's passthru action tell you when a user reports it?
    That a POST reached Rails instead of being handled by the OmniAuth middleware. The usual causes are a provider listed in `omniauth_providers` but missing from `config.omniauth`, or a path prefix mismatch. A GET never gets this far: the route accepts only `allowed_request_methods`. The action exists only to answer 404 "Not found. Authentication passthru."

  • Devise's :omniauthable lets a link_to GET start sign-in again.
  • Add OmniAuth::Builder as well as config.omniauth so the provider loads.
  • Devise supplies User.from_omniauth once :omniauthable is enabled.
  • Admins and users can each be :omniauthable with their own path prefixes.
  • With Devise the CSRF gem is unnecessary because Devise checks tokens.

Assumes Devise 5.0 with OmniAuth 2.1; Devise routes the authorize path with OmniAuth.config.allowed_request_methods, so it follows OmniAuth 2's POST-only default.