Social Login in Rails with Rodauth

OmniAuth provides a standardized interface for authenticating with various external providers. Once the user authenticates with the provider, it's up to us developers to handle the callback and implement actual login and registration into the app. There is a wiki page laying out various scenarios that need to be handled if you want to support multiple providers, showing that it's by no means a trivial task.

While Devise provides a convenience layer around OmniAuth, it does nothing to actually sign the user into your app. When I started writing the OmniAuth integration for Rodauth, I wanted to go one step further and actually handle things like persistence of external identities, account creation and login, while still allowing the developer to customize the behaviour. That's how rodauth-omniauth was created. ✨

In this article, I will show how to add social login to an existing Rails app that's using Rodauth, and extend the default behaviour with some custom logic. If you're looking to get started with Rodauth, check out my previous article. With that out of the way, let's dive in.

Setup

We'll start by installing the Rodauth extension and the desired OmniAuth strategies:

$ bundle add rodauth-omniauth omniauth-facebook omniauth-google_oauth2

You don't need to install any gems for CSRF protection of OmniAuth request endpoints, because rodauth-omniauth will automatically use whichever CSRF protection mechanism Rodauth was configured with, which in case of Rails will be ActionController::RequestForgeryProtection.

If you haven't already, create the necessary OAuth apps, and configure the callback URL to be https://localhost:3000/auth/{provider}/callback, where {provider} is either facebook or google. We'll save the credentials for the OAuth apps into our project:

$ rails credentials:edit

# ...
facebook:
  app_id: "<YOUR_APP_ID>"
  app_secret: "<YOUR_APP_SECRET>"
google:
  client_id: "<YOUR_CLIENT_ID>"
  client_secret: "<YOUR_CLIENT_SECRET>"

Next, we'll need to create the table that rodauth-omniauth will use for storing external identities:

$ rails generate migration create_account_identities
$ rails db:migrate

class CreateAccountIdentities < ActiveRecord::Migration
  def change
    create_table :account_identities do |t|
      t.references :account, null: false, foreign_key: { on_delete: :cascade }
      t.string :provider, null: false
      t.string :uid, null: false
      t.index [:provider, :uid], unique: true
    end
  end
end

In the Rodauth configuration, we can now enable the omniauth feature and register our strategies:

# app/misc/rodauth_main.rb
class RodauthMain < Rodauth::Rails::Auth
  configure do
    enable :omniauth

    omniauth_provider :facebook,
      Rails.application.credentials.facebook[:app_id],
      Rails.application.credentials.facebook[:app_secret],
      scope: "email"

    omniauth_provider :google_oauth2,
      Rails.application.credentials.google[:client_id],
      Rails.application.credentials.google[:client_secret],
      name: :google # rename it from "google_oauth2"
  end
end

Finally, we can import the view templates for the login form, and add the social login links there:

$ rails generate rodauth:views login
#  create  app/views/rodauth/_login_form.html.erb
#  create  app/views/rodauth/_login_form_footer.html.erb
#  create  app/views/rodauth/_login_form_footer.html.erb
#  create  app/views/rodauth/_login_form_header.html.erb
#  create  app/views/rodauth/login.html.erb
#  create  app/views/rodauth/multi_phase_login.html.erb

<!-- app/views/rodauth/_login_form_footer.html.erb -->
<!-- ... -->
  <li>
    <%= button_to "Login via Facebook", rodauth.omniauth_request_path(:facebook),
      method: :post, data: { turbo: false }, class: "btn btn-link p-0" %>
  </li>
  <li>
    <%= button_to "Login via Google", rodauth.omniauth_request_path(:google),
      method: :post, data: { turbo: false }, class: "btn btn-link p-0" %>
  </li>
<!-- ... -->

We're using POST form submits, because OmniAuth doesn't allow GET requests for the request phase anymore by default. You'll notice we had to disable Turbo for the request links, as those redirect to an external authorize URL, which don't support AJAX visits.

