Clone this wiki locally
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.
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
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.