factorylabs-casrack_the_authenticator 1.6.0

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/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/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