Add Rails::Auth::ControllerMethods

This defines a single method `#credentials` which provides a useful
shorthand for accessing rails-auth.credentials from the Rack
environment. It wrapps it in a HashWithIndifferentAccess for eash
access.

README.md

@@ -51,6 +51,34 @@ 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

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"

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

lib/rails/auth/credentials.rb

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

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