What is databasedotcom-oauth2?

When and why should I use it instead of OmniAuth?

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

Specifically, databasedotcom-oauth2:

  • allows multiple saleforce.com 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.

Demos

Using Sinatra

Simple example  (view source on github)

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

Usage

Minimal

require "databasedotcom-oauth"
use Databasedotcom::OAuth2::WebServerFlow, 
  :token_encryption_key => "replace me",
  :endpoints => {"login.salesforce.com" => {: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 => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"},
                 "test.salesforce.com"  => {:key => "replace me", :secret => "replace me"}}

Authentication

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"

Miscellaneous

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 salesforce.com 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.

    Example:

    :endpoints => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"}
               "test.salesforce.com"  => {: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"
Base64.strict_decode64(ENV['TOKEN'])

    Default: nil

Optional Configuration Parameters

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

    Values passed directly to salesforce.com 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 salesforce.com.

    Default: /auth/salesforce

Resources