databasedotcom-oauth2 0.1.8 → 0.1.9

data/README.md

@@ -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>
-
-## Usage
+```ruby
+require "databasedotcom-oauth"
+use Databasedotcom::OAuth2::WebServerFlow, 
+  :token_encryption_key => "replace me",
+  :endpoints => {"login.salesforce.com" => {:key => "replace me", :secret => "replace me"}}
+```
 
-### Required 
+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.
 
-`: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.  
+### Multiple Endpoints 
 
 ```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)

data/lib/databasedotcom-oauth2/version.rb

@@ -1,5 +1,5 @@
 module Databasedotcom
   module OAuth2
-    VERSION    = "0.1.8"
+    VERSION    = "0.1.9"
   end
 end

data/lib/databasedotcom-oauth2.rb

@@ -50,11 +50,6 @@ module Databasedotcom
       client
     end
 
-    #def set_org_and_user_id(orgid, userid)
-    #  @org_id        = orgid
-    #  @user_id       = userid
-    #end
-
     def org_id=(val)
       @org_id = val
     end
@@ -101,13 +96,15 @@ module Databasedotcom
           @token_encryption_key = options[:token_encryption_key]
           @path_prefix          = options[:path_prefix]
           @on_failure           = options[:on_failure]
-          @scope                = options[:scope]
           @display              = options[:display]
           @immediate            = options[:immediate]
-          @scope_override       = options[:scope_override]     || false
+          @prompt               = options[:prompt]
+          @scope                = options[:scope]
           @display_override     = options[:display_override]   || false
           @immediate_override   = options[:immediate_override] || false
-          @api_version          = options[:api_version]        || "24.0"
+          @prompt_override      = options[:prompt_override] || false
+          @scope_override       = options[:scope_override]     || false
+          @api_version          = options[:api_version]        || "25.0"
           @debugging            = options[:debugging]          || false
         end
 
@@ -180,18 +177,20 @@ module Databasedotcom
           :redirect_uri  => "#{full_host}#{@path_prefix}/callback",
           :state         => state.to_str
         }
-        auth_params[:scope]     = @scope     unless @scope.nil? || @scope.strip.empty?
         auth_params[:display]   = @display   unless @display.nil?
         auth_params[:immediate] = @immediate unless @immediate.nil?
-        
+        auth_params[:prompt]    = @prompt    unless @prompt.nil?
+        auth_params[:scope]     = @scope     unless @scope.nil? || @scope.strip.empty?
+
         #overrides
         overrides = {}
+        overrides[:display]   = request.params["display"]   unless !@display_override   || request.params["display"].nil?
+        overrides[:immediate] = request.params["immediate"] unless !@immediate_override || request.params["immediate"].nil?
+        overrides[:prompt]    = request.params["prompt"]    unless !@prompt_override || request.params["prompt"].nil?
         if @scope_override
           scope = (self.class.param_repeated(request.url, :scope) || []).join(" ")
           overrides[:scope] = scope unless scope.nil? || scope.strip.empty?
         end
-        overrides[:display]   = request.params["display"]   unless !@display_override   || request.params["display"].nil?
-        overrides[:immediate] = request.params["immediate"] unless !@immediate_override || request.params["immediate"].nil?
         auth_params.merge!(overrides)
         
         #do redirect
@@ -319,7 +318,6 @@ module Databasedotcom
           full_host = URI.parse(request.url.gsub(/\?.*$/,''))
           full_host.path = ''
           full_host.query = nil
-          #sometimes the url is actually showing http inside rails because the other layers (like nginx) have handled the ssl termination.
           full_host.scheme = 'https' if(request.env['HTTP_X_FORWARDED_PROTO'] == 'https')          
           full_host = full_host.to_s
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: databasedotcom-oauth2
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-27 00:00:00.000000000 Z
+date: 2012-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable