rails-auth 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98e7a606fb32ef7873566d049507dae530d17dc5
-  data.tar.gz: 3944a0e2f6d940b3e2dd64404ab96dab88a6be29
+  metadata.gz: 80fe77f1e603f206962d83d87f214d2f57e1dee9
+  data.tar.gz: 1c3eb52e07760479ad2254428bce28527b4deab4
 SHA512:
-  metadata.gz: 396fa09d53a3fc2d646e0b3822ecb40867de7010cd54bac5ab052a98fa0a05593b82fd7bcc870ebebd69420f866d3ccb1218990317b148223f2caebe9d48a047
-  data.tar.gz: 3e5ab68b0a75a8b1ef877c31a26f692bea39dcc4cfcd751fbb3fe9b5ea8ac9ee9d0d2056b7c09bf64b3ab64d1cead82507adb890a72186a845fc6078357dd7b6
+  metadata.gz: 18bdd7c51f0aa9844b0f7305f3a4455e93a6e3830722633924d433dd95ec608cd45354195007ca26a7020e9eb433f82ff8630a9bfe0b8b3a7a000f4024cb8bb9
+  data.tar.gz: 4d3b4b5146d98fbd5335944bbb5bba3a233f886b325430058415e4e5ca6961f273dfb9cd80744e8f0ccd839d4a12c1779b208cb6864f2df819be9fa1a2d511cc

data/CHANGES.md

