rails-auth 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f4c0d9519675ef1b560bbc2cc2ef0dcc2b9b178
-  data.tar.gz: 2cd1b6f0f0f2462db7ab4bd280f1c54dc6bff513
+  metadata.gz: 98e7a606fb32ef7873566d049507dae530d17dc5
+  data.tar.gz: 3944a0e2f6d940b3e2dd64404ab96dab88a6be29
 SHA512:
-  metadata.gz: 91b47228828b5f448effd6e5b03d0e141b35253a388823ec5fc10ef069f9a86cbff3c7d84efa589ed513da31e1528e176671deff7fe743b7b6ad3f7121d9d7e0
-  data.tar.gz: eaaa0f23d01a3a2efcdd0c4baf65f3f6259a86b9825d10ccd96431d80529eae395f8444cf8881fb799d63a09d682ebccaf4f627b0f0bc2b77c997ce01dda96f4
+  metadata.gz: 396fa09d53a3fc2d646e0b3822ecb40867de7010cd54bac5ab052a98fa0a05593b82fd7bcc870ebebd69420f866d3ccb1218990317b148223f2caebe9d48a047
+  data.tar.gz: 3e5ab68b0a75a8b1ef877c31a26f692bea39dcc4cfcd751fbb3fe9b5ea8ac9ee9d0d2056b7c09bf64b3ab64d1cead82507adb890a72186a845fc6078357dd7b6

data/CHANGES.md

