rubycas-client 2.0.1 → 2.1.0

data/examples/merb/merb_auth_cas.rb

@@ -0,0 +1,67 @@
+# run very flat apps with merb -I <app file>.
+
+# Uncomment for DataMapper ORM
+# use_orm :datamapper
+
+# Uncomment for ActiveRecord ORM
+# use_orm :activerecord
+
+# Uncomment for Sequel ORM
+# use_orm :sequel
+
+$:.unshift(File.dirname(__FILE__) / ".." / ".." / "lib")
+require "casclient"
+require 'casclient/frameworks/merb/filter'
+#
+# ==== Pick what you test with
+#
+
+# This defines which test framework the generators will use.
+# RSpec is turned on by default.
+#
+# To use Test::Unit, you need to install the merb_test_unit gem.
+# To use RSpec, you don't have to install any additional gems, since
+# merb-core provides support for RSpec.
+#
+# use_test :test_unit
+use_test :rspec
+
+#
+# ==== Choose which template engine to use by default
+#
+
+# Merb can generate views for different template engines, choose your favourite as the default.
+
+use_template_engine :erb
+# use_template_engine :haml
+
+Merb::Config.use { |c|
+  c[:framework]           = { :public => [Merb.root / "public", nil] }
+  c[:session_store]       = 'cookie'
+  c[:exception_details]   = true
+  c[:log_level]           = :debug # or error, warn, info or fatal
+  c[:log_stream]          = STDOUT
+  c[:session_secret_key]  = '9f30c015f2132d217bfb81e31668a74fadbdf672'
+  c[:log_file]            = Merb.root / "log" / "merb.log"
+
+  c[:reload_classes]   = true
+  c[:reload_templates] = true
+}
+
+
+Merb::Plugins.config[:"rubycas-client"] = {
+  :cas_base_url => "http://localhost:7777"
+}
+
+Merb::Router.prepare do
+  match('/').to(:controller => 'merb_auth_cas', :action =>'index').name(:default)
+end
+
+class MerbAuthCas < Merb::Controller
+  include CASClient::Frameworks::Merb::Filter
+  before :cas_filter
+
+  def index
+    "Hi, #{session[:cas_user]}"
+  end
+end

data/examples/merb/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require "rubygems"
+
+# Add the local gems dir if found within the app root; any dependencies loaded
+# hereafter will try to load from the local gems before loading system gems.
+if (local_gem_dir = File.join(File.dirname(__FILE__), '..', 'gems')) && $BUNDLE.nil?
+  $BUNDLE = true; Gem.clear_paths; Gem.path.unshift(local_gem_dir)
+end
+
+require "spec"
+require "merb-core"
+
+Merb::Config.use do |c|
+  c[:session_store] = "memory"
+end
+
+Merb.start_environment(:testing => true,
+                       :adapter => 'runner',
+                       :environment => ENV['MERB_ENV'] || 'test')
+
+Spec::Runner.configure do |config|
+  config.include(Merb::Test::ViewHelper)
+  config.include(Merb::Test::RouteHelper)
+  config.include(Merb::Test::ControllerHelper)
+end

data/lib/casclient/client.rb

@@ -11,6 +11,8 @@ module CASClient
     end
     
     def configure(conf)
+      #TODO: raise error if conf contains unrecognized cas options (this would help detect user typos in the config)
+
       raise ArgumentError, "Missing :cas_base_url parameter!" unless conf[:cas_base_url]
       
       @cas_base_url      = conf[:cas_base_url].gsub(/\/$/, '')       
@@ -43,20 +45,31 @@ module CASClient
     # If a logout_url has not been explicitly configured,
     # the default is cas_base_url + "/logout".
     #
-    # service_url:: Set this if you want the user to be
-    #               able to immediately log back in. Generally
-    #               you'll want to use something like <tt>request.referer</tt>.
-    #               Note that this only works with RubyCAS-Server.
-    # back_url:: This satisfies section 2.3.1 of the CAS protocol spec.
-    #            See http://www.ja-sig.org/products/cas/overview/protocol
-    def logout_url(service_url = nil, back_url = nil)
+    # destination_url:: Set this if you want the user to be
+    #                   able to immediately log back in. Generally
+    #                   you'll want to use something like <tt>request.referer</tt>.
+    #                   Note that the above behaviour describes RubyCAS-Server 
+    #                   -- other CAS server implementations might use this
+    #                   parameter differently (or not at all).
+    # follow_url:: This satisfies section 2.3.1 of the CAS protocol spec.
+    #              See http://www.ja-sig.org/products/cas/overview/protocol
+    def logout_url(destination_url = nil, follow_url = nil)
       url = @logout_url || (cas_base_url + "/logout")
       
-      if service_url || back_url
+      if destination_url
+        # if present, remove the 'ticket' parameter from the destination_url
+        duri = URI.parse(destination_url)
+        h = duri.query ? query_to_hash(duri.query) : {}
+        h.delete('ticket')
+        duri.query = hash_to_query(h)
+        destination_url = duri.to_s.gsub(/\?$/, '')
+      end
+      
+      if destination_url || follow_url
         uri = URI.parse(url)
         h = uri.query ? query_to_hash(uri.query) : {}
-        h['service'] = service_url if service_url
-        h['url'] = back_url if back_url
+        h['destination'] = destination_url if destination_url
+        h['url'] = follow_url if follow_url
         uri.query = hash_to_query(h)
         uri.to_s
       else
@@ -83,6 +96,30 @@ module CASClient
     end
     alias validate_proxy_ticket validate_service_ticket
     
+    # Returns true if the configured CAS server is up and responding;
+    # false otherwise.
+    def cas_server_is_up?
+      uri = URI.parse(login_url)
+      
+      log.debug "Checking if CAS server at URI '#{uri}' is up..."
+      
+      https = Net::HTTP.new(uri.host, uri.port)
+      https.use_ssl = (uri.scheme == 'https')
+      
+      begin
+        raw_res = https.start do |conn|
+          conn.get("#{uri.path}?#{uri.query}")
+        end
+      rescue Errno::ECONNREFUSED => e
+        log.warn "CAS server did not respond! (#{e.inspect})"
+        return false
+      end
+      
+      log.debug "CAS server responded with #{raw_res.inspect}:\n#{raw_res.body}"
+      
+      return raw_res.kind_of?(Net::HTTPSuccess)
+    end
+    
     # Requests a login using the given credentials for the given service; 
     # returns a LoginResponse object.
     def login_to_service(credentials, service)
@@ -167,18 +204,30 @@ module CASClient
     # Fetches a CAS response of the given type from the given URI.
     # Type should be either ValidationResponse or ProxyResponse.
     def request_cas_response(uri, type)
-      log.debug "Requesting CAS response form URI #{uri.inspect}"
+      log.debug "Requesting CAS response for URI #{uri}"
       
       uri = URI.parse(uri) unless uri.kind_of? URI
       https = Net::HTTP.new(uri.host, uri.port)
       https.use_ssl = (uri.scheme == 'https')
-      raw_res = https.start do |conn|
-        conn.get("#{uri.path}?#{uri.query}")
-      end
       
-      #TODO: check to make sure that response code is 200 and handle errors otherwise
+      begin
+        raw_res = https.start do |conn|
+          conn.get("#{uri.path}?#{uri.query}")
+        end
+      rescue Errno::ECONNREFUSED => e
+        log.error "CAS server did not respond! (#{e.inspect})"
+        raise "The CAS authentication server at #{uri} is not responding!"
+      end
       
-      log.debug "CAS Responded with #{raw_res.inspect}:\n#{raw_res.body}"
+      # We accept responses of type 422 since RubyCAS-Server generates these
+      # in response to requests from the client that are processable but contain
+      # invalid CAS data (for example an invalid service ticket).
+      if raw_res.kind_of?(Net::HTTPSuccess) || raw_res.code.to_i == 422
+        log.debug "CAS server responded with #{raw_res.inspect}:\n#{raw_res.body}"
+      else
+        log.error "CAS server responded with an error! (#{raw_res.inspect})"
+        raise "The CAS authentication server at #{uri} responded with an error (#{raw_res.inspect})!"
+      end
       
       type.new(raw_res.body)
     end

data/lib/casclient/frameworks/merb/filter.rb

