rails-auth 0.0.0 → 0.0.1

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Rails
+  module Auth
+    module X509
+      # Raised when certificate verification is mandatory
+      CertificateVerifyFailed = Class.new(NotAuthorizedError)
+
+      # Validates X.509 client certificates and adds principal objects for valid
+      # clients to the rack environment as env["rails-auth.principals"]["x509"]
+      class Middleware
+        # Create a new X.509 Middleware object
+        #
+        # @param [Object]               app next app in the Rack middleware chain
+        # @param [Hash]                 cert_filters maps Rack environment names to cert extractors
+        # @param [String]               ca_file path to the CA bundle to verify client certs with
+        # @param [OpenSSL::X509::Store] truststore (optional) provide your own truststore (for e.g. CRLs)
+        # @param [Boolean]              require_cert causes middleware to raise if certs are unverified
+        #
+        # @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
+
+          @app          = app
+          @logger       = logger
+          @truststore   = truststore || OpenSSL::X509::Store.new.add_file(ca_file)
+          @require_cert = require_cert
+          @cert_filters = cert_filters
+
+          @cert_filters.each do |key, filter|
+            next unless filter.is_a?(Symbol)
+
+            # Shortcut syntax for symbols
+            @cert_filters[key] = Rails::Auth::X509::Filter.const_get(filter.to_s.capitalize).new
+          end
+        end
+
+        def call(env)
+          principal = extract_principal(env)
+          Rails::Auth.add_principal(env, "x509".freeze, principal.freeze) if principal
+
+          @app.call(env)
+        end
+
+        private
+
+        def extract_principal(env)
+          @cert_filters.each do |key, filter|
+            raw_cert = env[key]
+            next unless raw_cert
+
+            cert = filter.call(raw_cert)
+            next unless cert
+
+            if @truststore.verify(cert)
+              log("Verified", cert)
+              return Rails::Auth::X509::Principal.new(cert)
+            else
+              log("Verify FAILED", cert)
+              fail CertificateVerifyFailed, "verify failed: #{subject(cert)}" if @require_cert
+            end
+          end
+
+          fail CertificateVerifyFailed, "no client certificate in request" if @require_cert
+          nil
+        end
+
+        def log(message, cert)
+          @logger.debug("rails-auth: #{message} (#{subject(cert)})") if @logger
+        end
+
+        def subject(cert)
+          cert.subject.to_a.map { |attr, data| "#{attr}=#{data}" }.join(",")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rails
+  module Auth
+    module X509
+      # HTTPS principal identified by an X.509 client certificate
+      class Principal
+        attr_reader :certificate
+
+        def initialize(certificate)
+          unless certificate.is_a?(OpenSSL::X509::Certificate)
+            fail TypeError, "expecting OpenSSL::X509::Certificate, got #{certificate.class}"
+          end
+
+          @certificate = certificate.freeze
+          @subject = {}
+
+          @certificate.subject.to_a.each do |name, data, _type|
+            @subject[name.freeze] = data.freeze
+          end
+
+          @subject.freeze
+        end
+
+        def [](component)
+          @subject[component.to_s.upcase]
+        end
+
+        def cn
+          @subject["CN".freeze]
+        end
+        alias common_name cn
+
+        def ou
+          @subject["OU".freeze]
+        end
+        alias organizational_unit ou
+      end
+    end
+  end
+end

data/rails-auth.gemspec

@@ -1,23 +1,34 @@
 # coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'rails/auth/version'
+require "rails/auth/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "rails-auth"
   spec.version       = Rails::Auth::VERSION
   spec.authors       = ["Tony Arcieri"]
-  spec.email         = ["bascule@gmail.com"]
+  spec.email         = ["tonyarcieri@squareup.com"]
+  spec.homepage      = "https://github.com/square/rails-auth/"
+  spec.licenses      = ["Apache-2.0"]
 
-  spec.summary       = "Placeholder for an upcoming gem. Stay tuned!"
-  spec.description   = "An exciting gem awaits this name really soon now!"
+  spec.summary       = "Modular resource-oriented authentication and authorization for Rails/Rack"
+  spec.description   = <<-DESCRIPTION.strip.gsub(/\s+/, " ")
+    A plugin-based framework for supporting multiple authentication and
+    authorization systems in Rails/Rack apps. Supports resource-oriented
+    route-by-route access control lists with TLS authentication.
+  DESCRIPTION
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  # Only allow gem to be pushed to https://rubygems.org
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.files         = `git ls-files`.split("\n")
   spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.required_ruby_version = ">= 2.0.0"
+
+  spec.add_runtime_dependency "rack"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
 end

data/spec/fixtures/example_acl.yml

