README.md in databasedotcom-oauth2-0.1.8 vs README.md in databasedotcom-oauth2-0.1.9

- old
+ new

@@ -1,76 +1,145 @@ -# databasedotcom-oauth2 +What is databasedotcom-oauth2? +------------------------------ +* an extension of the [databasedotcom](https://rubygems.org/gems/databasedotcom) gem that simplifies authentication and authorization with [salesforce.com](http://salesforce.com/) for Ruby web apps via OAuth 2.0 +* a Ruby gem intended to run as Rack Middleware +* an alternative to using [OmniAuth](http://www.omniauth.org/) and the corresponding [omniauth-salesforce](https://rubygems.org/gems/omniauth-salesforce) gem. -Rack Middleware for OAuth2 authentication against, and interaction with salesforce.com via the databasedotcom gem. +When and why should I use it instead of OmniAuth? +--------------------------------------------------------------- +Many Ruby web apps integrated with [salesforce.com](http://salesforce.com/) need more than just identification, they also need to _interact_ with [salesforce.com](http://salesforce.com/) via the [databasedotcom](https://rubygems.org/gems/databasedotcom) gem. Both OmniAuth and databasedotcom-oauth2 provide identification; however, databasedotcom-oauth2 makes the interaction part easier. -### Who's it for? +Specifically, databasedotcom-oauth2: -RubyDevelopers of -Whereas OmniAuth only provides authentication, this Rack Middleware assumes you lso instantiates a Databasedotcom::Client while providing an +* 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](https://rubygems.org/gems/databasedotcom) client upon each request (using the token in session) +* provides a mixin for your app containing utility methods like unauthenticated?, client, etc. - authentication and you need to query or manipulate salesforce.com data in addition to authentication. +Demos +------- -### Benefits: +**<a href="https://db-oauth2-sinatra-basic.herokuapp.com" target="_blank">Simple example using Sinatra</a>**&nbsp;&nbsp;<a href="https://github.com/richardvanhook/databasedotcom-oauth2-sinatra-basic" target="_blank">view source on github</a> -* Hides OAuth2 hand-shake complexity against multiple salesforce.com endpoints (prod vs sandbox) including support for My Domain. -* Configurable/override-able options for scope, display, immediate -* OAuth2 Token encrypted and stored in session, supports any Rack:Session type - Cookie, Pool, etc. -* Materializes Databasedotcom::Client from token upon each request -* Databasedotcom::OAuth2::Helpers mixin provides convenience methods client, me, etc. +**<a href="https://db-oauth2-sinatra-jqm.herokuapp.com" target="_blank">In-depth configuration with JQuery Mobile</a>**&nbsp;&nbsp;<a href="https://github.com/richardvanhook/databasedotcom-oauth2-sinatra-jqm" target="_blank">view source on github</a> -## Demos +Usage +------- -<a href="https://db-oauth2-sinatra-basic.herokuapp.com" target="_blank">Sinatra Basic</a><a href="https://github.com/richardvanhook/databasedotcom-oauth2-sinatra-basic" target="_blank">(source)</a> +### Minimal -<a href="https://db-oauth2-sinatra-jqm.herokuapp.com" target="_blank">Sinatra showing authentication options along with JQuery Mobile</a><a href="https://github.com/richardvanhook/databasedotcom-oauth2-sinatra-jqm" target="_blank">(source)</a> +```ruby +require "databasedotcom-oauth" +use Databasedotcom::OAuth2::WebServerFlow, + :token_encryption_key => "replace me", + :endpoints => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"}} +``` -## Usage +Insert above code wherever your [Rack](http://rack.github.com/) Stack is defined. See [Required Configuration Parameters](#required-configuration-parameters) for more information on parameters. -### Required +### Multiple Endpoints -`:token_encryption_key` & `:endpoints` are required. databasedotcom-oauth2 encrypts oauth2 token using `:token_encryption_key` and stores it in rack.session for further use. `:endpoints` defines the server endpoints to be available; multiple can be specified but at least one is required. - ```ruby use Databasedotcom::OAuth2::WebServerFlow, - :token_encryption_key => TOKEN_ENCRYPTION_KEY, - :endpoints => {"login.salesforce.com" => {:keys => CLIENT_ID, :secret => CLIENT_SECRET}} + :endpoints => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"}, + "test.salesforce.com" => {:key => "replace me", :secret => "replace me"}} ``` -### Multiple Endpoints - +### Authentication ```ruby use Databasedotcom::OAuth2::WebServerFlow, - :endpoints => {"login.salesforce.com" => {:keys => CLIENT_ID1, :secret => CLIENT_SECRET1}, - "test.salesforce.com" => {:keys => CLIENT_ID2, :secret => CLIENT_SECRET2}} + :display => "touch" , #default is "page" + :immediate => true , #default is false + :prompt => "login consent", #default is nil + :scope => "full" #default is "id api refresh_token" ``` -### Authentication Options + +### Miscellaneous ```ruby use Databasedotcom::OAuth2::WebServerFlow, - :scope => "full", #default is "id api refresh_token" - :display => "touch", #default is "page" - :immediate => true #default is false - :scope_override => true, #default is false - :display_override => true, #default is false - :immediate_override => true, #default is false + :api_version => "24.0" , #default is 25.0 + :debugging => "true" , #default is false + :path_prefix => "/auth/sfdc" #default is /auth/salesforce ``` -## Parameters +Required Configuration Parameters +----------------------------------- -### `:endpoints` +* **`:endpoints`** + Hash of remote access applications; at least one is required. Values must be generated via [salesforce.com](http://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: + ```ruby + :endpoints => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"} + "test.salesforce.com" => {:key => "replace me", :secret => "replace me"}} + ``` -### `:token_encryption_key` + *Default:* nil -It's uber important that `:token_encryption_key` is sufficiently strong. To generate a sufficiently strong key, run following: +* **`:token_encryption_key`** - $ ruby -ropenssl -rbase64 -e "puts Base64.strict_encode64(OpenSSL::Random.random_bytes(16).to_str)" + 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. -Then, in your code, decrypt prior using: + ``` + ruby -ropenssl -rbase64 -e "puts Base64.strict_encode64(OpenSSL::Random.random_bytes(16).to_str)" + ``` -```ruby -Base64.strict_decode64(TOKEN_ENCRYPTION_KEY) -``` + 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: -## Resources + ```ruby + require "base64" + Base64.strict_decode64(ENV['TOKEN']) + ``` + *Default:* nil + +Optional Configuration Parameters +----------------------------------- + +* **`:display`, `:immediate`, `:prompt`, `:scope`** + + Values passed directly to [salesforce.com](http://salesforce.com/) which control authentication behavior. See [OAuth 2.0 Web Server Authentication Flow](http://na12.salesforce.com/help/doc/en/remoteaccess_oauth_web_server_flow.htm#heading_2_1) for detailed explanation as well as valid and default values. + + *Default:* see [OAuth 2.0 Web Server Authentication Flow](http://na12.salesforce.com/help/doc/en/remoteaccess_oauth_web_server_flow.htm#heading_2_1) + +* **`: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](http://www.salesforce.com/us/developer/docs/api/Content/whats_new.htm) + + *Default:* 25.0 + +* **`:debugging`** + + Will enable debug output for both this gem and [databasedotcom](https://rubygems.org/gems/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](http://salesforce.com/). + + *Default:* /auth/salesforce + +## Resources +* [OAuth 2.0 Web Server Authentication Flow](http://na12.salesforce.com/help/doc/en/remoteaccess_oauth_web_server_flow.htm) * [Article: Digging Deeper into OAuth 2.0 on Force.com](http://wiki.developerforce.com/index.php/Digging_Deeper_into_OAuth_2.0_on_Force.com) \ No newline at end of file