OmniAuth is a Ruby on Rails library that provides standardized multi-provider authentication for web applications.  It makes login easy for user by allowing them to  use usernames and passwords from other websites to log into your app.  OmniAuth works on a number of providers, such as Amazon, Github, and Facebook.  A full list of provider strategies can be viewed here:

Each strategy is released as its own ruby gem and all of them can be found on RubyGems.

👍🏽OmniAuth works with Ruby web projects, so you will need to have either Sinatra or Rails installed in your project before beginning👍🏽

For the purposes of this guide, we will be looking specifically at the Facebook strategy for OmniAuth Facebook log in, as it is one of the more popular and also one of the more complex user authentication processes.  We will also be focusing on Rails, but most of the information will be the same or translatable for Sinatra projects.

😺NOTE: In code examples, things that say YOUR_APP, YOUR-APP, or YOUR_FACEBOOK_APP_ID (and the like) will need to be replaced with whatever your app is called (the directory name, most likely) or your Facebook App ID.  If things aren’t working, be sure to check those!😺


First you will need to add the following line to your Gemfile

gem ‘omniauth-facebook’

Any additional OmniAuth strategies will need to be added individually.  Be sure that you install it after the Rails or Sinatra gem in your Gemfile.  After you have entered the gem, run bundle install the the terminal (in your app’s directory!)

The database now needs to be migrated as well as letting Rails know what information will need to be required, which we will accomplish by the following command in the terminal (again in your app’s directory):

rails g migration AddOmniauthToUsers provider:string uid:string

Then you will need to migrate the database, which can be done in Rails by this command in the terminal:

rake db:migrate

Get Facebook Information

Next you will need to register your app with Facebook and get log in credentials.  Go to and click on “Add A New App” in the dropdown in the upper right corner of the page.  Enter the name you wish to display on your app, a contact email, and select a category that best fits what your app does.

Click on Settings on the left side of the page and here you will see your App ID and  App Secret key.


For my project, I used a localhost alternative, is a domain that is set up to point to, which is localhost.   This made the Facebook callbacks easier to work with and I highly recommend using it, but if you prefer trying localhost directly, that’s up to you!

Add your app’s domain name in App Domains.  I’ll be using, followed by the port number.  Click on ‘Add Platform’ at the bottom of the page and select ‘Website’ followed by entering your Site URL.  The Site URL and the App Domain will need to match.

In the root directory of your Rails project find (or if you don’t have it yet, create) a .env file.   On a new line add FACEBOOK_APP_SECRET=YOUR_APP_SECRET replacing YOUR_APP_SECRET with your App Secret key. There are no spaces and no quotation marks, brackets, or braces.

 You will now use the OmniAuth::Builder Rack middleware to build the list of strategies and what needs your app has for the use authentication in config/initializers/omniauth.rb:

Replace 'YOUR_FACEBOOK_APP_ID' with the App ID on your Facebook Developer dashboard and keep the single quote marks intact.

👍🏽Your App Secret key should remain private, so if you are using a public Git service, such as Github, remember to add your .env file to .gitignore.  👍🏽


Adding CoffeeScript

One other file that will need to be added, if you don’t already have it, is a app/assets/javascripts/

Add the following to that file:



This adds callback information to our app so that we send the right information to Facebook’s API and return the information given to us in a manner that we can work with.   It also separates the JavaScript code from the rest of our code, which makes everything easier to read.


Integrating OmniAuth Facebook Into Application

OmniAuth was intentionally designed to be extremely agnostic as far as what providers you use and what information you can get from those providers.  In the Facebook API we can get several different pieces of information from the user’s profile.

Option Keywords Default Value Description
callback_url/ callback_path If you wish to have a server-side flow, you can specify a custom callback URL. This should be specified in your Facebook app configuration (in ‘Advanced’ settings)
display page How the authentication page shows up to the user.
image_size square Displaying user profile image.
locale Specify which location should be used when acquiring user information.
scope email A list of permissions that you may request from the user.
secure_image_url false If you set this to true the user profile image url will be returned in the auth hash


As an example, if you wanted to get a user’s home town you would put in the same config/initializers/omniauth.rb:



Any additional requests can be added below as a separate line in the same middleware.


In the same config/initializers/omniauth.rb, we will add a logger at the top of the file:

OmniAuth.config.logger = Rails.logger

This will allow us to view the logs of OmniAuth communicating between the app and the Facebook Graph API.

Using OmniAuth

One way to utilize OmniAuth is by linking it in a button to ask users to log in:



Which gives us a button that looks like this, with some styling:



Trying It Out

Try clicking the button or link to log into the site.   The first time I tried this, I got this error:




This error was solved by entering the correct site on the Facebook Developers and making sure the Facebook Login Settings are set correctly:





👍🏽Remember to restart your Rails server if nothing else is working!👍🏽



By now you should be able to log into your site using the Facebook OmniAuth gem.  OmniAuth is an easy way to use the Facebook API in Ruby web applications.


More information about OmniAuth and the Facebook API can be viewed at:

The Github page for OmniAuth-Facebook:

Using the Facebook JavaScript SDK:

Using the Facebook API:

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.