@@ -0,0 +1,105 @@
+module CASClient
+  module Frameworks
+    module Merb
+      module Filter
+        attr_reader :client
+
+        def cas_filter
+          @client ||= CASClient::Client.new(config)
+
+          service_ticket = read_ticket(self)
+
+          cas_login_url = client.add_service_to_login_url(read_service_url(self))
+
+          last_service_ticket = session[:cas_last_valid_ticket]
+          if (service_ticket && last_service_ticket && 
+              last_service_ticket.ticket == service_ticket.ticket && 
+              last_service_ticket.service == service_ticket.service)
+
+            # warn() rather than info() because we really shouldn't be re-validating the same ticket. 
+            # The only time when this is acceptable is if the user manually does a refresh and the ticket
+            # happens to be in the URL.
+            log.warn("Reusing previously validated ticket since the new ticket and service are the same.")
+            service_ticket = last_service_ticket
+          elsif last_service_ticket &&
+            !config[:authenticate_on_every_request] && 
+            session[client.username_session_key]
+            # Re-use the previous ticket if the user already has a local CAS session (i.e. if they were already
+            # previously authenticated for this service). This is to prevent redirection to the CAS server on every
+            # request.
+            # This behaviour can be disabled (so that every request is routed through the CAS server) by setting
+            # the :authenticate_on_every_request config option to false. 
+            log.debug "Existing local CAS session detected for #{session[client.username_session_key].inspect}. "+
+              "Previous ticket #{last_service_ticket.ticket.inspect} will be re-used."
+              service_ticket = last_service_ticket
+          end
+
+          if service_ticket
+            client.validate_service_ticket(service_ticket) unless service_ticket.has_been_validated?
+            validation_response = service_ticket.response
+
+            if service_ticket.is_valid?
+              log.info("Ticket #{service_ticket.inspect} for service #{service_ticket.service.inspect} " + 
+                "belonging to user #{validation_response.user.inspect} is VALID.")
+
+              session[client.username_session_key] = validation_response.user
+              session[client.extra_attributes_session_key] = validation_response.extra_attributes
+
+              # Store the ticket in the session to avoid re-validating the same service
+              # ticket with the CAS server.
+              session[:cas_last_valid_ticket] = service_ticket
+              return true
+            else  
+              log.warn("Ticket #{service_ticket.ticket.inspect} failed validation -- " + 
+                "#{validation_response.failure_code}: #{validation_response.failure_message}")
+              redirect cas_login_url
+              throw :halt
+            end
+          else
+            log.warn("No ticket -- redirecting to #{cas_login_url}")
+            redirect cas_login_url
+            throw :halt
+          end
+        end
+
+        private
+        # Copied from Rails adapter
+        def read_ticket(controller)
+          ticket = controller.params[:ticket]
+
+          return nil unless ticket
+
+          log.debug("Request contains ticket #{ticket.inspect}.")
+
+          if ticket =~ /^PT-/
+            ProxyTicket.new(ticket, read_service_url(controller), controller.params[:renew])
+          else
+            ServiceTicket.new(ticket, read_service_url(controller), controller.params[:renew])
+          end
+        end
+
+        # Also copied from Rails adapter
+        def read_service_url(controller)
+          if config[:service_url]
+            log.debug("Using explicitly set service url: #{config[:service_url]}")
+            return config[:service_url]
+          end
+
+          params = controller.params.dup
+          params.delete(:ticket)
+          service_url = request.protocol + '://' + request.host / controller.url(params.to_hash.symbolize_keys!)
+          log.debug("Guessed service url: #{service_url.inspect}")
+          return service_url
+        end
+
+        def log
+          ::Merb.logger
+        end
+
+        def config
+          ::Merb::Plugins.config[:"rubycas-client"]
+        end
+      end
+    end
+  end
+end

data/lib/casclient/frameworks/merb/strategy.rb

@@ -0,0 +1,110 @@
+# The 'cas' strategy attempts to login users based on the CAS protocol 
+# http://www.ja-sig.org/products/cas/overview/background/index.html
+# 
+# install the rubycas-client gem
+# http://rubyforge.org/projects/rubycas-client/
+#
+require 'casclient'
+class Merb::Authentication
+  module Strategies
+    class CAS < Merb::Authentication::Strategy
+
+      include CASClient
+
+      def run!
+        @client ||= Client.new(config)
+
+        service_ticket = read_ticket
+
+        cas_login_url = @client.add_service_to_login_url(service_url)
+
+        last_service_ticket = session[:cas_last_valid_ticket]
+        if (service_ticket && last_service_ticket && 
+            last_service_ticket.ticket == service_ticket.ticket && 
+            last_service_ticket.service == service_ticket.service)
+
+          # warn() rather than info() because we really shouldn't be re-validating the same ticket. 
+          # The only time when this is acceptable is if the user manually does a refresh and the ticket
+          # happens to be in the URL.
+          log.warn("Reusing previously validated ticket since the new ticket and service are the same.")
+          service_ticket = last_service_ticket
+        elsif last_service_ticket &&
+          !config[:authenticate_on_every_request] && 
+          session[@client.username_session_key]
+          # Re-use the previous ticket if the user already has a local CAS session (i.e. if they were already
+          # previously authenticated for this service). This is to prevent redirection to the CAS server on every
+          # request.
+          # This behaviour can be disabled (so that every request is routed through the CAS server) by setting
+          # the :authenticate_on_every_request config option to false. 
+          log.debug "Existing local CAS session detected for #{session[@client.username_session_key].inspect}. "+
+                  "Previous ticket #{last_service_ticket.ticket.inspect} will be re-used."
+                  service_ticket = last_service_ticket
+        end
+
+        if service_ticket
+          @client.validate_service_ticket(service_ticket) unless service_ticket.has_been_validated?
+          validation_response = service_ticket.response
+
+          if service_ticket.is_valid?
+            log.info("Ticket #{service_ticket.inspect} for service #{service_ticket.service.inspect} " + 
+                    "belonging to user #{validation_response.user.inspect} is VALID.")
+
+            session[@client.username_session_key] = validation_response.user
+            session[@client.extra_attributes_session_key] = validation_response.extra_attributes
+
+            # Store the ticket in the session to avoid re-validating the same service
+            # ticket with the CAS server.
+            session[:cas_last_valid_ticket] = service_ticket
+            return true
+          else  
+            log.warn("Ticket #{service_ticket.ticket.inspect} failed validation -- " + 
+                    "#{validation_response.failure_code}: #{validation_response.failure_message}")
+            redirect!(cas_login_url)
+            return false
+          end
+        else
+          log.warn("No ticket -- redirecting to #{cas_login_url}")
+          redirect!(cas_login_url)
+          return false
+        end
+      end
+
+      def read_ticket
+        ticket = request.params[:ticket]
+
+        return nil unless ticket
+
+        log.debug("Request contains ticket #{ticket.inspect}.")
+
+        if ticket =~ /^PT-/
+          ProxyTicket.new(ticket, service_url, request.params[:renew])
+        else
+          ServiceTicket.new(ticket, service_url, request.params[:renew])
+        end
+      end
+
+      def service_url
+        if config[:service_url]
+          log.debug("Using explicitly set service url: #{config[:service_url]}")
+          return config[:service_url]
+        end
+
+        params = request.params.dup
+        params.delete(:ticket)
+        service_url = "#{request.protocol}://#{request.host}" + request.path
+        log.debug("Guessed service url: #{service_url.inspect}")
+        return service_url
+      end
+
+      def config
+        ::Merb::Plugins.config[:"rubycas-client"]
+      end
+
+      def log
+        ::Merb.logger
+      end
+
+    end # CAS
+  end # Strategies
+end
+

data/lib/casclient/frameworks/rails/filter.rb

@@ -12,17 +12,39 @@ module CASClient
         class << self
           def filter(controller)
             raise "Cannot use the CASClient filter because it has not yet been configured." if config.nil?
+            
+            last_st = controller.session[:cas_last_valid_ticket]
+            
+            if single_sign_out(controller)
+              controller.send(:render, :text => "CAS Single-Sign-Out request intercepted.")
+              return false 
+            end
 
             st = read_ticket(controller)
             
-            lst = controller.session[:cas_last_valid_ticket]
+            is_new_session = true
             
-            if st && lst && lst.ticket == st.ticket && lst.service == st.service
+            if st && last_st && 
+                last_st.ticket == st.ticket && 
+                last_st.service == st.service
               # warn() rather than info() because we really shouldn't be re-validating the same ticket. 
-              # The only time when this is acceptable is if the user manually does a refresh and the ticket
-              # happens to be in the URL.
-              log.warn("Re-using previously validated ticket since the new ticket and service are the same.")
-              st = lst
+              # The only situation where this is acceptable is if the user manually does a refresh and 
+              # the same ticket happens to be in the URL.
+              log.warn("Re-using previously validated ticket since the ticket id and service are the same.")
+              st = last_st
+              is_new_session = false
+            elsif last_st &&
+                !config[:authenticate_on_every_request] && 
+                controller.session[client.username_session_key]
+              # Re-use the previous ticket if the user already has a local CAS session (i.e. if they were already
+              # previously authenticated for this service). This is to prevent redirection to the CAS server on every
+              # request.
+              # This behaviour can be disabled (so that every request is routed through the CAS server) by setting
+              # the :authenticate_on_every_request config option to false.
+              log.debug "Existing local CAS session detected for #{controller.session[client.username_session_key].inspect}. "+
+                "Previous ticket #{last_st.ticket.inspect} will be re-used."
+              st = last_st
+              is_new_session = false
             end
             
             if st
@@ -30,30 +52,47 @@ module CASClient
               vr = st.response
               
               if st.is_valid?
-                log.info("Ticket #{st.ticket.inspect} for service #{st.service.inspect} belonging to user #{vr.user.inspect} is VALID.")
-                controller.session[client.username_session_key] = vr.user
-                controller.session[client.extra_attributes_session_key] = vr.extra_attributes
-                
-                # RubyCAS-Client 1.x used :casfilteruser as it's username session key,
-                # so we need to set this here to ensure compatibility with configurations
-                # built around the old client.
-                controller.session[:casfilteruser] = vr.user
-                
+                if is_new_session
+                  log.info("Ticket #{st.ticket.inspect} for service #{st.service.inspect} belonging to user #{vr.user.inspect} is VALID.")
+                  controller.session[client.username_session_key] = vr.user.dup
+                  controller.session[client.extra_attributes_session_key] = HashWithIndifferentAccess.new(vr.extra_attributes.dup)
+                  
+                  if vr.extra_attributes
+                    log.debug("Extra user attributes provided along with ticket #{st.ticket.inspect}: #{vr.extra_attributes.inspect}.")
+                  end
+                  
+                  # RubyCAS-Client 1.x used :casfilteruser as it's username session key,
+                  # so we need to set this here to ensure compatibility with configurations
+                  # built around the old client.
+                  controller.session[:casfilteruser] = vr.user
+                  
+                  if config[:enable_single_sign_out]
+                    f = store_service_session_lookup(st, controller.request.session_options[:id] || controller.session.session_id)
+                    log.debug("Wrote service session lookup file to #{f.inspect} with session id #{controller.request.session_options[:id] || controller.session.session_id.inspect}.")
+                  end
+                end
+              
                 # Store the ticket in the session to avoid re-validating the same service
                 # ticket with the CAS server.
                 controller.session[:cas_last_valid_ticket] = st
                 
                 if vr.pgt_iou
-                  log.info("Receipt has a proxy-granting ticket IOU. Attempting to retrieve the proxy-granting ticket...")
-                  pgt = client.retrieve_proxy_granting_ticket(vr.pgt_iou)
-                  if pgt
-                    log.debug("Got PGT #{pgt.ticket.inspect} for PGT IOU #{pgt.iou.inspect}. This will be stored in the session.")
-                    controller.session[:cas_pgt] = pgt
-                    # For backwards compatibility with RubyCAS-Client 1.x configurations...
-                    controller.session[:casfilterpgt] = pgt
+                  unless controller.session[:cas_pgt] && controller.session[:cas_pgt].ticket && controller.session[:cas_pgt].iou == vr.pgt_iou
+                    log.info("Receipt has a proxy-granting ticket IOU. Attempting to retrieve the proxy-granting ticket...")
+                    pgt = client.retrieve_proxy_granting_ticket(vr.pgt_iou)
+
+                    if pgt
+                      log.debug("Got PGT #{pgt.ticket.inspect} for PGT IOU #{pgt.iou.inspect}. This will be stored in the session.")
+                      controller.session[:cas_pgt] = pgt
+                      # For backwards compatibility with RubyCAS-Client 1.x configurations...
+                      controller.session[:casfilterpgt] = pgt
+                    else
+                      log.error("Failed to retrieve a PGT for PGT IOU #{vr.pgt_iou}!")
+                    end
                   else
-                    log.error("Failed to retrieve a PGT for PGT IOU #{vr.pgt_iou}!")
+                    log.info("PGT is present in session and PGT IOU #{vr.pgt_iou} matches the saved PGT IOU.  Not retrieving new PGT.")
                   end
+
                 end
                 
                 return true
@@ -62,16 +101,13 @@ module CASClient
                 redirect_to_cas_for_authentication(controller)
                 return false
               end
-            elsif !config[:authenticate_on_every_request] && controller.session[client.username_session_key]
-              # Don't re-authenticate with the CAS server if we already previously authenticated and the
-              # :authenticate_on_every_request option is disabled (it's disabled by default).
-              log.debug "Existing local CAS session detected for #{controller.session[client.username_session_key].inspect}. "+
-                "User will not be re-authenticated."
-              return true
             else
               if returning_from_gateway?(controller)
                 log.info "Returning from CAS gateway without authentication."
-                
+
+                # reset, so that we can retry authentication if there is a subsequent request
+                controller.session[:cas_sent_to_gateway] = false
+
                 if use_gatewaying?
                   log.info "This CAS client is configured to use gatewaying, so we will permit the user to continue without authentication."
                   return true
@@ -96,13 +132,37 @@ module CASClient
             @@config[:use_gatewaying]
           end
           
-          def returning_from_gateway?(controller)
-            controller.session[:cas_sent_to_gateway]
+          # Returns the login URL for the current controller. 
+          # Useful when you want to provide a "Login" link in a GatewayFilter'ed
+          # action. 
+          def login_url(controller)
+            service_url = read_service_url(controller)
+            url = client.add_service_to_login_url(service_url)
+            log.debug("Generated login url: #{url}")
+            return url
+          end
+          
+          # Clears the given controller's local Rails session, does some local 
+          # CAS cleanup, and redirects to the CAS logout page. Additionally, the
+          # <tt>request.referer</tt> value from the <tt>controller</tt> instance 
+          # is passed to the CAS server as a 'destination' parameter. This 
+          # allows RubyCAS server to provide a follow-up login page allowing
+          # the user to log back in to the service they just logged out from 
+          # using a different username and password. Other CAS server 
+          # implemenations may use this 'destination' parameter in different 
+          # ways. 
+          # If given, the optional <tt>service</tt> URL overrides 
+          # <tt>request.referer</tt>.
+          def logout(controller, service = nil)
+            referer = service || controller.request.referer
+            st = controller.session[:cas_last_valid_ticket]
+            delete_service_session_lookup(st) if st
+            controller.send(:reset_session)
+            controller.send(:redirect_to, client.logout_url(referer))
           end
           
           def redirect_to_cas_for_authentication(controller)
-            service_url = read_service_url(controller)
-            redirect_url = client.add_service_to_login_url(service_url)
+            redirect_url = login_url(controller)
             
             if use_gatewaying?
               controller.session[:cas_sent_to_gateway] = true
@@ -111,11 +171,92 @@ module CASClient
               controller.session[:cas_sent_to_gateway] = false
             end
             
+            if controller.session[:previous_redirect_to_cas] &&
+                controller.session[:previous_redirect_to_cas] > (Time.now - 1.second)
+              log.warn("Previous redirect to the CAS server was less than a second ago. The client at #{controller.request.remote_ip.inspect} may be stuck in a redirection loop!")
+              controller.session[:cas_validation_retry_count] ||= 0
+              
+              if controller.session[:cas_validation_retry_count] > 3
+                log.error("Redirection loop intercepted. Client at #{controller.request.remote_ip.inspect} will be redirected back to login page and forced to renew authentication.")
+                redirect_url += "&renew=1&redirection_loop_intercepted=1"
+              end
+              
+              controller.session[:cas_validation_retry_count] += 1
+            else
+              controller.session[:cas_validation_retry_count] = 0
+            end
+            controller.session[:previous_redirect_to_cas] = Time.now
+            
             log.debug("Redirecting to #{redirect_url.inspect}")
             controller.send(:redirect_to, redirect_url)
           end
           
           private
+          def single_sign_out(controller)
+            
+            # Avoid calling raw_post (which may consume the post body) if
+            # this seems to be a file upload
+            if content_type = controller.request.headers["CONTENT_TYPE"] &&
+                content_type =~ %r{^multipart/}
+              return false
+            end
+            
+            if controller.request.post? &&
+                controller.params['logoutRequest'] &&
+                controller.params['logoutRequest'] =~
+                  %r{^<samlp:LogoutRequest.*?<samlp:SessionIndex>(.*)</samlp:SessionIndex>}m
+              # TODO: Maybe check that the request came from the registered CAS server? Although this might be
+              #       pointless since it's easily spoofable...
+              si = $~[1]
+              
+              unless config[:enable_single_sign_out]
+                log.warn "Ignoring single-sign-out request for CAS session #{si.inspect} because ssout functionality is not enabled (see the :enable_single_sign_out config option)."
+                return false
+              end
+              
+              log.debug "Intercepted single-sign-out request for CAS session #{si.inspect}."
+              
+              begin
+                required_sess_store = ActiveRecord::SessionStore
+                current_sess_store  = ActionController::Base.session_store
+              rescue NameError
+                # for older versions of Rails (prior to 2.3)
+                required_sess_store = CGI::Session::ActiveRecordStore
+                current_sess_store  = ActionController::Base.session_options[:database_manager]
+              end
+
+
+              if current_sess_store == required_sess_store
+                session_id = read_service_session_lookup(si)
+
+                if session_id
+                  session = current_sess_store::Session.find_by_session_id(session_id)
+                  if session
+                    session.destroy
+                    log.debug("Destroyed #{session.inspect} for session #{session_id.inspect} corresponding to service ticket #{si.inspect}.")
+                  else
+                    log.debug("Data for session #{session_id.inspect} was not found. It may have already been cleared by a local CAS logout request.")
+                  end
+                  
+                  log.info("Single-sign-out for session #{session_id.inspect} completed successfuly.")
+                else
+                  log.warn("Couldn't destroy session with SessionIndex #{si} because no corresponding session id could be looked up.")
+                end
+              else
+                log.error "Cannot process logout request because this Rails application's session store is "+
+                  " #{current_sess_store.name.inspect}. Single Sign-Out only works with the "+
+                  " #{required_sess_store.name.inspect} session store."
+              end
+              
+              # Return true to indicate that a single-sign-out request was detected
+              # and that further processing of the request is unnecessary.
+              return true
+            end
+            
+            # This is not a single-sign-out request.
+            return false
+          end
+          
           def read_ticket(controller)
             ticket = controller.params[:ticket]
             
@@ -130,6 +271,10 @@ module CASClient
             end
           end
           
+          def returning_from_gateway?(controller)
+            controller.session[:cas_sent_to_gateway]
+          end
+          
           def read_service_url(controller)
             if config[:service_url]
               log.debug("Using explicitly set service url: #{config[:service_url]}")
@@ -142,6 +287,46 @@ module CASClient
             log.debug("Guessed service url: #{service_url.inspect}")
             return service_url
           end
+          
+          # Creates a file in tmp/sessions linking a SessionTicket
+          # with the local Rails session id. The file is named
+          # cas_sess.<session ticket> and its text contents is the corresponding 
+          # Rails session id.
+          # Returns the filename of the lookup file created.
+          def store_service_session_lookup(st, sid)
+            st = st.ticket if st.kind_of? ServiceTicket
+            f = File.new(filename_of_service_session_lookup(st), 'w')
+            f.write(sid)
+            f.close
+            return f.path
+          end
+          
+          # Returns the local Rails session ID corresponding to the given
+          # ServiceTicket. This is done by reading the contents of the
+          # cas_sess.<session ticket> file created in a prior call to 
+          # #store_service_session_lookup.
+          def read_service_session_lookup(st)
+            st = st.ticket if st.kind_of? ServiceTicket
+            ssl_filename = filename_of_service_session_lookup(st)
+            return File.exists?(ssl_filename) && IO.read(ssl_filename)
+          end
+          
+          # Removes a stored relationship between a ServiceTicket and a local
+          # Rails session id. This should be called when the session is being
+          # closed.
+          #
+          # See #store_service_session_lookup.
+          def delete_service_session_lookup(st)
+            st = st.ticket if st.kind_of? ServiceTicket
+            ssl_filename = filename_of_service_session_lookup(st)
+            File.delete(ssl_filename) if File.exists?(ssl_filename)
+          end
+          
+          # Returns the path and filename of the service session lookup file.
+          def filename_of_service_session_lookup(st)
+            st = st.ticket if st.kind_of? ServiceTicket
+            return "#{RAILS_ROOT}/tmp/sessions/cas_sess.#{st}"
+          end
         end
       end
     
@@ -152,4 +337,4 @@ module CASClient
       end
     end
   end
-end
+end