Some OAuth authorizations require that the web app is served over HTTPS. Assuming you're using Puma, a quick way to enable this locally would be to install the localhost gem, and tell the Rails server you want to use SSL:

$ bundle add localhost --group development
$ rails server -b ssl://localhost:3000

Now you should be able to open https://localhost:3000/login, and see the Rodauth login page with social login links.

Login & Registration

When we visit the Facebook login link, and authorize the OAuth app, upon returning to the app a new verified account with your Facebook email address should be automatically created, along with the external identity, and you should be logged in.

You should see something like this in the database:

account = Account.last
#=> #<Account id: 123, status: "verified", email: "[e-mail]">
account.identities
#=> [#<Account::Identity id: 456, account_id: 123, provider: "facebook", uid: "350872771">]

A problem I often experienced as a user was forgetting which social provider I initially logged into on a certain app, and whether I had even logged in with a social provider (though I can now easily determine the latter by checking my password manager). If I would sign in with the wrong provider, this would usually result in a new account being created for me.

Wouldn't it be nice if the app could detect that the email address of my existing account matches the one of the external identity, and automatically assign that identity to the existing account? Well, rodauth-omniauth does that automatically. If I were to authenticate with Google the next time, I would get logged into my existing account, with the new Google identity connected to it.

account.identities #=> [
#   #<Account::Identity id: 456, account_id: 123, provider: "facebook", uid: "350872771">,
#   #<Account::Identity id: 789, account_id: 123, provider: "google", uid: "987349876343">,
# ]

If for whatever reason you want to change or disable this behaviour, you can override account_from_omniauth, which is what searches existing accounts when authenticating with a provider for the first time:

class RodauthMain < Rodauth::Rails::Auth
  configure do
    # ...
    account_from_omniauth do
      # this is roughly the default implementation
      account_table_ds.first(email: omniauth_info["email"])
    end
    # OR
    account_from_omniauth {} # new identity = new account
  end
end

Storing additional data

Let's say users in our app can fill in their full name, and we decided to inherit it from their external identity when possible, to save them extra work.

We'll assume we have a separate profiles table associated to accounts, and we're already creating a profile record on normal registration:

# in a migration:
create_table :profiles do |t|
  t.references :account, null: false, foreign_key: true
  t.string :name
  t.timestamps
end

class RodauthMain < Rodauth::Rails::Auth
  configure do
    # create profile after normal registration
    after_create_account { Profile.create!(account_id: account_id) }
  end
end

We can override the hook for creating the account via OmniAuth login, and create the profile with the name prefilled:

class RodauthMain < Rodauth::Rails::Auth
  configure do
    # create profile after registration through OmniAuth login
    after_omniauth_create_account do
      Profile.create!(account_id: account_id, name: omniauth_info["name"])
    end
  end
end

Let's say we now want to store additional data on identities, which by default have only the mandatory provider and uid columns. We might want to store created_at & updated_at timestamps, as well as an email for each identity. We can start by creating the necessary columns:

# in a migration:
add_timestamps :account_identities
add_column :account_identities, :email, :string

We can now ensure created_at is set the first time we authenticate with a provider, and that updated_at and email are updated each time we authenticate with the provider:

class RodauthMain < Rodauth::Rails::Auth
  configure do
    # store `created_at` only when the identity is created
    omniauth_identity_insert_hash do
      super().merge(created_at: Time.now)
    end
    # update `updated_at` and `email` each time the identity is updated
    omniauth_identity_update_hash do
      super().merge(updated_at: Time.now, email: omniauth_email)
    end
  end
end

Now our account & identity data might look as follows:

account = Account.last
#=> #<Account id: 123,
#    status: "verified",
#    email: "[e-mail]",
#    name: "Janko Marohnić">

