Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby Perl
Branch: master
Failed to load latest commit information.
lib Replaced log string concatenation with heredocs
.gitignore updated
Gemfile updated
Gemfile.lock updated
MIT-LICENSE updated fixed require gem typo in min usage section
Rakefile updated
databasedotcom-oauth2.gemspec updated

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.