restful_api_authentication 0.1.2 → 0.2.0

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change History / Release Notes
 
+## Version 0.2.0
+
+* Added verbose error messaging; if this is enabled in the YML config file, then the response to an authentication failure will be more descriptive as to why the authentication failed.
+
 ## Version 0.1.2
 
 * Resolved Issue #2: UUID gem is not required and therefore throws an error when this gem is used.

data/README.md

@@ -4,6 +4,8 @@ RestfulApiAuthentication is a gem which implements a standard api_key/secret aut
 
 With most RESTful Web API's, it is important to know which app is using your resources and that only the apps you allow access those resources. This gem allows you to easily add this layer of authentication to any Rails RESTful resource you want, and it even includes protection against various forms of attack.
 
+Go here to read a more lengthy description of the problem this gem is attempting to solve: [Authentication of a Ruby on Rails RESTful Web API / Service](http://www.djkiger.com/?p=41)
+
 ## Requirements
 
 1. Rails 3.2.0+

data/lib/generators/restful_api_authentication/install/templates/restful_api_authentication.yml

@@ -1,6 +1,7 @@
 defaults: &DEFAULTS
-  request_window: 10 # request window in minutes - between 5 and 10 is usually best; must be at least 2
-  header_names:      # names of HTTP headers that must be sent on all requests requiring authentication
+  request_window: 10    # request window in minutes - between 5 and 10 is usually best; must be at least 2
+  verbose_errors: false # if false, error response will always be "not authorized", otherwise it will be more descriptive of why authentication failed
+  header_names:         # names of HTTP headers that must be sent on all requests requiring authentication
     timestamp: "x-timestamp"
     signature: "x-signature"
     api_key: "x-api-key"

data/lib/restful_api_authentication/checker.rb

@@ -24,24 +24,42 @@
 module RestfulApiAuthentication
   class Checker
     # Class attributes which are set when the Rails application is initialized: locally cached version of configuration settings stored in YML file.
-    cattr_accessor :header_timestamp, :header_signature, :header_api_key, :time_window
-    attr_accessor :http_headers, :request_uri
+    cattr_accessor :header_timestamp, :header_signature, :header_api_key, :time_window, :verbose_errors
+    attr_accessor :http_headers, :request_uri, :errors
     
     def initialize(http_headers, request_uri)
       @http_headers = http_headers
       @request_uri = request_uri
+      @errors = []
     end
 
     # Checks if the current request passes authorization
     def authorized?(options = {})
       raise "Configuration values not found. Please run rails g restful_api_authentication:install to generate a config file." if @@header_timestamp.nil? || @@header_signature.nil? || @@header_api_key.nil? || @@time_window.nil?
       return_val = false
-      if headers_have_values? && in_time_window?
-        if (options[:require_master] == true)
-          return_val = true if test_hash == @http_headers[@@header_signature] && is_master?
+      if headers_have_values?
+        if in_time_window?
+          if test_hash == @http_headers[@@header_signature]
+            if options[:require_master] == true
+              if is_master?
+                return_val = true
+              else
+                @errors << "client does not have the required permissions"
+              end
+            else
+              return_val = true
+            end
+          else
+            @errors << "signature is invalid"
+          end
         else
-          return_val = true if test_hash == @http_headers[@@header_signature]
+          @errors << "request is outside the required time window of #{@@time_window.to_s} minutes"
         end
+      else
+        @errors << "one or more required headers is missing"
+      end
+      if return_val == false && @errors.count == 0
+        @errors << "authentication failed"
       end
       return_val
     end
@@ -72,6 +90,9 @@ module RestfulApiAuthentication
       # generates the string that is hashed to produce the signature
       def str_to_hash
         client = RestClient.where(:api_key => @http_headers[@@header_api_key]).first
+        if client.nil?
+          @errors << "client is not registered"
+        end
         client.nil? ? "" : client.secret + @request_uri.gsub( /\?.*/, "" ) + @http_headers[@@header_timestamp]
       end
 

data/lib/restful_api_authentication/railtie.rb

@@ -24,17 +24,18 @@
 module RestfulApiAuthentication
   class Railtie < Rails::Railtie
     initializer "restful_api_authentication_railtie.config_initializer" do
+      RestfulApiAuthentication::Checker.time_window      = 4
+      RestfulApiAuthentication::Checker.header_timestamp = 'x-timestamp'
+      RestfulApiAuthentication::Checker.header_signature = 'x-signature'
+      RestfulApiAuthentication::Checker.header_api_key   = 'x-api-key'
+      RestfulApiAuthentication::Checker.verbose_errors   = false
       if File.exists? Rails.root.join('config', 'restful_api_authentication.yml')
         config_data = YAML::load_file(Rails.root.join('config', 'restful_api_authentication.yml'))[Rails.env]
-        RestfulApiAuthentication::Checker.time_window      = config_data['request_window']
-        RestfulApiAuthentication::Checker.header_timestamp = config_data['header_names']['timestamp']
-        RestfulApiAuthentication::Checker.header_signature = config_data['header_names']['signature']
-        RestfulApiAuthentication::Checker.header_api_key   = config_data['header_names']['api_key']
-      else
-        RestfulApiAuthentication::Checker.time_window      = nil
-        RestfulApiAuthentication::Checker.header_timestamp = nil
-        RestfulApiAuthentication::Checker.header_signature = nil
-        RestfulApiAuthentication::Checker.header_api_key   = nil
+        RestfulApiAuthentication::Checker.time_window      ||= config_data['request_window']
+        RestfulApiAuthentication::Checker.header_timestamp ||= config_data['header_names']['timestamp']
+        RestfulApiAuthentication::Checker.header_signature ||= config_data['header_names']['signature']
+        RestfulApiAuthentication::Checker.header_api_key   ||= config_data['header_names']['api_key']
+        RestfulApiAuthentication::Checker.verbose_errors   ||= config_data['verbose_errors']
       end
     end
   end

data/lib/restful_api_authentication/version.rb

@@ -22,5 +22,5 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module RestfulApiAuthentication
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/restful_api_authentication.rb

@@ -39,7 +39,11 @@ module RestfulApiAuthentication
     if checker.authorized?
       return true
     else
-      respond_with(["not authorized"], :status => 401, :location => nil)
+      if checker.verbose_errors
+        respond_with(checker.errors, :status => 401, :location => nil)
+      else
+        respond_with(["not authorized"], :status => 401, :location => nil)
+      end
     end
   end
 
@@ -53,7 +57,11 @@ module RestfulApiAuthentication
     if checker.authorized?({:require_master => true})
       return true
     else
-      respond_with(["not authorized"], :status => 401, :location => nil)
+      if checker.verbose_errors
+        respond_with(checker.errors, :status => 401, :location => nil)
+      else
+        respond_with(["not authorized"], :status => 401, :location => nil)
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restful_api_authentication
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-04 00:00:00.000000000 Z
+date: 2012-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70195976870460 !ruby/object:Gem::Requirement
+  requirement: &70141551581760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.2.0
   type: :runtime
   prerelease: false
-  version_requirements: *70195976870460
+  version_requirements: *70141551581760
 - !ruby/object:Gem::Dependency
   name: uuid
-  requirement: &70195976869960 !ruby/object:Gem::Requirement
+  requirement: &70141551581260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 2.3.5
   type: :runtime
   prerelease: false
-  version_requirements: *70195976869960
+  version_requirements: *70141551581260
 - !ruby/object:Gem::Dependency
   name: chronic
-  requirement: &70195976869480 !ruby/object:Gem::Requirement
+  requirement: &70141551580780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: 0.6.7
   type: :runtime
   prerelease: false
-  version_requirements: *70195976869480
+  version_requirements: *70141551580780
 description: A gem which implements a standard api_key / secret authentication system
   for your Ruby on Rails RESTful web services.
 email: