Home

OmniAuth is a Ruby authentication framework aimed to abstract away the difficulties of working with various types of authentication providers. It is meant to be hooked up to just about any system, from social networks to enterprise systems to simple username and password authentication.

Getting Started

To use OmniAuth in a project with a Gemfile, just add each of the strategies you want to use individually:

gem 'omniauth-github', github: 'intridea/omniauth-github'
gem 'omniauth-openid', github: 'intridea/omniauth-openid'

Now you can use the OmniAuth::Builder Rack middleware to build up your list of OmniAuth strategies for use in your application:

use OmniAuth::Builder do
  provider :github, ENV['GITHUB_KEY'], ENV['GITHUB_SECRET']
  provider :openid, store: OpenID::Store::Filesystem.new('/tmp')
end

When using OmniAuth in a Rails application you can add it to your middleware:

Rails.application.config.middleware.use OmniAuth::Builder do
  require 'openid/store/filesystem'
  provider :github, ENV['GITHUB_KEY'], ENV['GITHUB_SECRET']
  provider :openid, store: OpenID::Store::Filesystem.new('/tmp')
end

By default, OmniAuth will configure the path /auth/:provider. It is created by OmniAuth automatically for you, and you will start the auth process by going to that path.

Also by default, OmniAuth will return auth information to the path /auth/:provider/callback inside the Rack environment. In Sinatra, for example, a callback might look something like this:

# Support both GET and POST for callbacks
%w(get post).each do |method|
  send(method, "/auth/:provider/callback") do
    env['omniauth.auth'] # => OmniAuth::AuthHash
  end
end

Also of note, by default, if user authentication fails on the provider side, OmniAuth will catch the response and then redirect the request to the path /auth/failure, passing a corresponding error message in a parameter named message. You may want to add an action to catch these cases. Continuing with the previous Sinatra example, you could add an action like this:

get '/auth/failure' do
  flash[:notice] = params[:message] # if using sinatra-flash or rack-flash
  redirect '/'
end

In-Depth Documentation

This wiki is the home for all official project documentation. Use the sidebar on the right to navigate to various documentation topics for more specific information.