gunark-rubycas-client 2.0.99 → 2.1.0

data/History.txt

@@ -1,18 +1,24 @@
 = RubyCAS-Client Changelog
 
-== Version 2.1.0 :: In Progress...
+== Version 2.1.0 :: 2009-08-18
 
 * New functionality:
+  * Added an adapter for the Merb framework. Thanks to Andrew O'Brien and
+    Antono Vasiljev.
   * Implemented single-sign-out functionality. The client will now intercept
     single-sign-out requests and deal with them appropriately if the
     :enable_single_sign_out config option is set to true. This is currently
-    disabled by default.
+    disabled by default. (Currently this is only implemented for the Rails
+    adapter)
   * Added logout method to Rails adapter to simplify the logout process. The
     logout method resets the local Rails session and redirects to the CAS
     logout page.
+  * Added login_url method to the Rails filter. This will return the login
+    URL for the current controller; useful when you want to show a "Login"
+    link in a gatewayed page for an unauthenticated user.
+  * Added cas_server_is_up? method to the client, as requested in issue #5.
   * Extra user attributes are now automatically unserialized if the incoming data 
     is in YAML format.
-  * Added cas_server_is_up? method to the client as requested in issue #5.
     
 * Changes to existing functionality:
   * The 'service' parameter in the logout method has been renamed to
@@ -43,6 +49,10 @@
     stripped from the logout url.
   * The client will no longer attempt to retrieve a PGT for an IOU that had
     already been previously retrieved. [yipdw1]
+    
+* Misc:
+  * Added complete CAS client integration examples for Rails and Merb 
+    applications under /examples.
 
 == Version 2.0.1 :: 2008-02-27
 

data/Manifest.txt

@@ -2,11 +2,18 @@ CHANGELOG.txt
 History.txt
 LICENSE.txt
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
+examples/merb/README.textile
+examples/merb/Rakefile
+examples/merb/merb.thor
+examples/merb/merb_auth_cas.rb
+examples/merb/spec/spec_helper.rb
 init.rb
 lib/casclient.rb
 lib/casclient/client.rb
+lib/casclient/frameworks/merb/filter.rb
+lib/casclient/frameworks/merb/strategy.rb
 lib/casclient/frameworks/rails/cas_proxy_callback_controller.rb
 lib/casclient/frameworks/rails/filter.rb
 lib/casclient/responses.rb

data/{README.txt → README.rdoc}