@@ -1,3 +1,9 @@
+### 0.3.0 (2016-03-12)
+
+* [#12](https://github.com/square/rails-auth/pull/12)
+  Add Rails::Auth::ErrorPage::DebugMiddleware.
+  ([@tarcieri])
+
 ### 0.2.0 (2016-03-11)
 
 * [#10](https://github.com/square/rails-auth/pull/10)

data/Gemfile

@@ -6,7 +6,7 @@ end
 
 group :test do
   gem "rspec"
-  gem "rubocop", "0.36.0"
+  gem "rubocop", "0.38.0"
   gem "coveralls", require: false
   gem "certificate_authority", require: false
 end

data/README.md

@@ -406,10 +406,46 @@ exception is raised up the middleware chain. However, it's likely you would
 prefer to show an error page than have an unhandled exception.
 
 You can write your own middleware that catches `Rails::Auth::NotAuthorizedError`
-if you'd like. However, a default one is provided which renders a 403 response
-with a static page body if you find that helpful.
+if you'd like. However, this library includes two middleware for rescuing this
+exception for you and displaying an error page.
 
-To use it, add `Rails::Auth::ErrorPage::Middleware` to your app:
+#### Rails::Auth::ErrorPage::DebugMiddleware
+
+This middleware displays a detailed error page intended to help debug authorization errors:
+
+![Debug Error Page](https://raw.github.com/square/rails-auth/master/images/debug_error_page.png)
+
+Please be aware this middleware leaks information about your ACL to a potential attacker.
+Make sure you're ok with that information being public before using it. If you would like
+to avoid leaking that information, see `Rails::Auth::ErrorPage::Middleware` below.
+
+```ruby
+app = MyRackApp.new
+
+acl = Rails::Auth::ACL.from_yaml(
+  File.read("/path/to/my/acl.yaml")
+  matchers: { allow_x509_subject: Rails::Auth::X509::Matcher }
+)
+
+acl_auth = Rails::Auth::ACL::Middleware.new(app, acl: acl)
+
+x509_auth = Rails::Auth::X509::Middleware.new(
+  acl_auth,
+  ca_file: "/path/to/my/cabundle.pem"
+  cert_filters: { 'X-SSL-Client-Cert' => :pem },
+  require_cert: true
+)
+
+error_page = Rails::Auth::ErrorPage::Middleware.new(x509_auth, acl: acl)
+
+run error_page
+```
+
+#### Rails::Auth::ErrorPage::Middleware
+
+This middleware catches `Rails::Auth::NotAuthorizedError` and renders a given static HTML file,
+e.g. the 403.html file which ships with Rails. It will not give detailed errors to your users,
+but it also won't leak information to an attacker.
 
 ```ruby
 app = MyRackApp.new

data/lib/rails/auth/acl.rb

@@ -26,7 +26,7 @@ module Rails
 
         acl.each_with_index do |entry|
           resources = entry["resources"]
-          fail ParseError, "no 'resources' key present in entry: #{entry.inspect}" unless resources
+          raise ParseError, "no 'resources' key present in entry: #{entry.inspect}" unless resources
 
           predicates = parse_predicates(entry, matchers.merge(DEFAULT_MATCHERS))
 
@@ -73,8 +73,8 @@ module Rails
           next if name == "resources"
 
           matcher_class = matchers[name.to_sym]
-          fail ArgumentError, "no matcher for #{name}" unless matcher_class
-          fail TypeError, "expected Class for #{name}" unless matcher_class.is_a?(Class)
+          raise ArgumentError, "no matcher for #{name}" unless matcher_class
+          raise TypeError, "expected Class for #{name}" unless matcher_class.is_a?(Class)
 
           predicates[name.freeze] = matcher_class.new(options.freeze).freeze
         end

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

@@ -6,7 +6,7 @@ module Rails
         # Allows unauthenticated clients to access to a given resource
         class AllowAll
           def initialize(enabled)
-            fail ArgumentError, "enabled must be true/false" unless [true, false].include?(enabled)
+            raise ArgumentError, "enabled must be true/false" unless [true, false].include?(enabled)
             @enabled = enabled
           end
 

data/lib/rails/auth/acl/middleware.rb

@@ -15,14 +15,14 @@ module Rails
         #
         # @return [Rails::Auth::ACL::Middleware] new ACL middleware instance
         def initialize(app, acl: nil)
-          fail ArgumentError, "no acl given" unless acl
+          raise ArgumentError, "no acl given" unless acl
 
           @app = app
           @acl = acl
         end
 
         def call(env)
-          fail NotAuthorizedError, "unauthorized request" unless @acl.match(env)
+          raise NotAuthorizedError, "unauthorized request" unless @acl.match(env)
           @app.call(env)
         end
       end

data/lib/rails/auth/acl/resource.rb

@@ -18,11 +18,11 @@ module Rails
         # @param [Hash] :predicates matchers for this resource
         #
         def initialize(options, predicates)
-          fail TypeError, "expected Hash for options"    unless options.is_a?(Hash)
-          fail TypeError, "expected Hash for predicates" unless predicates.is_a?(Hash)
+          raise TypeError, "expected Hash for options"    unless options.is_a?(Hash)
+          raise TypeError, "expected Hash for predicates" unless predicates.is_a?(Hash)
 
           unless (extra_keys = options.keys - VALID_OPTIONS).empty?
-            fail ParseError, "unrecognized key in ACL resource: #{extra_keys.first}"
+            raise ParseError, "unrecognized key in ACL resource: #{extra_keys.first}"
           end
 
           @http_methods = extract_methods(options["method"])
@@ -63,7 +63,7 @@ module Rails
           return nil if methods.include?("ALL")
 
           methods.each do |method|
-            fail ParseError, "invalid HTTP method: #{method}" unless HTTP_METHODS.include?(method)
+            raise ParseError, "invalid HTTP method: #{method}" unless HTTP_METHODS.include?(method)
           end
 
           methods.freeze

data/lib/rails/auth/credentials.rb

@@ -25,7 +25,7 @@ module Rails
       def add_credential(env, type, credential)
         credentials = env[CREDENTIALS_ENV_KEY] ||= {}
 
-        fail ArgumentError, "credential #{type} already added to request" if credentials.key?(type)
+        raise ArgumentError, "credential #{type} already added to request" if credentials.key?(type)
         credentials[type] = credential
 
         env

data/lib/rails/auth/error_page/debug_middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "erb"
+require "cgi"
+
+module Rails
+  module Auth
+    module ErrorPage
+      # Render a descriptive access denied page with debugging information about why the given
+      # request was not authorized. Useful for debugging, but leaks information about your ACL
+      # to a potential attacker. Make sure you're ok with that information being public.
+      class DebugMiddleware
+        # Configure CSP to disable JavaScript, but allow inline CSS
+        # This is just in case someone pulls off reflective XSS, but hopefully all values are
+        # properly escaped on the page so that won't happen.
+        RESPONSE_HEADERS = {
+          "Content-Security-Policy" =>
+          "default-src 'self'; " \
+          "script-src 'none'; " \
+          "style-src 'unsafe-inline'"
+        }.freeze
+
+        def initialize(app, acl: nil)
+          raise ArgumentError, "ACL must be a Rails::Auth::ACL" unless acl.is_a?(Rails::Auth::ACL)
+
+          @app = app
+          @acl = acl
+          @erb = ERB.new(File.read(File.expand_path("../debug_page.html.erb", __FILE__))).freeze
+        end
+
+        def call(env)
+          @app.call(env)
+        rescue Rails::Auth::NotAuthorizedError
+          [403, RESPONSE_HEADERS.dup, [error_page(env)]]
+        end
+
+        def error_page(env)
+          credentials = Rails::Auth.credentials(env)
+          resources   = @acl.matching_resources(env)
+
+          @erb.result(binding)
+        end
+
+        def h(text)
+          CGI.escapeHTML(text || "")
+        end
+
+        def format_attributes(value)
+          value.respond_to?(:attributes) ? value.attributes.inspect : value.inspect
+        end
+
+        def format_path(path)
+          path.source.sub(/\A\\A/, "").sub(/\\z\z/, "")
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/error_page/debug_page.html.erb

@@ -0,0 +1,128 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Rails::Auth: Access Denied</title>
+  <style>
+    body {
+      font-family: Helvetica, Arial, sans-serif;
+      margin: 0;
+    }
+
+    #header {
+      background-color: #ddd;
+      padding: 8px 32px;
+      border-bottom: 2px solid #888;
+    }
+
+    #header h1, #header h2 {
+      margin: 0;
+      font-size: 2em;
+      display: inline-block;
+    }
+
+    #header h2 {
+      color: #880000;
+    }
+
+    #content {
+      padding: 8px 32px;
+    }
+
+    table {
+      border: 1px solid #ddd;
+      border-collapse: collapse;
+    }
+
+    tr:nth-child(odd) {
+       background-color: #eee;
+    }
+
+    td {
+      padding: 6px;
+      border-bottom: 1px solid #ddd;
+    }
+
+    td.label {
+      font-weight: bold;
+      text-align: right;
+    }
+  </style>
+</head>
+
+<body>
+  <div id="header">
+    <h1>Rails::Auth:</h1>
+    <h2>Access Denied</h2>
+  </div>
+
+  <div id="content">
+    <div id="row">
+      <p><b>Error:</b> Access to the requested resource is not allowed with your current credentials.</p>
+      <p>Below is information about the request you made and the credentials you sent:</p>
+    </div>
+
+    <div id="row">
+      <h3>Request:</h3>
+
+      <table>
+        <tr>
+          <td class="label">Method</td>
+          <td><%= h(env["REQUEST_METHOD"]) %></td>
+        </tr>
+        <tr>
+          <td class="label">Path</td>
+          <td><%= h(env["REQUEST_PATH"]) %></td>
+        </tr>
+        <tr>
+          <td class="label">Host</td>
+          <td><%= h(env["HTTP_HOST"]) %></td>
+        </tr>
+      </table>
+    </div>
+
+    <div id="row">
+      <h3>Credentials:</h3>
+
+      <% if credentials.empty? %>
+      <p><b>No credentials provided!</b> This is a likely cause of this error.</p>
+      <p>Please retry the request with proper credentials.</p>
+      <% else %>
+      <table>
+        <% credentials.each do |name, credential| %>
+        <tr>
+          <td class="label"><%= h(name) %></td>
+          <td><%= h(format_attributes(credential)) %></td>
+        </tr>
+        <% end %>
+      </table>
+      <% end %>
+    </div>
+
+    <div id="row">
+      <h3>Authorized ACL Entries:</h2>
+      <% if resources.empty? %>
+      <p><b>Error: No matching resources!</b> This is a likely cause of this error.</p>
+      <p>Please check your ACL and make sure there's an entry for this route.</p>
+      <% else %>
+      <p>The following entries in your ACL are authorized to view this paritcular route:</p>
+
+      <table>
+        <% resources.each do |resource| %>
+        <tr>
+          <td class="label"><%= h((resource.http_methods || "ALL").join(" ")) %> <%= h(format_path(resource.path)) %></td>
+          <td>
+            <ul>
+              <% resource.predicates.each do |name, predicate| %>
+              <li><%= h(name) %>: <%= h(format_attributes(predicate)) %></li>
+              <% end %>
+            </ul>
+          </td>
+        </tr>
+        <% end %>
+      </table>
+      <% end %>
+    </div>
+  </div>
+</body>
+</html>

data/lib/rails/auth/error_page/middleware.rb

@@ -4,7 +4,7 @@ module Rails
       # Render an error page in the event Rails::Auth::NotAuthorizedError is raised
       class Middleware
         def initialize(app, page_body: nil)
-          fail TypeError, "page_body must be a String" unless page_body.is_a?(String)
+          raise TypeError, "page_body must be a String" unless page_body.is_a?(String)
 
           @app       = app
           @page_body = page_body.freeze

data/lib/rails/auth/rack.rb

@@ -14,6 +14,7 @@ require "rails/auth/acl/middleware"
 require "rails/auth/acl/resource"
 
 require "rails/auth/error_page/middleware"
+require "rails/auth/error_page/debug_middleware"
 
 require "rails/auth/x509/certificate"
 require "rails/auth/x509/filter/pem"

data/lib/rails/auth/rspec/helper_methods.rb

@@ -30,7 +30,7 @@ module Rails
 
             # Warn if methods are improperly used
             unless path.chars[0] == "/"
-              fail ArgumentError, "expected #{path} to start with '/'"
+              raise ArgumentError, "expected #{path} to start with '/'"
             end
 
             env = {

data/lib/rails/auth/version.rb

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

data/lib/rails/auth/x509/certificate.rb

@@ -9,7 +9,7 @@ module Rails
 
         def initialize(certificate)
           unless certificate.is_a?(OpenSSL::X509::Certificate)
-            fail TypeError, "expecting OpenSSL::X509::Certificate, got #{certificate.class}"
+            raise TypeError, "expecting OpenSSL::X509::Certificate, got #{certificate.class}"
           end
 
           @certificate = certificate.freeze

data/lib/rails/auth/x509/middleware.rb

@@ -19,7 +19,7 @@ module Rails
         #
         # @return [Rails::Auth::X509::Middleware] new X509 middleware instance
         def initialize(app, cert_filters: {}, ca_file: nil, truststore: nil, require_cert: false, logger: nil)
-          fail ArgumentError, "no ca_file given" unless ca_file
+          raise ArgumentError, "no ca_file given" unless ca_file
 
           @app          = app
           @logger       = logger
@@ -57,11 +57,11 @@ module Rails
               return Rails::Auth::X509::Certificate.new(cert)
             else
               log("Verify FAILED", cert)
-              fail CertificateVerifyFailed, "verify failed: #{subject(cert)}" if @require_cert
+              raise CertificateVerifyFailed, "verify failed: #{subject(cert)}" if @require_cert
             end
           end
 
-          fail CertificateVerifyFailed, "no client certificate in request" if @require_cert
+          raise CertificateVerifyFailed, "no client certificate in request" if @require_cert
           nil
         end
 

data/spec/rails/auth/error_page/debug_middleware_spec.rb

@@ -0,0 +1,37 @@
+RSpec.describe Rails::Auth::ErrorPage::DebugMiddleware do
+  let(:request) { Rack::MockRequest.env_for("https://www.example.com") }
+
+  let(:example_config) { fixture_path("example_acl.yml").read }
+
+  let(:example_acl) do
+    Rails::Auth::ACL.from_yaml(
+      example_config,
+      matchers: {
+        allow_x509_subject: Rails::Auth::X509::Matcher,
+        allow_claims:       ClaimsMatcher
+      }
+    )
+  end
+
+  subject(:middleware) { described_class.new(app, acl: example_acl) }
+
+  context "access granted" do
+    let(:code) { 200 }
+    let(:app)  { ->(env) { [code, env, "Hello, world!"] } }
+
+    it "renders the expected response" do
+      response = middleware.call(request)
+      expect(response.first).to eq code
+    end
+  end
+
+  context "access denied" do
+    let(:app) { ->(_env) { raise(Rails::Auth::NotAuthorizedError, "not authorized!") } }
+
+    it "renders the error page" do
+      code, _env, body = middleware.call(request)
+      expect(code).to eq 403
+      expect(body.join).to include("Access Denied")
+    end
+  end
+end

data/spec/rails/auth/error_page/middleware_spec.rb

@@ -15,7 +15,7 @@ RSpec.describe Rails::Auth::ErrorPage::Middleware do
   end
 
   context "access denied" do
-    let(:app) { ->(_env) { fail(Rails::Auth::NotAuthorizedError, "not authorized!") } }
+    let(:app) { ->(_env) { raise(Rails::Auth::NotAuthorizedError, "not authorized!") } }
 
     it "renders the error page" do
       code, _env, body = middleware.call(request)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-auth
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-12 00:00:00.000000000 Z
+date: 2016-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -74,6 +74,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- images/debug_error_page.png
 - lib/rails/auth.rb
 - lib/rails/auth/acl.rb
 - lib/rails/auth/acl/matchers/allow_all.rb
@@ -81,6 +82,8 @@ files:
 - lib/rails/auth/acl/resource.rb
 - lib/rails/auth/controller_methods.rb
 - lib/rails/auth/credentials.rb
+- lib/rails/auth/error_page/debug_middleware.rb
+- lib/rails/auth/error_page/debug_page.html.erb
 - lib/rails/auth/error_page/middleware.rb
 - lib/rails/auth/exceptions.rb
 - lib/rails/auth/rack.rb
@@ -101,6 +104,7 @@ files:
 - spec/rails/auth/acl_spec.rb
 - spec/rails/auth/controller_methods_spec.rb
 - spec/rails/auth/credentials_spec.rb
+- spec/rails/auth/error_page/debug_middleware_spec.rb
 - spec/rails/auth/error_page/middleware_spec.rb
 - spec/rails/auth/rspec/helper_methods_spec.rb
 - spec/rails/auth/rspec/matchers/acl_matchers_spec.rb
@@ -137,3 +141,4 @@ signing_key:
 specification_version: 4
 summary: Modular resource-oriented authentication and authorization for Rails/Rack
 test_files: []
+has_rdoc: