casrack_the_authenticator 1.4.0

data/README.rdoc

@@ -0,0 +1,87 @@
+Casrack the Authenticator is a
+Rack[http://github.com/chneukirchen/rack] middleware
+that provides CAS[http://www.jasig.org/cas] support.
+
+As of the current version, Casrack the Authenticator only supports the most basic
+of CAS scenarios: it requires CAS authentication if it receives a 401 Unauthorized
+response from lower-down in the Rack stack, and it stores the authentication token
+in the session (so logout happens when users close their browers).  Casrack the Authenticator
+is a very open-minded beast, though, so please contribute (well-tested) additions to do
+proxy-authentication and single-sign-out, or for anything else you desire.
+
+=== How-To
+
+==== 1: install
+
+  [sudo] gem install casrack_the_authenticator
+
+==== 2: set up the middleware:
+
+  # in your rackup:
+  use CasrackTheAuthenticator::Simple, :cas_server => "http://cas.mycompany.com/cas"
+  # or "config.middleware.use" if you're on Rails
+  
+See CasrackTheAuthenticator::Configuration for specifics on that Hash argument.
+
+==== 3: optionally install CasrackTheAuthenticator::RequireCAS if you want _every_ request to require CAS authentication:
+   
+  # in your rackup:
+  use CasrackTheAuthenticator::Simple, :cas_server => ...
+  use CasrackTheAuthenticator::RequireCAS
+  # or "config.middleware.use" if you're on Rails
+   
+==== 4: pull the authenticated CAS username out of the Rack session:
+
+  # in a Rack app:
+  def call(env)
+    user = cas_user(env)
+    ...
+  end
+  
+  def cas_user(env)
+    username = Rack::Request.new(env).session[CasrackTheAuthenticator::USERNAME_PARAM]
+    User.find_by_username(username)
+  end
+  
+  # or, in a Rails controller:
+  
+  def cas_user
+    username = Rack::Request.new(request.env).session[CasrackTheAuthenticator::USERNAME_PARAM]
+    User.find_by_username(username)
+  end
+
+=== Disconnected (Fake) Mode
+
+I've often found myself working on a CAS-ified project while away from the office
+and unable to access the CAS server. To support this type of disconnected development,
+just substitute in the CasrackTheAuthenticator::Fake middleware. It acts like
+CasrackTheAuthenticator::Simple, but it uses HTTP Basic authentication against a
+preset list of usernames.
+
+A common pattern for Rails apps is to create a disconnected environment:
+
+==== 1: set up <tt>[rails_root]/config/database.yml</tt>
+
+  development: &DEV
+    adapter: sqlite3
+    database: db/development.sqlite3
+    pool: 5
+    timeout: 5000
+
+  # development mode when disconnected from MITRE
+  disconnected:
+    <<: *DEV
+    
+==== 2: set up <tt>[rails_root]/config/disconnected.rb</tt>:
+
+  load './development.rb'
+  config.middleware.swap 'CasrackTheAuthenticator::Simple', CasrackTheAuthenticator::Fake, 'jimbob', 'sueann'
+  
+==== 3: run in disconnected mode:
+
+  script/server -e disconnected
+  
+==== 4: login as 'jimbob' or 'sueann'
+
+Passwords are ignored.
+  

data/Rakefile

@@ -0,0 +1,78 @@
+desc "Default: run all tests, including features"
+task :default => [ 'test', 'features' ] 
+
+# PACKAGING
+
+require 'rake/gempackagetask'
+
+spec = eval File.read('casrack_the_authenticator.gemspec')
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+namespace :pkg do
+  
+  pkg_dir = './pkg'
+  
+  desc "clean the pkg/ director"
+  task :clean do
+    rm_r pkg_dir if File.exists?(pkg_dir)
+  end
+  
+end
+
+# DOCUMENTATION
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+desc "Generate RDoc"
+task :doc => ['doc:generate']
+
+namespace :doc do
+  
+  doc_dir = './doc/rdoc'
+  
+  YARD::Rake::YardocTask.new(:generate) do |yt|
+    yt.files   = ['lib/**/*.rb', 'README.rdoc']
+    yt.options = ['--output-dir', doc_dir, '--readme', 'README.rdoc']
+  end
+  
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_dir if File.exists?(doc_dir)
+  end
+  
+end
+
+# TESTING
+
+require 'cucumber'
+require 'cucumber/rake/task'
+require 'rake/testtask'
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "features --format pretty"
+end
+
+PROJECT_ROOT = File.expand_path(File.dirname(__FILE__))
+
+LIB_DIRECTORIES = FileList.new do |fl|
+  fl.include "#{PROJECT_ROOT}/lib"
+  fl.include "#{PROJECT_ROOT}/test/lib"
+end
+ 
+TEST_FILES = FileList.new do |fl|
+  fl.include "#{PROJECT_ROOT}/test/**/*_test.rb"
+  fl.exclude "#{PROJECT_ROOT}/test/test_helper.rb"
+  fl.exclude "#{PROJECT_ROOT}/test/lib/**/*.rb"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs = LIB_DIRECTORIES
+  t.test_files = TEST_FILES
+  t.verbose = true
+end

data/features/fake.feature

@@ -0,0 +1,34 @@
+Feature: Fake CAS Authentication
+  In order to support developers who work away from the office
+  Casrack the Authenticator provides a Fake middleware.
+  
+  Background:
+    Given a Rack application exists
+    And the fake Casrack middleware is installed with user "missy"
+    
+  Scenario: not-signed-in user makes a request to a public area
+    Given the underlying Rack application returns [200, {}, "Public Information"]
+    When I make a request
+    Then the response should be successful
+    And the response body should include "Public Information"
+    And the CAS user should be nil
+    
+  Scenario: not-signed-in user makes a request to a private area
+    Given the underlying Rack application returns [401, {}, 'Restricted. Go away.']
+    When I make a request
+    Then I should be presented with a HTTP Basic authentication request
+    And the CAS user should be nil
+  
+  Scenario: user presenting invalid credentials makes a request to a private area
+    Given the underlying Rack application returns [401, {}, 'Restricted. Go away.']
+    When I make a request as "thomas"
+    Then I should be presented with a HTTP Basic authentication request
+    And the CAS user should be nil
+    
+  Scenario: user presenting credentials makes a request to a private area
+    Given the underlying Rack application returns [200, {}, 'Restricted. Shh.']
+    When I make a request as "missy"
+    Then the response should be successful
+    And the response body should include "Restricted. Shh."
+    And the CAS user should be "missy"
+    

data/features/require_cas.feature

@@ -0,0 +1,19 @@
+Feature: Required CAS Authentication
+  In order make it dead-simple for users to implement a CAS-login requirement
+  Casrack the Authenticator provides a RequireCAS middleware.
+  
+  Background:
+    Given a Rack application exists
+    And the RequireCAS middleware is installed
+    And the simple version of Casrack the Authenticator is installed
+    And the underlying Rack application returns [200, {}, "Public Information"]
+    
+  Scenario: not-signed-in user makes a request
+    When I make a request
+    Then I should be redirected to CAS
+    And the "Content-Type" header should be "text/plain"
+    
+  Scenario: signed-in-user makes a request
+    When I return to "http://myapp.org/bar" with a valid CAS ticket for "tperon"
+    Then the response should be successful
+    And the response body should include "Public Information"

data/features/simple.feature

@@ -0,0 +1,32 @@
+Feature: Simple CAS Authentication
+  In order to maintain privacy and accountability while keeping IT costs low
+  "Upper Management" wants to use CAS authentication
+  
+  Background:
+    Given a Rack application exists
+    And the simple version of Casrack the Authenticator is installed
+  
+  Scenario: not-signed-in user accesses public material
+    Given the underlying Rack application returns [200, {}, "Public Information"]
+    When I make a request
+    Then the response should be successful
+    And the response body should include "Public Information"
+    
+  Scenario: not-signed-in user accesses restricted material
+    Given the underlying Rack application returns [401, {}, "Restricted!"]
+    When I make a request to "http://myapp.com/foo?bar=baz"
+    Then I should be redirected to CAS
+    And the "Content-Type" header should be "text/plain"
+    And CAS should return me to "http://myapp.com/foo?bar=baz"
+    
+  Scenario: returning from a successful CAS sign-in
+    Given the underlying Rack application returns [200, {}, "Information for jswanson"]
+    When I return to "http://myapp.org/bar" with a valid CAS ticket for "jswanson"
+    Then the CAS user should be "jswanson"
+    And the response should be successful
+    And the response body should include "Information for jswanson"
+    
+  Scenario: returning from an unsuccessful CAS sign-in
+    Given the underlying Rack application returns [401, {}, "Restricted!"]
+    When I return to "http://myapp.org/bar" with an invalid CAS ticket
+    Then the CAS user should be nil

data/features/step_definitions/fake_cas_steps.rb

@@ -0,0 +1,14 @@
+Given /^the fake Casrack middleware is installed with user "([^\"]*)"$/ do |user|
+  self.app = CasrackTheAuthenticator::Fake.new(app, user)
+end
+
+Then /^I should be presented with a HTTP Basic authentication request$/ do
+  assert_equal 401, response.status
+  assert_equal 'text/plain', response.headers['Content-Type']
+  assert_equal '0', response.headers['Content-Length']
+  assert_equal 'Basic realm="CasrackTheAuthenticator::Fake"', response.headers['WWW-Authenticate']
+end
+
+When /^I make a request as "([^\"]*)"$/ do |username|
+  get '/', { 'HTTP_AUTHORIZATION' => 'Basic ' + ["#{username}:sekret"].pack("m*") }
+end

data/features/step_definitions/rack_steps.rb

@@ -0,0 +1,69 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'test', 'test_helper.rb')
+require 'rack/mock'
+
+Given /^a Rack application exists$/ do
+  self.underlying_app = lambda { |env| nil }
+  self.app = underlying_app
+end
+
+Given /^the simple version of Casrack the Authenticator is installed$/ do
+  self.app = CasrackTheAuthenticator::Simple.new(app, :cas_server => 'http://cas.test/cas')
+end
+
+Given /^the RequireCAS middleware is installed$/ do
+  self.app = CasrackTheAuthenticator::RequireCAS.new(app)
+end
+
+Given /^the underlying Rack application returns (.+)$/ do |response|
+  underlying_app.stubs(:call).returns(eval(response))
+end
+
+When /^I make a request$/ do
+  get '/'
+end
+
+When /^I make a request to "([^\"]*)"$/ do |url|
+  get url
+end
+
+When /^I return to "([^\"]*)" with a valid CAS ticket for "([^\"]*)"$/ do |url, user|
+  http_request_returns_valid_cas_user user
+  url << (url.include?('?') ? '&' : '?') << 'ticket=ST-123455'
+  When "I make a request to \"#{url}\""
+end
+
+When /^I return to "([^\"]*)" with an invalid CAS ticket$/ do |url|
+  http_request_returns_error
+  url << (url.include?('?') ? '&' : '?') << 'ticket=ST-not-a-valid-ticket'
+  When "I make a request to \"#{url}\""
+end
+
+Then /^the CAS user should be nil$/ do
+  assert_equal nil, session[:cas_user]
+end
+
+Then /^the CAS user should be "([^\"]*)"$/ do |username|
+  assert_equal username, session[:cas_user]
+end
+
+Then /^the response should be successful$/ do
+  assert((200..299).include?(response.status), "Expected success, but was #{response.status}")
+end
+
+Then /^the response body should include "([^\"]*)"$/ do |text|
+  assert response.body.include?(text)
+end
+
+Then /^I should be redirected to CAS$/ do
+  assert((300..399).include?(response.status), "Expected redirect, but was #{response.status}")
+  assert !redirected_to.nil?
+  assert redirected_to.to_s =~ /cas/i
+end
+
+Then /^CAS should return me to "([^\"]*)"$/ do |return_to|
+  assert_equal return_to, service_url
+end
+
+Then /^the "([^\"]*)" header should be "([^\"]*)"$/ do |header, value|
+  assert_equal value, response.headers[header]
+end

data/features/support/assertions.rb

@@ -0,0 +1,3 @@
+require 'test/unit/assertions'
+
+World(Test::Unit::Assertions)

data/features/support/rack_support.rb

@@ -0,0 +1,89 @@
+require 'rack'
+require 'rack/mock'
+Rack::MockRequest.class_eval do
+  
+  class <<self
+    def env_for_with_hook(*args)
+      return ::RackSupport.current_env unless ::RackSupport.current_env.nil?
+      env = env_for_without_hook(*args)
+      ::RackSupport.current_env = env
+      env
+    end
+    alias_method :env_for_without_hook, :env_for
+    alias_method :env_for, :env_for_with_hook
+  end
+  
+end
+
+module RackSupport
+  
+  VALID_CAS_USER_XML = <<-EOX
+<cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
+  <cas:authenticationSuccess>
+    <cas:user>%s</cas:user>
+  </cas:authenticationSuccess>
+</cas:serviceResponse>
+EOX
+  
+  @@current_env = nil
+  
+  def self.current_env
+    @@current_env
+  end
+  
+  def self.current_env=(env)
+    @@current_env = env
+  end
+  
+  attr_accessor :underlying_app, :app, :response, :session
+  
+  def cleanup_rack_variables
+    ::RackSupport.current_env = nil
+    self.underlying_app = self.app = self.session = self.response = nil
+  end
+  
+  def get(url, headers = {})
+    env = RackSupport.current_env = Rack::MockRequest.env_for(url, headers)
+    if session
+      env['rack.session'] = session
+    else
+      self.session = Rack::Request.new(env).session
+    end
+    self.response = Rack::MockRequest.new(app).get url, headers
+  end
+  
+  def redirected_to
+    return nil if response.headers['Location'].nil?
+    URI::parse(response.headers['Location'])
+  end
+  
+  def service_url
+    return nil if redirected_to.nil?
+    Rack::Utils.parse_nested_query(redirected_to.query)['service']
+  end
+  
+  def http_request_returns_valid_cas_user(username)
+    http_request_returns VALID_CAS_USER_XML % username
+  end
+  
+  def http_request_returns_error
+    http_request_returns "this is not a valid CAS service-ticket-validation response!"
+  end
+  
+  def http_request_returns(content)
+    server = Object.new
+    connection = Object.new
+    response = Object.new
+    Net::HTTP.stubs(:new).returns(server)
+    server.stubs(:start).yields(connection)
+    connection.stubs(:get).returns(response)
+    response.stubs(:body).returns(content)
+  end
+  
+end
+
+After do
+  cleanup_rack_variables
+end
+
+World(RackSupport)

data/lib/casrack_the_authenticator.rb

@@ -0,0 +1,11 @@
+module CasrackTheAuthenticator
+  
+  USERNAME_PARAM = :cas_user
+  
+  autoload :Simple, 'casrack_the_authenticator/simple'
+  autoload :Configuration, 'casrack_the_authenticator/configuration'
+  autoload :ServiceTicketValidator, 'casrack_the_authenticator/service_ticket_validator'
+  autoload :RequireCAS, 'casrack_the_authenticator/require_cas'
+  autoload :Fake, 'casrack_the_authenticator/fake'
+  
+end

data/lib/casrack_the_authenticator/configuration.rb

@@ -0,0 +1,88 @@
+require 'uri'
+require 'rack'
+require 'rack/utils'
+
+module CasrackTheAuthenticator
+  
+  class Configuration
+    
+    DEFAULT_LOGIN_URL = "%s/login"
+    
+    DEFAULT_SERVICE_VALIDATE_URL = "%s/serviceValidate"
+    
+    # @param [Hash] params configuration options
+    # @option params [String, nil] :cas_server the CAS server root URL; probably something like
+    #         'http://cas.mycompany.com' or 'http://cas.mycompany.com/cas'; optional.
+    # @option params [String, nil] :cas_login_url (:cas_server + '/login') the URL to which to
+    #         redirect for logins; options if <tt>:cas_server</tt> is specified,
+    #         required otherwise.
+    # @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
+    #         URL to use for validating service tickets; optional if <tt>:cas_server</tt> is
+    #         specified, requred otherwise.
+    def initialize(params)
+      parse_params params
+    end
+    
+    # Build a CAS login URL from +service+.
+    #
+    # @param [String] service the service (a.k.a. return-to) URL
+    # 
+    # @return [String] a URL like
+    # "http://cas.mycompany.com/login?service=..."
+    def login_url(service)
+      append_service @login_url, service
+    end
+    
+    # Build a service-validation URL from +service+ and +ticket+.
+    #
+    # @param [String] service the service (a.k.a. return-to) URL
+    # @param [String] ticket the ticket to validate
+    #
+    # @return [String] a URL like
+    # "http://cas.mycompany.com/serviceValidate?service=...&ticket=..."
+    def service_validate_url(service, ticket)
+      url = append_service @service_validate_url, service
+      url << '&ticket=' << Rack::Utils.escape(ticket)
+    end
+    
+    private
+    
+    def parse_params(params)
+      if params[:cas_server].nil? && params[:cas_login_url].nil?
+        raise ArgumentError.new(":cas_server or :cas_login_url MUST be provided")
+      end
+      @login_url   = params[:cas_login_url]
+      @login_url ||= DEFAULT_LOGIN_URL % params[:cas_server]
+      validate_is_url 'login URL', @login_url
+      
+      if params[:cas_server].nil? && params[:cas_service_validate_url].nil?
+        raise ArgumentError.new(":cas_server or :cas_service_validate_url MUST be provided")
+      end
+      @service_validate_url   = params[:cas_service_validate_url]
+      @service_validate_url ||= DEFAULT_SERVICE_VALIDATE_URL % params[:cas_server]
+      validate_is_url 'service-validate URL', @service_validate_url
+    end
+    
+    IS_NOT_URL_ERROR_MESSAGE = "%s is not a valid URL"
+    
+    def validate_is_url(name, possibly_a_url)
+      url = URI.parse(possibly_a_url) rescue nil
+      raise ArgumentError.new(IS_NOT_URL_ERROR_MESSAGE % name) unless url.kind_of?(URI::HTTP)
+    end
+    
+    # Adds +service+ as an URL-escaped parameter to +base+.
+    #
+    # @param [String] base the base URL
+    # @param [String] service the service (a.k.a. return-to) URL.
+    #
+    # @return [String] the new joined URL.
+    def append_service(base, service)
+      result = base.dup
+      result << (result.include?('?') ? '&' : '?')
+      result << 'service='
+      result << Rack::Utils.escape(service)
+    end
+    
+  end
+  
+end

data/lib/casrack_the_authenticator/fake.rb

@@ -0,0 +1,49 @@
+require 'rack'
+require 'rack/auth/basic'
+
+module CasrackTheAuthenticator
+  
+  # A fake CAS authenticator.  Good for disconnected-mode
+  # development.
+  class Fake
+    
+    BASIC_AUTH_401 = [
+      401,
+      {
+        'Content-Type' => 'text/plain',
+        'Content-Length' => '0',
+        'WWW-Authenticate' => 'Basic realm="CasrackTheAuthenticator::Fake"'
+      },
+      []
+    ]
+    
+    # @param app the underlying Rack application
+    # @param [Array<String>] usernames an Array of usernames that
+    #        will successfully authenticate as though they
+    #        had come from CAS.
+    def initialize(app, *usernames)
+      @app, @usernames = app, usernames
+      raise "Why would you create a Fake CAS authenticator but not let anyone use it?" if usernames.empty?
+    end
+    
+    def call(env)
+      process_basic_auth(env)
+      basic_auth_on_401(@app.call(env))
+    end
+    
+    private
+    
+    def process_basic_auth(env)
+      auth = Rack::Auth::Basic::Request.new(env)
+      if auth.provided? && auth.basic? && @usernames.include?(auth.username)
+        Rack::Request.new(env).session[CasrackTheAuthenticator::USERNAME_PARAM] = auth.username
+      end
+    end
+    
+    def basic_auth_on_401(response)
+      response[0] == 401 ? BASIC_AUTH_401 : response
+    end
+    
+  end
+  
+end

data/lib/casrack_the_authenticator/require_cas.rb

@@ -0,0 +1,36 @@
+module CasrackTheAuthenticator
+  
+  class RequireCAS
+    
+    # Create a new RequireCAS middleware, which requires
+    # users to log in via CAS for _all_ requests, and
+    # returns a 401 Unauthorized if they aren't signed in.
+    #
+    # @param app the underlying Rack app.
+    def initialize(app)
+      @app = app
+    end
+    
+    def call(env)
+      if signed_in?(env)
+        @app.call(env)
+      else
+        unauthorized
+      end
+    end
+    
+    private
+    
+    # @return [true, false] whether the user is signed in via CAS.
+    def signed_in?(env)
+      !Rack::Request.new(env).session[CasrackTheAuthenticator::USERNAME_PARAM].nil?
+    end
+    
+    # @return [Array<Integer, Hash, String>] a 401 Unauthorized Rack response.
+    def unauthorized
+      [401, {}, "CAS Authentication is required"]
+    end
+    
+  end
+  
+end

data/lib/casrack_the_authenticator/service_ticket_validator.rb

@@ -0,0 +1,55 @@
+require 'nokogiri'
+
+module CasrackTheAuthenticator
+  
+  class ServiceTicketValidator
+    
+    VALIDATION_REQUEST_HEADERS = { 'Accept' => '*/*' }
+    
+    # Build a validator from a +configuration+, a
+    # +return_to+ URL, and a +ticket+.
+    #
+    # @param [CasrackTheAuthenticator::Configuration] configuration the CAS configuration
+    # @param [String] return_to_url the URL of this CAS client service
+    # @param [String] ticket the service ticket to validate
+    def initialize(configuration, return_to_url, ticket)
+      @uri = URI.parse(configuration.service_validate_url(return_to_url, ticket))
+    end
+    
+    # Request validation of the ticket from the CAS server's
+    # serviceValidate (CAS 2.0) function.
+    #
+    # Swallows all XML parsing errors (and returns +nil+ in those cases).
+    #
+    # @return [String, nil] a username if the response is valid; +nil+ otherwise.
+    #
+    # @raise any connection errors encountered.
+    def user
+      parse_user(get_validation_response_body)
+    end
+    
+    private
+    
+    def get_validation_response_body
+      result = ''
+      Net::HTTP.new(@uri.host, @uri.port).start do |c|
+        response = c.get "#{@uri.path}?#{@uri.query}", VALIDATION_REQUEST_HEADERS
+        result = response.body
+      end
+      result
+    end
+    
+    def parse_user(body)
+      begin
+        doc = Nokogiri::XML(body)
+        node   = doc.xpath('/cas:serviceResponse/cas:authenticationSuccess/cas:user').first
+        node ||= doc.xpath('/serviceResponse/authenticationSuccess/user').first  # try w/o the namespace just in case
+        node.nil? ? nil : node.content
+      rescue Nokogiri::XML::XPath::SyntaxError
+        nil
+      end
+    end
+    
+  end
+  
+end

data/lib/casrack_the_authenticator/simple.rb

@@ -0,0 +1,82 @@
+require 'rack'
+require 'rack/request'
+
+module CasrackTheAuthenticator
+  
+  # The most basic CAS client use-case: redirects to CAS
+  # if a middleware or endpoint beneath this one returns
+  # a 401 response. On successful redirection back from 
+  # CAS, puts the username of the CAS user in the session
+  # under <tt>:cas_user</tt>.
+  class Simple
+    
+    # Create a new CAS middleware.
+    # 
+    # @param app the underlying Rack application
+    # @param [Hash] options - see
+    #               CasrackTheAuthenticator::Configuration
+    #               for more information
+    def initialize(app, options)
+      @app = app
+      @configuration = CasrackTheAuthenticator::Configuration.new(options)
+    end
+    
+    # Processes the CAS user if a "ticket" parameter is passed,
+    # then calls the underlying Rack application; if the result
+    # is a 401, redirects to CAS; otherwise, returns the response
+    # unchanged.
+    #
+    # @return [Array<Integer, Hash, #each>] a Rack response
+    def call(env)
+      request = Rack::Request.new(env)
+      process_return_from_cas(request)
+      redirect_on_401(request, @app.call(env))
+    end
+    
+    private
+    
+    # ticket processing
+    
+      def process_return_from_cas(request)
+        ticket = request.params['ticket']
+        if ticket
+          validator = ServiceTicketValidator.new(@configuration, service_url(request), ticket)
+          request.session[CasrackTheAuthenticator::USERNAME_PARAM] = validator.user
+        end
+      end
+    
+    # redirection
+    
+      def redirect_on_401(request, response)
+        if response[0] == 401
+          redirect_to_cas(request)
+        else
+          response
+        end
+      end
+    
+      def redirect_to_cas(request)
+        service_url = service_url(request)
+        [ 
+          302,
+          {
+            'Location' => @configuration.login_url(service_url),
+            'Content-Type' => 'text/plain'
+          },
+          ["You are being redirected to CAS for sign-in."]
+        ]
+      end
+    
+    # utils  
+    
+      def service_url(request)
+        strip_ticket_param request.url
+      end
+    
+      def strip_ticket_param(url)
+        url.sub(/[\?&]ticket=[^\?&]+/, '')
+      end
+    
+  end
+  
+end

data/test/configuration_test.rb

@@ -0,0 +1,83 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class ConfigurationTest < Test::Unit::TestCase
+  
+  def new_config
+    CasrackTheAuthenticator::Configuration.new @valid_params
+  end
+  
+  context 'a Casrack configuration' do
+    
+    setup do
+      @valid_params = {
+        :cas_login_url => 'http://cas.example.org/login',
+        :cas_service_validate_url => 'http://cas.example.org/service-validate',
+        :cas_server => 'http://cas.example.org'
+      }
+    end
+    
+    should 'be invalid with neither a :cas_server nor a :cas_login_url' do
+      assert_raises(ArgumentError) do
+        @valid_params[:cas_server] = @valid_params[:cas_login_url] = nil
+        new_config
+      end
+    end
+    
+    should 'be invalid with neither a :cas_server nor a :cas_service_validate_url' do
+      assert_raises(ArgumentError) do
+        @valid_params[:cas_server] = @valid_params[:cas_service_validate_url] = nil
+        new_config
+      end
+    end
+    
+    should "be invalid with a :cas_login_url that isn't really a URL" do
+      assert_raises(ArgumentError) do
+        @valid_params[:cas_login_url] = 'not a URL'
+        new_config
+      end
+    end
+    
+    should "be invalid with a :cas_service_validate_url that isn't really a URL" do
+      assert_raises(ArgumentError) do
+        @valid_params[:cas_service_validate_url] = 'not a URL'
+        new_config
+      end
+    end
+    
+    should 'use the login URL if given' do
+      base = @valid_params[:cas_login_url]
+      service = 'http://example.org'
+      assert_equal base + '?service=http%3A%2F%2Fexample.org', new_config.login_url(service)
+    end
+    
+    should 'use the service-validate URL if given' do
+      base = @valid_params[:cas_service_validate_url]
+      service = 'http://example.org'
+      ticket = 'ST-00192'
+      svurl = URI.parse new_config.service_validate_url(service, ticket)
+      assert svurl.to_s =~ /^#{base}/
+      assert_equal service, Rack::Utils.parse_query(svurl.query)['service']
+      assert_equal ticket, Rack::Utils.parse_query(svurl.query)['ticket']
+    end
+    
+    should 'provide a default login URL if none is given' do
+      @valid_params[:cas_login_url] = nil
+      base = 'http://cas.example.org/login'
+      service = 'http://example.org'
+      assert_equal base + '?service=http%3A%2F%2Fexample.org', new_config.login_url(service)
+    end
+    
+    should 'provide a default service-validate URL if none is given' do
+      @valid_params[:cas_service_validate_url] = nil
+      base = 'http://cas.example.org/serviceValidate'
+      service = 'http://example.org'
+      ticket = 'ST-373737'
+      svurl = URI.parse new_config.service_validate_url(service, ticket)
+      assert svurl.to_s =~ /^#{base}/
+      assert_equal service, Rack::Utils.parse_query(svurl.query)['service']
+      assert_equal ticket, Rack::Utils.parse_query(svurl.query)['ticket']
+    end
+    
+  end
+
+end

data/test/fake_test.rb

@@ -0,0 +1,94 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class FakeTest < Test::Unit::TestCase
+  
+  def self.should_let_the_response_bubble_up_unaltered
+    should 'let the response bubble up unaltered' do
+      assert_equal @app_response, @response
+    end
+  end
+  
+  def self.should_set_the_cas_user_to(user)
+    should "set the CAS user to #{user || '<nil>'}" do
+      assert_received(@app, :call) do |expects|
+        expects.with() do |env|
+          assert_equal user, Rack::Request.new(env).session[:cas_user]
+          true
+        end
+      end
+    end
+  end
+  
+  def self.should_prompt_http_basic_authentication
+    should 'prompt HTTP basic authentication' do
+      assert_equal 401, @response[0]
+      assert_equal 'Basic realm="CasrackTheAuthenticator::Fake"', @response[1]['WWW-Authenticate']
+    end
+  end
+  
+  def auth_headers(user)
+    { 'HTTP_AUTHORIZATION' => 'Basic '+ ["#{user}:passw0rd"].pack("m*") }
+  end
+  
+  context 'the Fake authenticator' do
+    
+    setup do
+      @app = Object.new
+      @fake = CasrackTheAuthenticator::Fake.new @app, 'jlevitt'
+    end
+    
+    context 'when receiving a non-401 response' do
+      
+      setup do
+        @app_response = [ 320, {}, ["Weird redirection"] ]
+        @app.stubs(:call).returns @app_response
+        @response = @fake.call({})
+      end
+      
+      should_let_the_response_bubble_up_unaltered
+      
+    end
+    
+    context 'when receiving a 401 from below' do
+      
+      setup do
+        @app_response = [ 401, {}, 'Unauthorized!' ]
+        @app.stubs(:call).returns @app_response
+        @response = @fake.call({})
+      end
+      
+      should_prompt_http_basic_authentication
+      
+    end
+    
+    context 'when getting a valid HTTP Basic user in the request' do
+      
+      setup do
+        @app_response = [ 210, {}, ["Success-ish"] ]
+        @app.stubs(:call).returns @app_response
+        @response = @fake.call(auth_headers('jlevitt'))
+      end
+      
+      should_let_the_response_bubble_up_unaltered
+      
+      should_set_the_cas_user_to 'jlevitt'
+      
+    end
+    
+    context 'when getting an invalid HTTP Basic user in the request' do
+      
+      setup do
+        @app_response = [ 401, {}, [] ]
+        @app.stubs(:call).returns @app_response
+        @response = @fake.call(auth_headers('zdeschanel'))
+      end
+      
+      should_prompt_http_basic_authentication
+      
+      should_set_the_cas_user_to nil
+      
+    end
+    
+  end
+  
+end

data/test/service_ticket_validator_test.rb

@@ -0,0 +1,84 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class ServiceTicketValidatorTest < Test::Unit::TestCase
+  
+  context 'a service-ticket validator' do
+    
+    setup do
+      config = Object.new
+      config.stubs(:service_validate_url).returns('http://cas.example.org/cas/serviceValidate?service=foo&ticket=bar')
+      @validator = CasrackTheAuthenticator::ServiceTicketValidator.new(config, nil, nil)
+    end
+    
+    context 'validating a ticket' do
+      
+      setup do
+        @server = Object.new
+        @connection = Object.new
+        @response = Object.new
+        @body = Object.new
+        Net::HTTP.stubs(:new).returns(@server)
+        @server.stubs(:start).yields(@connection)
+        @connection.stubs(:get).returns(@response)
+        @response.stubs(:body).returns(@body)
+      end
+      
+      should 'return the body from the service-validate URL' do
+        assert_equal @body, @validator.send(:get_validation_response_body)
+        assert_received(Net::HTTP, :new) do |expects|
+          expects.with('cas.example.org', 80)
+        end
+        assert_received(@server, :start)
+        assert_received(@connection, :get) do |expects|
+          expects.with('/cas/serviceValidate?service=foo&ticket=bar', { 'Accept' => '*/*' })
+        end
+        assert_received(@response, :body)
+      end
+      
+      context "but a connection error gets in the way" do
+        
+        setup do
+          @server.stubs(:start).raises(SocketError)
+        end
+      
+        should 'let the error percolate' do
+          assert_raises(SocketError) do
+            @validator.send(:get_validation_response_body)
+          end
+        end
+        
+      end
+      
+    end
+    
+    context 'parsing a successful response' do
+      
+      setup do
+        @body = <<-EOX
+<cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
+  <cas:authenticationSuccess>
+    <cas:user>beatrice</cas:user>
+  </cas:authenticationSuccess>
+</cas:serviceResponse>
+EOX
+      end
+      
+      should 'get the user' do
+        assert_equal 'beatrice', @validator.send(:parse_user, @body)
+      end
+    
+    end
+    
+    context 'parsing an unsuccessful response' do
+      setup do
+        @body = ''
+      end
+      
+      should 'return nil' do
+        assert_equal nil, @validator.send(:parse_user, @body)
+      end
+    end
+    
+  end
+  
+end

data/test/simple_test.rb

@@ -0,0 +1,131 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class SimpleTest < Test::Unit::TestCase
+  
+  context 'creating a Simple authenticator' do
+    should 'require a :cas_server' do
+      assert_raises(ArgumentError) do
+        CasrackTheAuthenticator::Simple.new(:anything, {})
+      end
+    end
+  end
+  
+  def self.should_pass_the_request_on_down
+    should "pass the request to the underyling app" do
+      assert_received(@app, :call)
+    end
+  end
+  
+  def self.should_set_the_cas_user_in_the_session_to(username)
+    should "set the CAS user in the session to #{username || '<nil>'}" do
+      assert_equal username, @session[:cas_user]
+    end
+  end
+  
+  def get(url)
+    env = Rack::MockRequest.env_for(url)
+    if @session
+      env['rack.session'] = @session
+    else
+      @session = Rack::Request.new(env).session
+    end
+    Rack::MockRequest.stubs(:env_for).returns(env)
+    @response = @request.get url
+  end
+  
+  def param_from_url(param, url)
+    uri = URI.parse(url)
+    Rack::Utils.parse_nested_query(uri.query)[param]
+  end
+  
+  def return_to_url(response)
+    param_from_url 'service', response.headers['Location']
+  end
+  
+  context 'a Simple authenticator' do
+    
+    setup do
+      @app = Object.new
+      @authenticator = CasrackTheAuthenticator::Simple.new(@app, {:cas_server => 'http://cas.test/'})
+      @request = Rack::MockRequest.new(@authenticator)
+    end
+    
+    context 'when receiving a 200 from below' do
+      
+      setup do
+        @response_from_below = [ 200, {}, 'Success!' ]
+        @app.stubs(:call).returns(@response_from_below)
+        get '/'
+      end
+      
+      should_pass_the_request_on_down
+
+      should 'do nothing to the response' do
+        assert_equal @response_from_below[0], @response.status
+        assert_equal @response_from_below[2], @response.body
+      end
+      
+    end
+    
+    context 'when receiving a 401 from below' do
+      
+      setup do
+        response = [401, {}, 'Unauthorized!']
+        @app.stubs(:call).returns(response)
+        @url = "http://foo.bar/baz?yoo=hoo"
+        get @url
+      end
+      
+      should_pass_the_request_on_down
+      
+      should 'redirect to CAS' do
+        assert((300..399).include?(@response.status))
+        assert @response.headers['Location'] =~ /cas/i
+      end
+      
+      should 'set the content-type to text/plain' do
+        assert_equal 'text/plain', @response.headers['Content-Type']
+      end
+      
+      should 'use the requested URL for the return-to' do
+        assert_equal @url, return_to_url(@response)
+      end
+      
+      context "and the request URL includes a 'ticket' param" do
+        
+        setup do
+          @url = "http://foo.bar/baz?ticket=12345"
+          get @url
+        end
+        
+        should 'strip the ticket from the return-to URL' do
+          return_to = return_to_url(@response)
+          assert_equal nil, param_from_url('ticket', return_to)
+        end
+        
+      end
+      
+    end
+    
+    context 'when receiving a valid result from CAS' do
+      
+      setup do
+        validator = Object.new
+        validator.stubs(:user).returns 'timmy'
+        CasrackTheAuthenticator::ServiceTicketValidator.stubs(:new).returns(validator)
+        @response_from_below = [ 200, {}, 'Success!' ]
+        @app.stubs(:call).returns(@response_from_below)
+        get '/?ticket=ST-77889'
+      end
+      
+      should_set_the_cas_user_in_the_session_to 'timmy'
+      
+      should 'build a service-ticket validator' do
+        assert_received(CasrackTheAuthenticator::ServiceTicketValidator, :new)
+      end
+      
+    end
+    
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,16 @@
+require 'test/unit'
+require 'test/unit/testcase'
+require 'rubygems'
+require 'shoulda'
+gem 'jferris-mocha'
+require 'mocha'
+require 'redgreen'
+
+I_KNOW_I_AM_USING_AN_OLD_AND_BUGGY_VERSION_OF_LIBXML2 = 1
+
+lib_path = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$: << lib_path unless $:.include?(lib_path)
+
+require 'casrack_the_authenticator'
+require 'rack'
+require 'rack/mock'

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: casrack_the_authenticator
+version: !ruby/object:Gem::Version 
+  version: 1.4.0
+platform: ruby
+authors: 
+- James Rosen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-05 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: CAS Authentication via Rack Middleware
+email: james.a.rosen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/casrack_the_authenticator/configuration.rb
+- lib/casrack_the_authenticator/fake.rb
+- lib/casrack_the_authenticator/require_cas.rb
+- lib/casrack_the_authenticator/service_ticket_validator.rb
+- lib/casrack_the_authenticator/simple.rb
+- lib/casrack_the_authenticator.rb
+- test/configuration_test.rb
+- test/fake_test.rb
+- test/service_ticket_validator_test.rb
+- test/simple_test.rb
+- test/test_helper.rb
+- features/fake.feature
+- features/require_cas.feature
+- features/simple.feature
+- features/step_definitions/fake_cas_steps.rb
+- features/step_definitions/rack_steps.rb
+- features/support/assertions.rb
+- features/support/rack_support.rb
+- README.rdoc
+- Rakefile
+has_rdoc: true
+homepage: http://github.com/gcnovus/casrack_the_authenticator
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- "Casrack the Authenticator: RDoc"
+- --charset
+- utf-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.3
+signing_key: 
+specification_version: 3
+summary: CAS Authentication via Rack Middleware
+test_files: []
+