account.identities.first
#=> #<Account::Identity
#    id: 789,
#    account_id: 123,
#    provider: "google",
#    uid: "987349876343",
#    email: "[e-mail]",
#    created_at: Fri, 11 Nov 2022 13:11:85 UTC,
#    updated_at: Fri, 02 Dec 2022 08:01:26 UTC>

Multiple account types

If your app has different account types which require potentially different authentication rules, you'll be glad to know that rodauth-omniauth supports distinct configurations.

Let's say we have an admin account type, for which we want to provide logging in via GitHub. Assuming we've already created the OAuth app, we'll install the OmniAuth strategy gem:

$ bundle add omniauth-github
$ rails credentials:edit

# ...
github:
  client_id: "<YOUR_CLIENT_ID>"
  client_secret: "<YOUR_CLIENT_SECRET>"

To protect the admin section, we'll only allow users that are members of the company's GitHub organization. For this, we might have the following Rodauth configuration:

# app/misc/rodauth_admin.rb
class RodauthAdmin < Rodauth::Rails::Auth
  configure do
    enable :omniauth

    prefix "/admin"
    session_key_prefix "admin_"

    omniauth_provider :github,
      Rails.application.credentials.github[:client_id],
      Rails.application.credentials.github[:client_secret]

    before_omniauth_callback_route do
      if omniauth_provider == :github && !organization_member?(omniauth_info["nickname"])
        set_redirect_error_flash "User is not a member of our GitHub organization"
        redirect "/admin"
      end
    end
  end

  private

  def organization_member?(username)
    # ... check if user is a member of company's GitHub organization ...
  end
end

Since we've set admin routes to be prefixed with /admin, OmniAuth routes will be prefixed as well, so the request phase will be at /admin/auth/github. This ensures authentication doesn't overlap with the main account type.

If we had decided to use a separate table for admin accounts (e.g. admins), we can also use a separate identities table:

# in a migration:
create_table :admin_identities do |t|
  t.references :admin, null: false, foreign_key: { on_delete: :cascade }
  t.string :provider, null: false
  t.string :uid, null: false
  t.index [:provider, :uid], unique: true
end

class RodauthAdmin < Rodauth::Rails::Auth
  configure do
    # ...
    omniauth_identities_table :admin_identities
    omniauth_identities_account_id_column :admin_id
  end
end

Future work

Separate registration step

The current automatic registration assumes the external login will always return the user's email address, which is not always the case (hello Twitter). It also assumes we don't need additional information from the user before creating their account.

After external login, I would like to support having a separate registration step, with fields like email address already being filled in. The main challenge is preventing an attacker from signing up with another person's identity. I would definitely welcome any contributions. 🙏

Connecting additional identities

Once the user is signed in, it would be useful to allow them to connect additional external identities, as well as disconnect already linked identities, to make future logins more reliable.

GitLab account interface

This feature seems more straightforward to implement. However, it's tricky to handle the scenario when a logged in user wants to authenticate via a different provider, because by default Rodauth doesn't disallow access to the login page in this case. There are also questions around connecting identities that are currently assigned to a different account.

Closing words

This was definitely the most challenging Rodauth extension I've built. I had been working on it periodically for 2 years, and was only able to release it once I decided to postpone the mentioned features. It took a while to find the right balance between respecting OmniAuth configuration and Rodauth conventions, support JSON API with JWT, handle inheritance, figure out the OmniAuth 2.0 upgrade, and implement a customizable callback phase.

I was able to do all this thanks to the strong foundation Rodauth provides. Its layered design allowed me to hook at the right level to make it work well with other authentication features, while the configuration DSL made it easy to make any part customizable. Because Rodauth supports feature dependencies, I was able to extract the pure OmniAuth integration for standalone usage, for those who don't need any of the database logic.

While it was previously possible to use OmniAuth directly, I'm happy that Rodauth now has a social login story. Given that this is a much more integrated solution compared to what Devise offers, and other people might have more custom authentication flows, I'm curious to get everyone's feedback. 😉