rubycas-client 1.0.0 → 1.1.0

data/CHANGES

@@ -1,5 +1,23 @@
 = RubyCAS-Client Changelog
 
+== Version 1.1.0 :: 2007-12-21
+
+* Fixed serious bug having to do with logouts. You can now end the
+  CAS session on the client-side (i.e. force the client to re-authenticate)
+  by setting session[:casfilteruser] = nil.
+* Added new GatewayFilter. This is identical to the normal Filter but
+  has the gateway option set to true by default. This should make
+  using the gateway option easier.
+* The CAS::Filter methods are now properly documented.
+* Simplified guess_service produces better URLs when redirecting to the CAS
+  server for authentication and the service URL is not explicitly specified. 
+  [delagoya]
+* The correct method for overriding the service URL for the client is now
+  properly documented. You should use service_url=, as server_name= no longer
+  works and instead generates a warning message.
+* logout_url() now takes an additional 'service' parameter. If specified, this
+  URL will be passed on to the CAS server as part of the logout URL. 
+
 == Version 1.0.0 :: 2007-07-26
 
 * RubyCAS-Client has matured to the point where it is probably safe to

data/README

@@ -85,6 +85,26 @@ which are covered in the next section):
 Note that in this example we explicitly specified the login and validate URLs instead of letting RubyCAS-Client figure them out
 based on <tt>CAS::Filter.cas_base_url</tt>.
 
+==== Defining a 'logout' action
+
+Your Rails application's controller(s) will probably have some sort of logout function. In it you will likely want reset the 
+user's session for your application, and then redirect to the CAS server's logout URL. Here's an example of how to do this:
+
+  def logout
+  	reset_session
+  	redirect_to CAS::Filter.logout_url(self, request.referer)
+  end
+
+==== Gatewayed authentication
+
+RubyCAS-Client supports gatewaying as of version 1.1.0. Gatewaying allows for optional CAS authentication, so that users who
+already have a pre-existing CAS SSO session will be automatically authenticated for the gatewayed service, while those who
+do not, will be allowed to access the service without authentication. This is useful for example when you want to show
+some additional private content on a homepage to authenticated users, but also want unauthenticated users to be able to
+access the page without first logging in.
+
+For more information on using gatewaying, see CAS::GatewayFilter.
+
 ==== How to act as a CAS proxy
 
 CAS 2.0 has a built-in mechanism that allows a CAS-authenticated application to pass on its authentication to other applications.
@@ -189,7 +209,7 @@ Then make sure the library for open SSL is installed. For example, on an Debian/
 == License
 
 This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
+it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
 
@@ -198,6 +218,6 @@ but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
-You should have received a copy of the GNU General Public License
+You should have received a copy of the GNU Lesser General Public License
 along with this program (see the file called LICENSE); if not, write to the
 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA

data/lib/cas.rb

@@ -80,11 +80,11 @@ module CAS
       begin
         doc = REXML::Document.new str
       rescue REXML::ParseException => e
-        raise MalformedServerResponseException, "BAD RESPONSE FROM CAS SERVER:\n#{str}\n\nEXCEPTION:\n#{e}"
+        raise MalformedServerResponseException, "BAD RESPONSE FROM CAS SERVER:\n#{str.inspect}\n\nEXCEPTION:\n#{e}"
       end
       
       unless doc.elements && doc.elements["cas:serviceResponse"]
-        raise MalformedServerResponseException, "BAD RESPONSE FROM CAS SERVER:\n#{str}\n\nXML DOC:\n#{doc.inspect}"
+        raise MalformedServerResponseException, "BAD RESPONSE FROM CAS SERVER:\n#{str.inspect}\n\nXML DOC:\n#{doc.inspect}"
       end
       
       resp = doc.elements["cas:serviceResponse"].elements[1]

data/lib/cas_auth.rb

@@ -39,20 +39,24 @@ module CAS
   # To use CAS::Filter for authentication, add something like this to
   # your environment:
   # 
-  #   CAS::Filter.server_name = "yourapplication.server.name"
   #   CAS::Filter.cas_base_url = "https://cas.company.com
   #   
   # The filter will try to use the standard CAS page locations based on this URL.
   # Or you can explicitly specify the individual URLs:
   #
-  #   CAS::Filter.server_name = "yourapplication.server.name"
   #   CAS::Filter.login_url = "https://cas.company.com/login"
   #   CAS::Filter.validate_url = "https://cas.company.com/proxyValidate"
   #
+  # The filter will also try to automatically figure out your CAS-protected application's 
+  # URL (to send the client back after authenticating on the CAS server), but you can 
+  # explicitly override:
+  #
+  #   CAS::Filter.service_url = "http://www.my-cas-protected-app.com/
+  #
   # It is of course possible to use different configurations in development, test
   # and production by placing the configuration in the appropriate environments file.
   #
-  # To add CAS protection to a controller:
+  # To add CAS protection to a Rails controller:
   # 
   #   before_filter CAS::Filter
   #   
@@ -76,25 +80,28 @@ module CAS
     @@login_url = "https://localhost/login"
     @@logout_url = nil
     @@validate_url = "https://localhost/proxyValidate"
-    @@server_name = "localhost"
     @@renew = false
     @@session_username = :casfilteruser
     @@query_string = {}
     @@fake = nil
     @@pgt = nil
     cattr_accessor :query_string
-    cattr_accessor :login_url, :validate_url, :service_url, :server_name, :renew, :wrap_request, :gateway, :session_username
+    cattr_accessor :login_url, :validate_url, :service_url, :wrap_request, :session_username
+    class_inheritable_accessor :gateway, :renew
     cattr_accessor :proxy_url, :proxy_callback_url, :proxy_retrieval_url
     @@authorized_proxies = []
     cattr_accessor :authorized_proxies
 
+    # gatewaying is disabled by default -- use GatewayFilter if you want gatewaying
+    self.gateway = false
 
     class << self
     
-      # Retrieves the current Logger instance
+      # Retrieves the Logger used by the filter
       def logger
         CAS::LOGGER
       end
+      # Sets the Logger used by the filter
       def logger=(val)
         CAS::LOGGER.set_logger(val)
       end
@@ -102,6 +109,9 @@ module CAS
       alias :log :logger
       alias :log= :logger=
   
+      # Builds the internal logout URL. The current @@logout_url value will
+      # be used if it is set. Otherwise we will try to figure it out based
+      # on the @@login_url.
       def create_logout_url
         if !@@logout_url && @@login_url =~ %r{^(.+?)/[^/]*$}
           @@logout_url = "#{$1}/logout"
@@ -109,18 +119,28 @@ module CAS
         logger.debug "Created logout url: #{@@logout_url}"
       end
       
-      def logout_url(controller)
+      # Returns the logout URL for the given controller.
+      # This method calls create_logout_url if no logout url has yet
+      # been created or set.
+      #
+      # Additionally a service URL can be provided and will be attached
+      # to the CAS server logout URL. If not provided, the service URL
+      # will be automatically derived using guess_service().
+      def logout_url(controller, service = nil)
         create_logout_url unless @@logout_url
-        url = redirect_url(controller,@@logout_url)
+        url = redirect_url(controller,@@logout_url,service)
         logger.debug "Logout url is: #{url}"
         url
       end
       
+      # Explicitly sets the logout URL.
       def logout_url=(url)
         @@logout_url = url
         logger.debug "Initialized logout url to: #{url}"
       end
       
+      # Sets the base CAS url. The login_url, validate_url, and proxy_url
+      # are automagically built on top of this.
       def cas_base_url=(url)
         url.gsub!(/\/$/, '')
         CAS::Filter.login_url = "#{url}/login"
