Skip to content
No description or website provided.
Ruby Perl
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore updated Jun 9, 2012

What is databasedotcom-oauth2?

When and why should I use it instead of OmniAuth?

Many Ruby web apps integrated with need more than just identification, they also need to interact with via the databasedotcom gem. Both OmniAuth and databasedotcom-oauth2 provide identification; however, databasedotcom-oauth2 makes the interaction part easier.

Specifically, databasedotcom-oauth2:

  • allows multiple endpoints (production, sandbox, etc.)
  • supports configuration of scope, display, and immediate OAuth 2.0 parameters
  • supports My Domain
  • maintains an encrypted OAuth 2.0 token in whatever session store you choose (Cookie, Pool, etc)
  • materializes a databasedotcom client upon each request (using the token in session)
  • provides a mixin for your app containing utility methods like unauthenticated?, client, etc.


Using Sinatra

Simple example  (view source on github)

Advanced configuration with a JQuery Mobile front-end  (view source on github)



require "databasedotcom-oauth2"
use Databasedotcom::OAuth2::WebServerFlow, 
  :token_encryption_key => "replace me",
  :endpoints => {"" => {:key => "replace me", :secret => "replace me"}}

Insert above code wherever your Rack Stack is defined. See Required Configuration Parameters for more information on parameters.

Multiple Endpoints

use Databasedotcom::OAuth2::WebServerFlow, 
  :endpoints => {"" => {:key => "replace me", :secret => "replace me"},
                 ""  => {:key => "replace me", :secret => "replace me"}}


use Databasedotcom::OAuth2::WebServerFlow, 
  :display   => "touch"        , #default is "page"
  :immediate => true           , #default is false
  :prompt    => "login consent", #default is nil
  :scope     => "full"           #default is "id api refresh_token"


use Databasedotcom::OAuth2::WebServerFlow, 
  :api_version => "24.0"      , #default is 25.0
  :debugging   => "true"      , #default is false
  :path_prefix => "/auth/sfdc"  #default is /auth/salesforce

Required Configuration Parameters

  • :endpoints

    Hash of remote access applications; at least one is required. Values must be generated via at Setup > App Setup > Develop > Remote Access. Only one remote access application is needed for production, sandbox, or pre-release; separate entries are not necessary for My Domain.


    :endpoints => {"" => {:key => "replace me", :secret => "replace me"}
                   ""  => {:key => "replace me", :secret => "replace me"}}

    Default: nil

  • :token_encryption_key

    Encrypts OAuth 2.0 token prior to persistence in session store. Any Rack session store can be used: Rack:Session:Cookie, Rack:Session:Pool, etc. A sufficiently strong key must be generated. It's recommended you use the following command to generate a random key value.

    ruby -ropenssl -rbase64 -e "puts Base64.strict_encode64(OpenSSL::Random.random_bytes(16).to_str)"

    It's also recommended you store the key value as an environment variable as opposed to a string literal in your code. To both create the key value and store as an environment variable, use this command:

    export TOKEN=`ruby -ropenssl -rbase64 -e "puts Base64.strict_encode64(OpenSSL::Random.random_bytes(16).to_str)"`

    Then, in your code, decrypt prior to use:

    require "base64"

    Default: nil

Optional Configuration Parameters

  • :display, :immediate, :prompt, :scope

    Values passed directly to which control authentication behavior. See OAuth 2.0 Web Server Authentication Flow for detailed explanation as well as valid and default values.

    Default: see OAuth 2.0 Web Server Authentication Flow

  • :display_override,:immediate_override, :prompt_override,:scope_override

    Allow correspondingly named parameter to be overridden at runtime via http parameter of same name. For example, if your app is capable of detecting the client device type, set :display_override to true and pass a display http parameter to /auth/salesforce.

    Default: false

  • :api_version

    For explanation of api versions, see What's New in Version XX.X

    Default: 25.0

  • :debugging

    Will enable debug output for both this gem and databasedotcom.

    Default: false

  • :on_failure

    A lambda block to be executed upon authentication failure.

    Default: redirect to /auth/salesforce/failure with error message passed via message http parameter.

  • :path_prefix

    The path that signals databasedotcom-oauth2 to initiate authentication with

    Default: /auth/salesforce


Something went wrong with that request. Please try again.