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