@@ -1,3 +1,10 @@
+### 0.2.0 (2016-03-11)
+
+* [#10](https://github.com/square/rails-auth/pull/10)
+  Add Rails::Auth::ControllerMethods and #credentials method for accessing
+  rails-auth.credentials from a Rails controller.
+  ([@tarcieri])
+
 ### 0.1.0 (2016-02-10)
 
 * [#6](https://github.com/square/rails-auth/pull/6):

data/README.md

@@ -21,6 +21,97 @@ Rails::Auth can be used to authenticate and authorize end users using browser
 cookies, service-to-service requests using X.509 client certificates, or any
 other clients with credentials that have proper authenticating middleware.
 
+## Architecture
+
+Rails::Auth makes use of multiple, independent, single-purpose middleware
+classes to handle specific types of AuthN/AuthZ.
+
+### AuthN
+
+Rails::Auth ships with the following AuthN middleware:
+
+* `Rails::Auth::X509::Middleware`: authenticates X.509 certificates obtained
+  from the Rack environment.
+
+The goal of Rails::Auth's AuthN middleware is to authenticate *credentials*
+taken from the Rack environment and place objects representing them under
+the `"rails-auth.credentials"` key within the Rack environment for use by
+subsequent AuthN or AuthZ middleware. The built-in support is for X.509
+client certificates, but other middleware could handle authentication of
+cookies or (OAuth) bearer credentials.
+
+The intended usage is to have multiple AuthN middlewares that are capable
+of extracting different types of credentials, but also allowing AuthZ
+middleware to apply a single policy to all of them. It's also possible to
+chain AuthN middleware together such that one credential obtained earlier
+in the middleware stack is used to authenticate another (for e.g.
+[channel-bound cookies]).
+
+[channel-bound cookies]: http://www.browserauth.net/channel-bound-cookies
+
+### AuthZ
+
+Rails::Auth ships with one primary AuthZ middleware:
+
+* `Rails::Auth::ACL::Middleware`: support for Access Control Lists.
+
+Access Control Lists (ACLs) let you write a single, declarative policy for
+authorization in your application. ACLs are pluggable and let you write
+a single policy which can authorize access using different types of
+credentials.
+
+ACLs are a declarative approach to authorization, consolidating policies
+into a single file that can be easily audited by a security team without
+deep understanding of the many eccentricities of Rails. These policies
+provide coarse-grained authorization based on routes (as matched by
+regexes) and the credentials extracted by the AuthN middleware. However,
+the do not provide AuthZ which includes specific domain objects, or
+policies around them.
+
+## Comparison to other Rails/Rack auth libraries/frameworks
+
+Below is a comparison of how Rails::Auth relates to the existing landscape
+of Rails AuthN and AuthZ libraries. These are grouped into two different
+categories: libraries Rails::Auth replaces, and libraries with which 
+Rails::Auth can be used in a complimentary fashion.
+
+### Replaces:
+
+* [Warden]: Uses a single "opinionated" Rack middleware providing
+  user-centric authentication and methods that allow controllers
+  to imperatively interrogate the authentication context for
+  authorization purposes. By comparison Rails::Auth is not prescriptive
+  and much more flexible about credential types (supporting credentials 
+  for both user and service clients) and uses declarative authorization
+  policies in the form of ACLs.
+
+* [Devise]: A mature, flexible, expansive framework primarily intended
+  for user authentication. Some of the same caveats as Warden apply,
+  however Devise provides a framework for modeling users within a Rails
+  app along with common authentication flows, making it somewhat
+  orthogonal to what Rails::Auth provides. Rails::Auth is designed to
+  easily support [claims-based identity] systems where user identity
+  is outsourced to a separate microservice.
+
+### Compliments:
+
+* [Pundit]: Domain object-centric fine-grained authorization using clean
+  object-oriented APIs. Pundit makes authorization decisions around particular
+  objects based on policy objects and contexts. Rails::Auth's credentials
+  can be used as a powerful policy context for Pundit.
+
+* [CanCanCan]: a continuation of the popular CanCan AuthZ library after a
+  period of neglect. Uses a more DSL-like approach to AuthZ than Pundit,
+  but provides many facilities similar to Pundit for domain object-centric
+  AuthZ.
+
+[Warden]: https://github.com/hassox/warden/wiki
+[Devise]: https://github.com/plataformatec/devise
+[Pundit]: https://github.com/elabs/pundit
+[CanCanCan]: https://github.com/CanCanCommunity/cancancan
+
+[claims-based identity]: https://en.wikipedia.org/wiki/Claims-based_identity
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -51,13 +142,38 @@ Rails::Auth ships with the following middleware:
 
 Documentation of these middleware and how to use them is provided below.
 
+
+### Controller Methods
+
+Rails::Auth includes a module of helper methods you can use from Rails
+controllers. Include them like so:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Rails::Auth::ControllerMethods
+
+  def x509_certificate_ou
+    credentials[:x509].try(:ou)
+  end
+
+  def current_username
+    # Note: Rails::Auth doesn't provide a middleware to extract this, it's
+    # just an example of how you could use it with your own claims-based
+    # identity system.
+    credentials[:identity_claims].try(:username)
+  end
+end
+```
+
+This defines the following methods:
+
+* `#credentials`: obtain a HashWithIndifferentAccess containing all of the
+  credentials that Rails::Auth has extracted using its AuthN middleware.
+
 ### Access Control Lists (ACLs)
 
 ACLs are the main tool Rails::Auth provides for AuthZ. ACLs use a set of
 route-by-route matchers to control access to particular resources.
-Unlike some Rails AuthZ frameworks, this gem grants/denies access to
-controller actions, rather than helping you provide different content to
-different roles or varying the parameters allowed in, say, an update action.
 
 Rails::Auth encourages the use of YAML files for storing ACL definitions,
 although the use of YAML is not mandatory and the corresponding object

data/lib/rails/auth.rb

@@ -2,3 +2,6 @@
 
 # Pull in core library components that work with any Rack application
 require "rails/auth/rack"
+
+# Rails controller method support
+require "rails/auth/controller_methods"

data/lib/rails/auth/acl.rb

@@ -1,16 +1,14 @@
+# Pull in default predicate matchers
+require "rails/auth/acl/matchers/allow_all"
+
 module Rails
   module Auth
     # Route-based access control lists
     class ACL
       # Predicate matchers available by default in ACLs
-      # These are added by the individual files in lib/rails/auth/acl/matchers
-      # at the time they're loaded.
-      DEFAULT_MATCHERS = {} # rubocop:disable Style/MutableConstant
-
-      # Pull in default predicate matchers
-      require "rails/auth/acl/matchers/allow_all"
-
-      DEFAULT_MATCHERS.freeze
+      DEFAULT_MATCHERS = {
+        allow_all: Matchers::AllowAll
+      }.freeze
 
       # Create a Rails::Auth::ACL from a YAML representation of an ACL
       #

data/lib/rails/auth/acl/matchers/allow_all.rb

@@ -14,9 +14,6 @@ module Rails
             @enabled
           end
         end
-
-        # Make `allow_all` available by default as an ACL matcher
-        ACL::DEFAULT_MATCHERS[:allow_all] = AllowAll
       end
     end
   end

data/lib/rails/auth/controller_methods.rb

@@ -0,0 +1,20 @@
+require "active_support/hash_with_indifferent_access"
+
+module Rails
+  module Auth
+    # Convenience methods designed to be included in an ActionController::Base subclass
+    # Recommended use: include in ApplicationController
+    module ControllerMethods
+      # Obtain credentials for the current request
+      #
+      # @return [HashWithIndifferentAccess] credentials extracted from the environment
+      #
+      def credentials
+        @_rails_auth_credentials ||= begin
+          creds = Rails::Auth.credentials(request.env)
+          HashWithIndifferentAccess.new(creds).freeze
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/credentials.rb

@@ -27,6 +27,8 @@ module Rails
 
         fail ArgumentError, "credential #{type} already added to request" if credentials.key?(type)
         credentials[type] = credential
+
+        env
       end
     end
 

data/lib/rails/auth/version.rb

@@ -3,6 +3,6 @@
 module Rails
   # Pluggable authentication and authorization for Rack/Rails
   module Auth
-    VERSION = "0.1.0".freeze
+    VERSION = "0.2.0".freeze
   end
 end

data/spec/rails/auth/controller_methods_spec.rb

@@ -0,0 +1,25 @@
+RSpec.describe Rails::Auth::ControllerMethods do
+  let(:controller_class) do
+    Class.new do
+      attr_reader :request
+
+      def initialize(env)
+        @request = OpenStruct.new(env: env)
+      end
+
+      include Rails::Auth::ControllerMethods
+    end
+  end
+
+  describe "#credentials" do
+    let(:example_credential_type)  { "x509" }
+    let(:example_credential_value) { instance_double(Rails::Auth::X509::Certificate) }
+
+    let(:example_env) { Rails::Auth.add_credential({}, example_credential_type, example_credential_value) }
+    let(:example_controller) { controller_class.new(example_env) }
+
+    it "extracts credentials from the Rack environment" do
+      expect(example_controller.credentials[example_credential_type.to_sym]).to eq example_credential_value
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-auth
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-11 00:00:00.000000000 Z
+date: 2016-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -79,6 +79,7 @@ files:
 - lib/rails/auth/acl/matchers/allow_all.rb
 - lib/rails/auth/acl/middleware.rb
 - lib/rails/auth/acl/resource.rb
+- lib/rails/auth/controller_methods.rb
 - lib/rails/auth/credentials.rb
 - lib/rails/auth/error_page/middleware.rb
 - lib/rails/auth/exceptions.rb
@@ -98,6 +99,7 @@ files:
 - spec/rails/auth/acl/middleware_spec.rb
 - spec/rails/auth/acl/resource_spec.rb
 - spec/rails/auth/acl_spec.rb
+- spec/rails/auth/controller_methods_spec.rb
 - spec/rails/auth/credentials_spec.rb
 - spec/rails/auth/error_page/middleware_spec.rb
 - spec/rails/auth/rspec/helper_methods_spec.rb