omniauth-facebook, a Facebook OAuth2 strategy for OmniAuth

A strategy, which in OmniAuth means a Rack middleware

omniauth-facebook is a Facebook OAuth2 strategy for OmniAuth, and the README is precise about the shape. The strategy class is OmniAuth::Strategies::Facebook, and it is simply a Rack middleware, which is why the usage instructions point at the OmniAuth documentation for the general mechanics. It supports OAuth 2.0 in both server-side and client-side flows, and the client-side flow uses the Facebook JavaScript SDK with FB.login, after which the application hits the callback endpoint. The audience is a Rails or Sinatra developer who already uses OmniAuth and wants Facebook as one more provider, and the project is published as a gem, omniauth-facebook, with the documentation hosted on a GitHub pages site. The notes in the README are based on the master branch, with a note to look at the tags for documentation that matches a specific release.

Installing and mounting it

Installation is a Gemfile line and a bundle install.

gem 'omniauth-facebook'

In a Rails application the middleware is added in an initializer, and the credentials come from the environment.

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :facebook, ENV['FACEBOOK_APP_ID'], ENV['FACEBOOK_APP_SECRET']
end

For a plain Rack application the same builder block goes into the config.ru file, and the repository ships a runnable example with a Gemfile, a Gemfile.lock, an app.rb and the config.ru, where the config.ru demonstrates both the server-side and the client-side flow including the use of the Facebook JavaScript SDK. The point of the example is worth noting for anyone integrating this. The server-side flow is the one most applications will use, and the client-side flow exists for the case where the login dialog is opened from the browser and the application then posts the result to the callback path.

The options table, one line at a time

Configuration is passed as a hash to the provider method, and the README documents each option with its default. scope defaults to email and is a comma-separated list of the permissions you ask the user for. display defaults to page and accepts page or popup, and the option is about the context the authentication page is shown in. config_id selects the configuration ID used for a System User access token with Facebook Login for Business. image_size defaults to square and covers the profile picture returned in the auth hash, with the named sizes square, small, normal and large, and it also accepts a hash with :width and :height, in which case the closest available picture is returned for the requested size and aspect ratio. info_fields defaults to name,email and lists exactly which fields come back from the /me endpoint, and locale selects the locale used for that call. auth_type optionally asks for re-authentication, with https checking for the secure cookie and reauthenticate forcing it, and the README notes using rerequest when you want to ask for permissions again. secure_image_url defaults to true so the avatar URL is served over https, and callback_url or callback_path override the callback used in the server-side flow, which has to be registered in the Facebook app configuration.

The Graph API version is a decision, not an accident

The strategy uses versioned API endpoints by default, and the current version is v24.0. The version can be changed through the client_options hash passed to the provider, by editing the site and authorize_url parameters.

use OmniAuth::Builder do
  provider :facebook, ENV['FACEBOOK_APP_ID'], ENV['FACEBOOK_APP_SECRET'],
    client_options: {
      site: 'https://graph.facebook.com/v20.0',
      authorize_url: "https://www.facebook.com/v20.0/dialog/oauth"
    }
end

The release history shows why this matters. The v9.0.0 release defaulted to Graph API 5.0, v10.0.0 defaulted to 19.0, and v11.0.0 defaults to 24.0, with v10.0.0 and v11.0.0 both published on 2026-07-18 and v9.0.0 back on 2021-10-25. In other words, the default version is a property of the major release you installed, and a dependency that floats on the latest tag can change the Graph API version under you. Pinning the gem major and, if you need it, setting the version explicitly is the safer arrangement.

Per request options and the auth hash

Some options can be overridden for a single request rather than for the whole application, by passing them in the query string of the OmniAuth request phase URL. The README shows the pattern with /auth/facebook?display=popup, /auth/facebook?scope=email and /auth/facebook?config_id=001, and the same works for auth_type. The result of a successful authentication is the auth hash in request.env['omniauth.auth'], and the README prints the whole structure, which is a useful reference because it shows the four top level keys. The provider and uid identify the account, info carries the email, name, first name, last name, image and verified flag, credentials carries the OAuth 2.0 access token with expires_at and expires, and extra holds the raw_info from the Graph API with the id, name, link, username, location, gender, email, timezone, locale, verified and updated_time. The README adds the caveat that the precise information available may depend on which permissions you request, which is the same point the options table makes from the other direction.

The client-side flow and its cookie requirement

The client-side flow exists for the case where the login dialog is opened in the browser by the Facebook JavaScript SDK. You call FB.login and then, once the user has authenticated in the success callback, you hit the callback endpoint, which is /auth/facebook/callback by default. There is one requirement in that section that is easy to lose, because the README is cut off in the middle of it, but the substance is that cookies must be enabled in the FB.init configuration for the procedure to work. The reason is not the SDK but the browser, since the callback is a normal request to your server and the session that carries the authorisation has to arrive with it. For an application that just wants a working Facebook sign in, the server-side flow through the OmniAuth middleware is the simpler path, and the client-side flow is the one to reach for when the login has to happen inside a page the application already controls.

The project is asking for maintainers

The first thing in the README, above the feature list, is a notice. The project is looking for maintainers to help keep it up to date, and readers are invited to open an issue expressing their interest. That is worth taking at face value, because it is the kind of statement that usually precedes a project drifting out of maintenance. The repository is not archived and the last push was on 2026-08-11, and the release history shows the recent work, with v11.0.0 and v10.0.0 published on 2026-07-18 and a long gap back to v9.0.0 in October 2021, which suggests the recent releases were a deliberate effort to catch up with the Graph API rather than a steady rhythm. The top level of the repository is small and conventional, with lib/ for the strategy, an example/ directory with a runnable Sinatra application, test/, a Rakefile, a Gemfile, the gemspec and a CHANGELOG.md. The licence field on the project is recorded as unknown, and there is no licence file at the top level of the tree, so the terms for redistribution are worth confirming before you build on the gem.

Editorial conclusion

omniauth-facebook fits a Rails or Sinatra application that wants Facebook sign in through the standard OmniAuth middleware, with the option to switch the Graph API version without waiting for a gem release. It does not fit an application that has moved away from OmniAuth, since it is a strategy for that library rather than a standalone client, and it does not fit a team that needs a maintained dependency for a platform whose own API keeps moving. Verify three things before depending on it: which Graph API version the default in your installed release points at, since the defaults changed across the 9, 10 and 11 major lines, which permissions you request and therefore which fields you get in the auth hash, and that the callback URL you register with Facebook matches the one your application presents.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. simi/omniauth-facebook on GitHub