#OmniAuth
"OmniAuth is a library that standardizes multi-provider authentication for web applications. It was created to be powerful, flexible, and do as little as possible. Any developer can create strategies for OmniAuth that can authenticate users via disparate systems. OmniAuth strategies have been created for everything from Facebook to LDAP." - OmniAuth GitHub Page
OmniAuth is like a little black box of unknown power. You put something in the box, like a user's Facebook credentials, and it magically spits out that user's facebook information. This is everything from their name, profile picture, and email, to a whole slew of other useless information for you to massage to your webapp's content. Be careful, though; to look into the mysterious box of OmniAuth is akin to Pandora looking into her box and unleasing pain and suffering on the world, but with Pandora being you and the world being your brain.
But fear not, oh weary developer! This article will walk you through the dreary process of making your app OmniAuthenticable. By the end, you will have made Facebook your certified OmniAuthorized slave. Now, keep your head up, and let's get started.
##Getting Started
The thing to remember about OmniAuth is that it is modularized to make provider integration easier. For example, to use OmniAuth's Facebook strategy (OmniAuth's name for different website logins), you simply include it in your Gemfile, along with the generic OmniAuth gem:
gem 'omniauth',
gem 'omniauth-facebook'
These two files will get you set up with everything you need to run OmniAuth alongside your User model. Now, you must be thinking "Wait a minute, run alongside my User model? I thought it would just be a part if it!", and I am here to tell you that you are wrong. So wrong. OmniAuth does not just plug into an existing model or controller; it will need it's own to operate. More on that later.
##Integrating OmniAuth
For now, let's continue configuring OmniAuth in the config/initializers/omniauth.rb:
Rails.application.config.middleware.use OmniAuth::Builder do
provider :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET']
end
You'll need to go to Facebook's developement site to grab that FACEBOOK_KEY and FACEBOOK_SECRET. Beyond that, visit each OmniAuth strategy's github page to see the different configurations that can be included in this file.
Next up is getting the OmniAuth routes plugged into your routes.rb, but before we do that, let's look at how OmniAuth makes calls to the various providers it supports.
The basics of OmniAuth's functionality comes from redirecting the user to /auth/:provider. Then, OmniAuth with use it's black magic to take the user the the respective provider's login page. Create a link to send a user to log in with their Facebook credentials:
=link_to 'Connect with Facebook', '/auth/facebook'
Once the user has done the deed (login, that is), OmniAuth with take all the user's information and package it into an Authentication Hash. This hash will be sent to your application on via a route called /auth/:provider/callback. To use this data, just open up your routes.rb file and make an endpoint for this data:
get '/auth/:provider/callback', to: 'sessions#create'
This is where the whole "OmniAuth needs it's own controller!" stuff comes into play. That sessions#create method will massage the data received from the Authentication Hash and save it to your Users database. An example SessionsController is as follows:
class SessionsController < ApplicationController
def create
@user = User.find_or_create_from_auth_hash(auth_hash)
self.current_user = @user
redirect_to '/'
end
protected
def auth_hash
request.env['omniauth.auth']
end
end
See that omniauth.auth? That's the key to the treasure chest of user information you jsut received. With it, you can save all the information from the user's Authentication Hash into your database. After all is said and done, you may carry on making the rest of your app as awesome as humanly possible, knowing that all of that juicy information is at your beck and call.
If you would like more examples, check out the User model in CourewareOfTheFuture and bask in the glory that is Github OmniAuth.
Good luck!
##Other Helpful Links