Skip to content
OpenAuth2 is a thin OAuth2 wrapper written on top of Faraday in Ruby.
Pull request Compare This branch is 100 commits behind sent-hil:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


OpenAuth2 Build Status

OpenAuth2 is a thin OAuth2 wrapper written on top of Faraday in Ruby. The goal is a simple, well documented, easy to use interface for all your OAuth2 needs.

  • This software is alpha, you're either very brave or very foolish to use this in production of rockets or anything else.
  • This Readme is best viewed in DocumentUp.


To begin, let's setup the configuration. Here we're assuming connection to Facebook api. OpenAuth2 supports Google and Facebook out of the box (more to come soon). Other sites can be configured manually.

require 'open_auth2'

# get this info by signing your app at
client_id     = 'enter in your own value'
client_secret = 'enter in your own value'
redirect_uri  = 'enter in your own value'

config = do |c|
  # indicate what kind of provider you want to use
  # Accepts: :google, :facebook or :default
  c.provider       = :facebook

  c.client_id      = client_id
  c.client_secret  = client_secret
  c.redirect_uri   = redirect_uri
  c.scope          = ['publish_stream']


Next, initialize a client object, which we'll use to make requests and pass in the config object we created earlier.

client = do |c|
  c.config = config

Client#configure_connection takes a block, which can be used to setup middleware like any other Faraday client, i.e:

client.configure_connection do |c|
  c.response :logger

Authenticate Url

To start the OAuth2 exotic dance, you'll need to obtain a 'code' from the server, which you can then use to request an 'access_token'. Redirect the user/yourself to this url to obtain that 'code'.


build_code_url takes optional params hash, which will be bundled into the url.

client.build_code_url(:scope => 'publish_stream')

Access token

Access token is used to sign the request so the server can identify the client sending the request. If you already have an access token, add it to the client with a block.

access_token  = 'enter in your value'
refresh_token = 'enter in your value'

client.configure do |c|
  c.access_token  = access_token

  # optional, for fb its same as above
  c.refresh_token = refresh_token

GET Access Token

If you don't have an access token, we'll need to ask the server for it.

token#configure_connection takes an block, just like client#configure_connection, which can be used to setup middleware like any other Faraday client.

token = client.token
token.configure_connection do |c|
  c.response :logger

# asks Facebook for access_token

# the following methods are now available

GET Refresh Token

# tells Facebook api to extend the expiration of the access_token

GET request

To make an api call, simply call get with a hash containing path.

client.get(:path => '/cocacola')

get accepts a Hash as second argument, which can be used to pass in additional parameters.

client.get(:path => '/cocacola', :limit => 1)

Faraday convenience methods

Client#get is a convenience method that calls Faraday#get. You can drop down to Faraday connection object itself and make requests via that also.

client.connection.get do |conn|

Client#run_request points to Faraday#run_request. It takes hash since I can never remember the order in which to pass the arguments.

path = ""
client.run_request(verb: :get, path: path, body: nil, header: nil)

# same as
client.connection.run_request(:get, path, nil, nil)


Since various OAuth2 providers differ in their implementation, OpenAuth2 provides a simple plugin system to accomodate the differences, rather than 'one shoe fits all' approach. Facebook and Google plugins are builtin, but it is trivial to add new ones.

There are three requirements:

  1. Should be under right namespace (OpenAuth2::Provider)
  2. Contain Options hash
  3. Contain #parse class method

To use the plugin, call Config#provider= with name of the provider. OpenAuth2 upcases and camelizes the name and looks for the constant under OpenAuth2::Provider namespace.

Plugin Example

module OpenAuth2
  module Provider
    module YourApi

      # Provider::Base contains keys of various accepted
      # Options, while Provider::Default contains the default options and
      # their values. You can however override them here.
      Options = {
        :authorize_url            => '',
        :code_url                 => '',
        :refresh_token_grant_name => '',

      # Called after AccessToken#get and #refresh response are received
      # from provider.
      def self.parse(config, response_body)
        # parse the response body
        access_token            = response_body.gsub('access_token=', '')

        # update config to reflect new information
        config.access_token     = access_token
        config.token_arrived_at =

Google example

require 'open_auth2'
require 'json'

access_token  = 'enter in your own value'
refresh_token = 'enter in your own value'

config = do |c|
  c.provider       = :google
  c.access_token   = access_token
  c.refresh_token  = refresh_token
  c.scope          = ['']
  c.redirect_uri   = 'http://localhost:9393/google/callback'
  c.path_prefix    = '/calendar/v3'

client = do |c|
  c.config = config

# get request
client.get(:path => '/users/me/calendarList')

post_url = '/calendar/v3/calendars/'
body     = {
  "summary" => "From OpenAuth2",
  "start"   => {"dateTime"=>"2012-01-20T10:00:00.000-07:00"},
  "end"     => {"dateTime"=>"2012-01-20T10:25:00.000-07:00"}
body = JSON.dump(body)

# post request         => post_url,
            :body         => body,
            :content_type => content_type)

header   = {"Content-Type" => "application/json"}
full_url = "#{post_url}?access_token=#{access_token}"

# post request via #run_request
client.run_request(:verb   => :post,
                   :path   => full_url,
                   :body   => body,
                   :header => header)


  • ActiveSupport
  • Faraday
  • URI
  • Json

Supported Versions

  • MRI 1.9.2
  • MRI 1.9.3
  • jRuby (jruby --1.9 rspec)
  • Rubinius 2.0.0dev (RBXOPT=-X19 rbx- S rspec)


$ gem install open_auth2


OpenAuth2's git repo is available on GitHub:


You will need these gems to get tests to pass:

  • rspec2
  • rake
  • SimpleCov (optional for coverage)

See meta for more info on contributing and technology used to create this gem.


Copyright (c) 2012 Senthil A. See License for details.

Something went wrong with that request. Please try again.