@@ -128,15 +148,28 @@ module CAS
         CAS::Filter.proxy_url = "#{url}/proxy"
         logger.debug "Initialized CAS base url to: #{url}"
       end
-        
+      
+      # Returns the current @@fake value.
+      # This is used for debugging. See <tt>fake=</tt> and <tt>filter_f</tt>.
       def fake
         @@fake
       end
       
+      # Enables or disables the fake filter.
+      # This is used in debugging.
+      #
+      # The argument can have one of the following values:
+      #
+      # :failure :: The fake filter will always fail.
+      # :param :: The fake filter will use the 'username' request param to set 
+      #           the username.
+      # Proc :: The fake filter will execute the given proc to determine the 
+      #         username. The current controller will be fed to the Proc as an
+      #         argument.
+      # nil :: Disables the fake filter and enables the real filter.
       def fake=(val)
         if val.nil?
           alias :filter :filter_r
-          logger.info "Will use real filter"
         else
           alias :filter :filter_f
           logger.warn "Will use fake filter"
@@ -144,9 +177,11 @@ module CAS
           @@fake = val
         end
   
+      # This is the fake filter method. It is aliased as 'filter'
+      # when the fake filter is enabled. See <tt>fake=</tt>.
       def filter_f(controller)
           logger.break
-          logger.warn("Using fake CAS filter")
+          logger.warn "Using fake CAS filter"
         username = @@fake
         if :failure == @@fake
           return false
@@ -160,16 +195,36 @@ module CAS
         return true
       end
       
+      # This is the real filter method. It is aliased as 'filter'
+      # by default (when the fake filter is disabled).
+      #
+      # The filter method behaves like a standard Rails filter, taking
+      # the current controller as an argument (in order to access the current
+      # request params, the session, etc.). The method returns true
+      # when authentication is successful, false otherwise. Generally,
+      # before returning false the filter will send a HTTP redirect back to the 
+      # CAS server.
       def filter_r(controller)
         logger.break
         logger.info("Using real CAS filter in controller: #{controller}")
         
+        # We store the receipt in the session so that we do not have to fetch it again
+        # if we're asked to validate a ticket that has already been validated. This
+        # saves us from unnecessarily hitting the CAS server.
         session_receipt = controller.session[:casfilterreceipt]
         session_ticket = controller.session[:caslastticket]
         ticket = controller.params[:ticket]
   
         is_valid = false
         