@@ -19,6 +19,10 @@ For general information about the open CAS protocol, please have a look at http:
 If your organization does not already have a CAS server, you may be interested in RubyCAS-Client's sister project,
 RubyCAS-Server[http://code.google.com/p/rubycas-server/].
 
+The RubyCAS-Client package includes adapters for Rails and Merb, although the client library itself can be
+adapted for other frameworks (for example an implementation for Camping is available via the Picnic[http://github.com/zuk/picnic/tree/master]
+library).
+
 
 == Getting help and reporting problems
 
@@ -26,13 +30,15 @@ If you need help, try posting to the RubyCAS discussion group at http://groups.g
 
 To report problems, please use the Google Code issue tracker at http://code.google.com/p/rubycas-client/issues/list.
 
+API documentation (i.e. the RDocs) are available at http://rubycas-client.rubyforge.org
+
 
 == Installation
 
 You can download the latest version of RubyCAS-Client from the project's rubyforge page at 
 http://rubyforge.org/projects/rubycas-client.
 
-However, it is easier to install the CAS client into a Ruby on Rails app as a plugin:
+However, if you're using Rails, it's easier to install the CAS client as a plugin:
 
   cd <your rails app>
   ./script/plugin install http://rubycas-client.googlecode.com/svn/trunk/rubycas-client
@@ -46,11 +52,20 @@ you always have the latest bleeding-edge version of RubyCAS-Client:
 
   ./script/plugin install -x http://rubycas-client.googlecode.com/svn/trunk/rubycas-client
 
+With Rails 2.1 or newer, it is also possible to install the plugin directly from the bleeding-edge git repository:
+
+  ./script/plugin install git://github.com/gunark/rubycas-client.git
 
 == Usage Examples
 
-Although RubyCAS-Client can be used with other web Frameworks (for example Camping), the following examples
-are aimed at {Ruby on Rails}[http://rubyonrails.org].
+If you'd rather jump right in, have a look at the example Rails and Merb applications pre-configured for CAS
+authentication:
+
+http://github.com/gunark/rubycas-client/tree/master/examples
+
+
+Otherwise, continue reading for a step-by-step guide for integrating RubyCAS-Client with Rails:
+
 
 ==== Using RubyCAS-Client in Rails controllers
 
@@ -101,9 +116,9 @@ Here is a more complicated configuration showing most of the configuration optio
     :logout_url    => "https://cas.example.foo/logout",
     :validate_url  => "https://cas.example.foo/proxyValidate",
     :username_session_key => :cas_user,
-    :extra_attributes_session_key => :cas_extra_attributes
+    :extra_attributes_session_key => :cas_extra_attributes,
     :logger => cas_logger,
-    :authenticate_on_every_request => true
+    :enable_single_sign_out => true
   )
 
 Note that normally it is not necessary to specify <tt>:login_url</tt>, <tt>:logout_url</tt>, and <tt>:validate_url</tt>.
@@ -128,12 +143,25 @@ the disadvantage is that the filter no longer checks to make sure that the user'
 In other words it is possible for the user's authentication session to be closed on the CAS server without the
 client application knowing about it.
 
-In the future RubyCAS-Client will support the new "Single Sign-Out" functionality in CAS 3.1, allowing the server to 
-notify the client application that the CAS session is closed, but for now it is up to you  to handle this by, for example, 
-by wiping the local <tt>session[:cas_user]</tt> value periodically to force a CAS re-check.
+To address this, RubyCAS-Client now supports the new "Single Sign-Out" functionality in CAS 3.1, allowing the server to 
+notify the client application that the CAS session is closed. The client will automatically intercept Single Sign-Out
+requsts from the CAS server, but in order for this to work you must configure your Rails application as follows:
+
+1. The Rails session store must be set to ActiveRecord: <tt>config.action_controller.session_store = :active_record_store</tt>
+2. The server must be able to read and write to RAILS_ROOT/tmp/sessions. If you are in a clustered environment,
+   the contents of this directory must be shared between all server instances. 
+3. Cross-site request forgery protection must be disabled. In your <tt>application.rb</tt>: <tt>self.allow_forgery_protection = false</tt>.
+   (Or rather you may want to disable forgery protection only for actions that are behind the CAS filter.)
+4. Finally, you must add <tt>:enable_single_sign_out => true</tt> to your CAS client config (a similar option must be
+   enabled on the CAS server, if you're using RubyCAS-Server).
+
+The best way to debug single-sign out functionality is to configure your CAS client with logging (see above) and then watch the
+log to ensure that single-sign out requests from the server are being processed correctly.
+
  
-Alternatively, it is possible to disable this authentication persistence behaviour by setting the <tt>:authenticate_on_every_request</tt>
-configuration option to true as in the example above.
+Alternatively, it is possible to disable authentication persistence in the client by setting the <tt>:authenticate_on_every_request</tt>
+configuration option to true as, in the example in the previous section. However, this is not recommended as it will almost
+certainly have a deleterious impact on performance and can interfere with certain HTTP transactions (AJAX requests, for example). 
 
 
 ==== Defining a 'logout' action
@@ -177,6 +205,9 @@ CAS authentication for all actions in a controller except the index action:
     # ...
   end
   
+To provide a login URL for unauthenticated users:
+
+  <%= link_to("Login", CASClient::Frameworks::Rails::Filter.login_url(controller)) %>
 
 ==== How to act as a CAS proxy
 
@@ -237,12 +268,12 @@ to authenticate another application:
 
   service_uri = "http://some-other-application.example.foo"
   proxy_granting_ticket = session[:cas_pgt]
-  ticket = CASClient::Frameworks::Rails::Filter.client.request_proxy_ticket(service_uri, proxy_granting_ticket).ticket
+  proxy_ticket = CASClient::Frameworks::Rails::Filter.client.request_proxy_ticket(service_uri, proxy_granting_ticket)
   
-<tt>ticket</tt> should now contain a valid service ticket. You can use it to authenticate other services by sending it and 
+<tt>proxy_ticket</tt> should now contain a valid proxy ticket. You can use it to authenticate other services by sending it together with 
 the service URI as parameters to your target application:
 
-  http://some-other-application.example.foo?service=#{CGI.encode(ticket.target_service)}&ticket=#{ticket.proxy_ticket}
+  http://some-other-application.example.foo?service=#{CGI::escape(proxy_ticket.service)}&ticket=#{proxy_ticket.ticket}
   
 This is of course assuming that http://some-other-application.example.foo is also protected by the CAS filter. 
 Note that you should always URI-encode your service parameter inside URIs!

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(/\/$/, '')       

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

@@ -66,8 +66,10 @@ module CASClient
                   # built around the old client.
                   controller.session[:casfilteruser] = vr.user
                   
-                  f = store_service_session_lookup(st, controller.session.session_id)
-                  log.debug("Wrote service session lookup file to #{f.inspect} with session id #{controller.session.session_id.inspect}.")
+                  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
@@ -102,7 +104,10 @@ module CASClient
             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
@@ -127,6 +132,16 @@ module CASClient
             @@config[:use_gatewaying]
           end
           
+          # 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 
@@ -147,8 +162,7 @@ module CASClient
           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
@@ -194,16 +208,29 @@ module CASClient
               # TODO: Maybe check that the request came from the registered CAS server? Although this might be
               #       pointless since it's easily spoofable...
               si = $~[1]
-              log.debug "Intercepted single-sign-out request for CAS session #{si.inspect}."
               
-              required_sess_store = CGI::Session::ActiveRecordStore
-              current_sess_store  = ActionController::Base.session_options[:database_manager]
+              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 = CGI::Session::ActiveRecordStore::Session.find_by_session_id(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}.")
@@ -271,7 +298,7 @@ module CASClient
             f = File.new(filename_of_service_session_lookup(st), 'w')
             f.write(sid)
             f.close
-            return filename_of_service_session_lookup(st)
+            return f.path
           end
           
           # Returns the local Rails session ID corresponding to the given

data/lib/casclient/responses.rb

@@ -71,7 +71,11 @@ module CASClient
         
         # unserialize extra attributes
         @extra_attributes.each do |k, v|
-          @extra_attributes[k] = YAML.load(v)
+          if v.blank?
+            @extra_attributes[k] = nil
+          else
+            @extra_attributes[k] = YAML.load(v)
+          end
         end
       elsif is_failure?
         @failure_code = @xml.elements['//cas:authenticationFailure'].attributes['code']

data/lib/casclient/version.rb

@@ -1,8 +1,8 @@
 module CASClient #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 2
-    MINOR = 0
-    TINY  = 99
+    MINOR = 1
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: gunark-rubycas-client
 version: !ruby/object:Gem::Version 
-  version: 2.0.99
+  version: 2.1.0
 platform: ruby
 authors: 
 - Matt Zukowski
@@ -15,6 +15,7 @@ default_executable:
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -24,6 +25,7 @@ dependencies:
     version: 
 - !ruby/object:Gem::Dependency 
   name: hoe
+  type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
@@ -42,13 +44,13 @@ extra_rdoc_files:
 - History.txt
 - LICENSE.txt
 - Manifest.txt
-- README.txt
+- README.rdoc
 files: 
 - CHANGELOG.txt
 - History.txt
 - LICENSE.txt
 - Manifest.txt
-- README.txt
+- README.rdoc
 - Rakefile
 - init.rb
 - lib/casclient.rb
@@ -63,6 +65,7 @@ files:
 - setup.rb
 has_rdoc: true
 homepage: http://rubycas-client.rubyforge.org
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --main
@@ -84,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rubycas-client
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 2
 summary: Client library for the Central Authentication Service (CAS) protocol.