@@ -0,0 +1,27 @@
+---
+- resources:
+  - method: ALL
+    path: /foo/bar/.*
+  allow_x509_subject:
+    ou: ponycopter
+  allow_claims:
+    group: example
+- resources:
+  - method: GET
+    path: /baz/.*
+  allow_x509_subject:
+    ou: ponycopter
+- resources:
+  - method: ALL
+    path: /_admin/?.*
+  allow_claims:
+    group: admins
+- resources:
+  - method: GET
+    path: /internal/frobnobs/.*
+  allow_x509_subject:
+    ou: frobnobber
+- resources:
+  - method: GET
+    path: /
+  allow_all: true

data/spec/rails/auth/acl/matchers/allow_all_spec.rb

@@ -0,0 +1,32 @@
+RSpec.describe Rails::Auth::ACL::Matchers::AllowAll do
+  let(:predicate)   { described_class.new(enabled) }
+  let(:example_env) { env_for(:get, "/") }
+
+  describe "#initialize" do
+    it "raises if given nil" do
+      expect { described_class.new(nil) }.to raise_error(ArgumentError)
+    end
+
+    it "raises if given a non-boolean" do
+      expect { described_class.new(42) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#match" do
+    context "enabled" do
+      let(:enabled) { true }
+
+      it "allows all requests" do
+        expect(predicate.match(example_env)).to eq true
+      end
+    end
+
+    context "disabled" do
+      let(:enabled) { false }
+
+      it "rejects all requests" do
+        expect(predicate.match(example_env)).to eq false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require "logger"
+
+RSpec.describe Rails::Auth::ACL::Middleware do
+  let(:request)     { Rack::MockRequest.env_for("https://www.example.com") }
+  let(:app)         { ->(env) { [200, env, "Hello, world!"] } }
+  let(:acl)         { instance_double(Rails::Auth::ACL, match: authorized) }
+  let(:middleware)  { described_class.new(app, acl: acl) }
+
+  context "authorized" do
+    let(:authorized) { true }
+
+    it "allows authorized requests" do
+      expect(middleware.call(request)[0]).to eq 200
+    end
+  end
+
+  context "unauthorized" do
+    let(:authorized) { false }
+
+    it "raises Rails::Auth::NotAuthorizedError for unauthorized requests" do
+      expect { expect(middleware.call(request)) }.to raise_error(Rails::Auth::NotAuthorizedError)
+    end
+  end
+end

data/spec/rails/auth/acl/resource_spec.rb

@@ -0,0 +1,105 @@
+RSpec.describe Rails::Auth::ACL::Resource do
+  let(:example_method) { "GET" }
+  let(:another_method) { "POST" }
+  let(:example_path)   { "/foobar" }
+  let(:another_path)   { "/baz" }
+
+  let(:example_options) do
+    {
+      "method" => example_method,
+      "path"   => example_path
+    }
+  end
+
+  let(:example_predicates) { { "example" => double(:predicate, match: predicate_matches) } }
+  let(:example_resource)   { described_class.new(example_options, example_predicates) }
+  let(:example_env)        { env_for(example_method, example_path) }
+
+  describe "#initialize" do
+    it "initializes with a method and a path" do
+      resource = described_class.new(
+        {
+          "method" => example_method,
+          "path"   => example_path
+        },
+        {}
+      )
+
+      expect(resource.http_methods).to eq [example_method]
+    end
+
+    it "accepts ALL as a specifier for all HTTP methods" do
+      resource = described_class.new(
+        {
+          "method" => "ALL",
+          "path"   => example_path
+        },
+        {}
+      )
+
+      expect(resource.http_methods).to eq nil
+    end
+
+    context "errors" do
+      let(:invalid_method) { "DERP" }
+
+      it "raises ParseError for invalid HTTP methods" do
+        expect do
+          described_class.new(
+            {
+              "method" => invalid_method,
+              "path"   => example_path
+            },
+            {}
+          )
+        end.to raise_error(Rails::Auth::ParseError)
+      end
+    end
+  end
+
+  describe "#match" do
+    context "with matching predicates and method/path" do
+      let(:predicate_matches) { true }
+
+      it "matches against a valid resource" do
+        expect(example_resource.match(example_env)).to eq true
+      end
+    end
+
+    context "without matching predicates" do
+      let(:predicate_matches) { false }
+
+      it "doesn't match against a valid resource" do
+        expect(example_resource.match(example_env)).to eq false
+      end
+    end
+
+    context "without a method/path match" do
+      let(:predicate_matches) { true }
+
+      it "doesn't match" do
+        env = env_for(another_method, example_path)
+        expect(example_resource.match(env)).to eq false
+      end
+    end
+  end
+
+  describe "#match_method_and_path" do
+    let(:predicate_matches) { false }
+
+    it "matches against all methods if specified" do
+      resource = described_class.new(example_options.merge("method" => "ALL"), example_predicates)
+      expect(resource.match_method_and_path(example_env)).to eq true
+    end
+
+    it "doesn't match if the method mismatches" do
+      env = env_for(another_method, example_path)
+      expect(example_resource.match_method_and_path(env)).to eq false
+    end
+
+    it "doesn't match if the path mismatches" do
+      env = env_for(example_method, another_path)
+      expect(example_resource.match_method_and_path(env)).to eq false
+    end
+  end
+end

data/spec/rails/auth/acl_spec.rb

@@ -0,0 +1,28 @@
+RSpec.describe Rails::Auth::ACL do
+  let(:example_config) { fixture_path("example_acl.yml").read }
+
+  let(:example_acl) do
+    described_class.from_yaml(
+      example_config,
+      matchers: {
+        allow_x509_subject: Rails::Auth::X509::Matcher,
+        allow_claims:       ClaimsPredicate
+      }
+    )
+  end
+
+  describe "#match" do
+    it "matches routes against the ACL" do
+      expect(example_acl.match(env_for(:get, "/"))).to eq true
+      expect(example_acl.match(env_for(:get, "/foo/bar/baz"))).to eq true
+      expect(example_acl.match(env_for(:get, "/_admin"))).to eq false
+    end
+  end
+
+  describe "#matching_resources" do
+    it "finds Rails::Auth::ACL::Resource objects that match the request" do
+      resources = example_acl.matching_resources(env_for(:get, "/foo/bar/baz"))
+      expect(resources.first.path).to eq %r{\A/foo/bar/.*\z}
+    end
+  end
+end

data/spec/rails/auth/principals_spec.rb

@@ -0,0 +1,36 @@
+RSpec.describe Rails::Auth::Principals do
+  describe "#principals" do
+    let(:example_type)       { "example" }
+    let(:example_principals) { { example_type => double(:principal) } }
+
+    let(:example_env) do
+      env_for(:get, "/").tap do |env|
+        env[Rails::Auth::PRINCIPALS_ENV_KEY] = example_principals
+      end
+    end
+
+    it "extracts principals from Rack environments" do
+      expect(Rails::Auth.principals(example_env)).to eq example_principals
+    end
+  end
+
+  describe "#add_principal" do
+    let(:example_type)      { "example" }
+    let(:example_principal) { double(:principal) }
+    let(:example_env)       { env_for(:get, "/") }
+
+    it "adds principals to a Rack environment" do
+      expect(Rails::Auth.principals(example_env)[example_type]).to be_nil
+      Rails::Auth.add_principal(example_env, example_type, example_principal)
+      expect(Rails::Auth.principals(example_env)[example_type]).to eq example_principal
+    end
+
+    it "raises ArgumentError if the same type of principal is added twice" do
+      Rails::Auth.add_principal(example_env, example_type, example_principal)
+
+      expect do
+        Rails::Auth.add_principal(example_env, example_type, example_principal)
+      end.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/rails/auth/rspec/helper_methods_spec.rb

@@ -0,0 +1,42 @@
+RSpec.describe Rails::Auth::RSpec::HelperMethods, acl_spec: true do
+  let(:example_cn) { "127.0.0.1" }
+  let(:example_ou) { "ponycopter" }
+
+  describe "#x509_principal" do
+    subject { x509_principal(cn: example_cn, ou: example_ou) }
+
+    it "creates instance doubles for Rails::Auth::X509::Principals" do
+      # Method syntax
+      expect(subject.cn).to eq example_cn
+      expect(subject.ou).to eq example_ou
+
+      # Hash-like syntax
+      expect(subject[:cn]).to eq example_cn
+      expect(subject[:ou]).to eq example_ou
+    end
+  end
+
+  describe "#x509_principal_hash" do
+    subject { x509_principal_hash(cn: example_cn, ou: example_ou) }
+
+    it "creates a principal hash with an Rails::Auth::X509::Principal double" do
+      expect(subject["x509"].cn).to eq example_cn
+    end
+  end
+
+  Rails::Auth::ACL::Resource::HTTP_METHODS.each do |method|
+    describe "##{method.downcase}_request" do
+      it "returns a Rack environment" do
+        # These methods introspect self.class.description to find the path
+        allow(self.class).to receive(:description).and_return("/")
+        env = method("#{method.downcase}_request").call
+
+        expect(env["REQUEST_METHOD"]).to eq method
+      end
+
+      it "raises ArgumentError if the description doesn't start with /" do
+        expect { method("#{method.downcase}_request").call }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end