+        if controller.session[:casfiltergateway]
+          log.debug "Coming back from gatewayed request to CAS server..."
+          did_gateway = true
+          controller.session[:casfiltergateway] = false
+        else
+          log.debug "This request is not gatewayed."
+        end
+        
         if ticket and (!session_ticket or session_ticket != ticket)
           log.info "A ticket parameter was given in the URI: #{ticket} and "+
             (!session_ticket ? "there is no previous ticket for this session" : 
@@ -203,10 +258,9 @@ module CAS
             end
           end
           
-        elsif session_receipt
+        elsif session_receipt && controller.session[@@session_username] && !@@renew
         
-          log.info "Validating receipt from the session because " + 
-            (ticket ? "the given ticket #{ticket} is the same as the old ticket" : "there was no ticket given in the URI") + "."
+          log.info "Validating receipt from the session (instead of checking with the CAS server) because we have a :casfilteruser and the filter is not configured with @@renew."
           log.debug "The session receipt is: #{session_receipt}"
           
           is_valid = validate_receipt(session_receipt)
@@ -221,19 +275,19 @@ module CAS
           
           log.info "No ticket was given and we do not have a receipt in the session."
         
-          did_gateway = controller.session[:casfiltergateway]
+          
           raise CASException, "Can't redirect without login url" unless @@login_url
           
           if did_gateway
-            if controller.session[@@session_username]
-              log.info "We gatewayed and have a username stored in the session. The gateway was therefore successful."
-              is_valid = true
+            log.info "We gatewayed and came back without authentication."
+            if self.gateway
+              log.info "This filter is configured to allow gatewaying, so we will permit the user to continue without authentication."
+              return true
             else
-              log.debug "We gatewayed but do not have a username stored in the session, so we will keep session[:casfiltergateway] true"
-              controller.session[:casfiltergateway] = true
+              log.warn "This filter is NOT configured to allow gatewaying, yet this request was gatewayed. Something is not right!"
             end
-          else
-            log.info "We did not gateway, so we will notify the filter that the next request is being gatewayed by setting sesson[:casfiltergateway} to true"
+          elsif self.gateway
+            log.debug "We did not gateway, so we will notify the filter that the next request is being gatewayed by setting sesson[:casfiltergateway] to true"
             controller.session[:casfiltergateway] = true
           end
           
@@ -250,13 +304,18 @@ module CAS
       end
       alias :filter :filter_r
         
-        
+      # Requests a proxy ticket from the CAS server and returns it as a ProxyTicketRequest object.
+      #
+      # Note that the ProxyTicketRequest object is returned regardless of whether the request
+      # is successful. You should check the returned object's proxy_ticket field to find out
+      # whether the request resulted in a valid proxy ticket.
       def request_proxy_ticket(target_service, pgt)
         r = ProxyTicketRequest.new
         r.proxy_url = @@proxy_url
         r.target_service = target_service
         r.pgt = pgt
   
+        # FIXME: Why is this here? The only way it would get raised is if the supplied pgt was nil/false? This might be a vestige...
         raise CAS::ProxyGrantingNotAvailable, "Cannot request a proxy ticket for service #{r.target_service} because no proxy granting ticket (PGT) has been set." unless r.pgt
         
         logger.info("Requesting proxy ticket for service: #{r.target_service} with PGT #{pgt}")
@@ -276,6 +335,10 @@ module CAS
     
     private
     
+      # Retrieves a proxy granting ticket corresponding to the given receipt's
+      # proxy granting ticket IOU from the proxy callback server.
+      #
+      # Returns a CAS::ProxyGrantingTicket object.
       def self.retrieve_pgt(receipt)
         retrieve_url = "#{@@proxy_retrieval_url}?pgtIou=#{receipt.pgt_iou}"
                 
@@ -288,6 +351,7 @@ module CAS
         return pgt
       end
     
+      # Returns true if the given CAS::Receipt is valid; false wotherwise.
       def self.validate_receipt(receipt)
         logger.info "Checking that the receipt is valid and coherent..."
         
@@ -321,6 +385,12 @@ module CAS
         return true
       end
   
+      # Fetches a CAS::Receipt for the given service or proxy ticket
+      # and returns it.
+      #
+      # Takes the current controller as the second argument in order to
+      # guess the current service URL when it is not explicitly set for
+      # the filter.
       def self.get_receipt_for_ticket(ticket, controller)
         logger.info "Getting receipt for ticket '#{ticket}'"
         pv = ProxyTicketValidator.new
@@ -343,6 +413,11 @@ module CAS
         receipt
       end
       
+      # Returns the service URL for the current service.
+      #
+      # This will return the @@service_url if it has been explicitly
+      # set; otherwise it will try to guess the service URL based
+      # on the given controller parameters (see <tt>guess_service()</tt>).
       def self.service_url(controller)
         unclean = @@service_url || guess_service(controller)
         clean = remove_ticket_from_service_uri(unclean)
@@ -350,15 +425,50 @@ module CAS
         clean
       end
       
+      def self.server_name=(s)
+        puts
+        puts "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+        puts "!!! CAS CONFIGURATION WARNING !!!"
+        puts "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+        puts
+        puts "CAS::Filter.server_name= no longer does anything."
+        puts 
+        puts "If you want to explicitly set the service, try using:"
+        puts "CAS::Filter.service_url = 'http://myservice.com'"
+        puts
+      end
+      
+      # Returns the URL to the login page of the CAS server with
+      # additional parameters like 'renew', and 'gateway' tacked
+      # on as appropriate. The <tt>url</tt> parameter can be used
+      # to use something other than the login url as the base.
+      #
+      # An optional <tt>service</tt> parameter can be provided to
+      # override the 'service' part of the URL.
+      #
       # FIXME: this method is really poorly named :(
-      def self.redirect_url(controller,url=@@login_url)
-        "#{url}?service=#{CGI.escape(service_url(controller))}" + 
+      def self.redirect_url(controller,url=@@login_url,service=nil)     
+        if service
+          service = remove_ticket_from_service_uri(service)
+        end
+        
+        service = CGI.escape(service || service_url(controller))  
+
+        "#{url}?service=#{service}" + 
           ((@@renew)? "&renew=true":"") + 
-          ((@@gateway)? "&gateway=true":"") + 
+          ((gateway)? "&gateway=true":"") + 
           ((@@query_string.blank?)? "" : "&" +
           (@@query_string.collect { |k,v| "#{k}=#{v}"}.join("&")))
       end
       
+      # Tries to figure out the current service URL. 
+      #
+      # This is used when the @@service_url has not been explicitly set. 
+      # The guessed URL (generally the current URL stripped of some 
+      # CAS-specific parameters) is fed to the CAS server so that the
+      # server knows where to redirect back after authentication.
+      #
+      # Also see <tt>redirect_url</tt>.
       def self.guess_service(controller)
         logger.info "Guessing service based on params: #{controller.params.inspect}"
         
@@ -378,18 +488,16 @@ module CAS
         end
         
         parms.delete("ticket")
-        
-        query = (parms.collect {|key, val| "#{key}=#{val}"}).join("&")
-        query = "?" + query unless query.empty?
-        
-        service = "#{req.protocol}#{@@server_name}#{req.request_uri.split(/\?/)[0]}#{query}"
+        service = controller.url_for(parms)
         
         logger.info "Guessed service is: #{service}"
         
         return service
       end
       
+      # URI-encodes the 
       def self.escape_service_uri(uri)
+        # FIXME: Why aren't we just using  CGi.escape?
         URI.encode(uri, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]", false, 'U').freeze)
       end
       
@@ -401,6 +509,39 @@ module CAS
       end
   end
   
+  # The GatewayFilter is identical to the normal Filter, but has the gateway 
+  # option set to true by default. This makes it easier to use in cases where 
+  # authentication is optional.
+  #
+  # For example, say your 'index' view is accessible by authenticated and 
+  # unauthenticated users, but you want some additional content shown for 
+  # authenticated users. You can use the GatewayFilter to check if the user is 
+  # already authenticated with CAS and provide them with a service ticket for 
+  # the new service. If they are not already authenticated, then they will be 
+  # allowed to see the 'index' view without being asked for a login.
+  #
+  # To achieve this in a Rails controller, you should set up your filters as follows:
+  #
+  #   before_filter CAS::Filter, :except => [:index]  
+  #   before_filter CAS::GatewayFilter, :only => [:index]
+  #
+  # Note that you cannot use the 'renew' option with the GatewayFilter since the 
+  # 'gateway' and 'renew' options have roughly opposite meanings -- 'renew' forces
+  # re-authentication, while 'gateway' makes authentication optional.
+  class GatewayFilter < Filter
+    self.gateway = true
+    self.renew = false
+    
+    def logout_url
+      uri = URI.parse(super)
+      if uri.query?
+        uri.to_s + "&gateway=true"
+      else
+        uri.to_s + "?gateway=true"
+      end
+    end
+  end
+  
   class ProxyGrantingNotAvailable < Exception
   end
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.2
 specification_version: 1
 name: rubycas-client
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
-date: 2007-07-26 00:00:00 -04:00
+  version: 1.1.0
+date: 2007-12-21 12:37:15.306028 -05:00
 summary: Client library for the CAS single-sign-on protocol.
 require_paths: 
 - lib