OmniAuth gem: Standardized Multi-Provider Authentication for Ruby

• OmniAuth

OmniAuth is a library that standardizes multi-provider authentication for web applications. 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.

To use OmniAuth, you need only

1. to redirect users to /auth/:provider, where :provider is the name of the strategy (for example, developer or twitter).

2. From there, OmniAuth will take over and take the user through the necessary steps to authenticate them with the chosen strategy.

3. Once the user has authenticated, OmniAuth sets a special hash called the Authentication Hash on the Rack environment of a request to /auth/:provider/callback.

4. This hash contains as much information about the user as OmniAuth was able to glean from the utilized strategy.

5. You should set up an endpoint in your application that matches to the callback URL and then performs whatever steps are necessary for your application.

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'
gem 'omniauth-openid'

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

Para saber mas sobre Rack y sobre Middlewares Rack, véanse las secciones

• Rack en 43,
• Middleware y la Clase Rack::Builder en 43.18 y
• La Estructura de una Aplicación Rack en 43.14

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

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

Strategies

In this link we can find a list of the strategies that are available for OmniAuth: List of Strategies for Omniauth.

Auth Hash Schema

OmniAuth is a flexible authentication system utilizing Rack middleware.

OmniAuth will always return a hash of information after authenticating with an external provider in the Rack environment under the key omniauth.auth.

This information is meant to be as normalized as possible, so the schema below will be filled to the greatest degree available given the provider upon authentication. Fields marked required will always be present.

• provider (required) The provider with which the user authenticated (e.g. twitter or facebook)

• uid (required) An identifier unique to the given provider, such as a Twitter user ID. Should be stored as a string.

• info (required) A hash containing information about the user
  • name (required) The best display name known to the strategy. Usually a concatenation of first and last name, but may also be an arbitrary designator or nickname for some strategies
  • email The e-mail of the authenticating user. Should be provided if at all possible (but some sites such as Twitter do not provide this information)
  • nickname The username of an authenticating user (such as your @-name from Twitter or GitHub account name)
  • first_name
  • last_name
  • location The general location of the user, usually a city and state.
  • description A short description of the authenticating user.
  • image A URL representing a profile image of the authenticating user. Where possible, should be specified to a square, roughly 50x50 pixel image.
  • phone The telephone number of the authenticating user (no formatting is enforced).
  • urls A hash containing key value pairs of an identifier for the website and its URL.

    For instance, an entry could be

    "Blog" => "http://intridea.com/blog"
    

• credentials If the authenticating service provides some kind of access token or other credentials upon authentication, these are passed through here.
• token Supplied by OAuth and OAuth 2.0 providers, the access token.
• secret Supplied by OAuth providers, the access token secret.
• extra Contains extra information returned from the authentication provider. May be in provider-specific formats.
• raw_info A hash of all information gathered about a user in the format it was gathered.

  For example, for Twitter users this is a hash representing the JSON hash returned from the Twitter API.

Ejemplos

• Omniauth Sinatra Example (Twitter y OpenID)
• Omniauth Sinatra Gist Example: Facebook, Twitter, GitHub

Documentación de la Gema

• API doc: OmniAuth: Standardized Multi-Provider Authentication
• Module: OmniAuth
• Esta clase contiene información sobre el usuario. Class: OmniAuth::AuthHash::InfoHash

Véase

• Blog Post: ColdFusion and OAuth part 3- Google authentication. Raymond Camden