rubycas-client 2.0.1 → 2.1.0

data/CHANGELOG.txt

@@ -1,114 +1 @@
-= RubyCAS-Client Changelog
-
-== Version 2.0.1 :: 2008-02-27
-
-* The Rails filter no longer by default redirects to the CAS server on 
-  every request. This restores the behaviour of RubyCAS-Client 1.x.
-  In other words, if a session[:cas_user] value exists, the filter
-  will assume that the user is authenticated without going through the
-  CAS server. This behaviour can be disabled (so that a CAS re-check is 
-  done on every request) by setting the 'authenticate_on_every_request' 
-  option to true. See the "Re-authenticating on every request" section 
-  in the README.txt for details. 
-
-== Version 2.0.0 :: 2008-02-14
-
-* COMPLETE RE-WRITE OF THE ENTIRE CLIENT FROM THE GROUND UP. Oh yes.
-* Core client has been abstracted out of the Rails adapter. It should now
-  be possible to use the client in other frameworks (e.g. Camping).
-* Configuration syntax has completely changed. In other words, your old
-  rubycas-client-1.x configuration will no longer work. See the README
-  for details.
-* Added support for reading extra attributes from the CAS response (i.e. in
-  addition to just the username). However currently this is somewhat useless
-  since RubyCAS-Server does not yet provide a method for adding extra
-  attributes to the responses it generates.
-
-== 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
-  take it out of beta and release version 1.0.
-* Non-SSL CAS URLs will now work. This may be useful for demo purposes, 
-  but certainly shouldn't be used in production. The client automatically
-  disables SSL if the CAS URL starts with http (rather than https). [rubywmq]
-
-== Version 0.12.0
-
-* Prior to redirecting to the CAS login page, the client now stores the
-  current service URI in a session variable. This value is used to
-  validate the service ticket after the user comes back from the CAS
-  server's login page. This should address issues where redirection
-  from the CAS server resulted in a slightly different URI from the original
-  one used prior to login redirection (for example due to variations in the
-  way routing rules are applied by the server).
-* The client now handles malformed CAS server responses more gracefully.
-  This makes debugging a malfunctioning CAS server somewhat easier.
-* When receiving a proxy-granting ticket, the cas_proxy_callback_controller
-  can now take a parameter called 'pgt' (which is what ought to be used
-  according to the published CAS spec) or 'pgtId' (which is what the JA-SIG
-  CAS server uses).
-* Logging has been somewhat quieted down. Many messages that were previously
-  logged as INFO are now logged as DEBUG.
-
-== Version 0.11.0
-
-* Added this changelog to advise users of major changes to the library.
-
-* Large chunks of the library have been re-written. Beware of the possibility
-  of new bugs (although the re-write was meant to fix a whole slew of existing
-  bugs, so you're almost certainly better off upgrading).
-
-* service and targetService parameters in requests are now properly URI-encoded,
-  so the filter should behave properly when your service has query parameters.
-  Thanks sakazuki for pointing out the problem.
-
-* You can now force the CAS client to re-authenticate itself with the CAS server
-  (i.e. override the authentication stored in the session) by providing a new
-  service ticket in the URI. In other words, the client will authenticate with
-  CAS if: a) you have a 'ticket' parameter in the URI, and there is currently no
-  authentication info in the session, or b) you have a 'ticket' parameter in the
-  URI and this ticket is different than the ticket that was used to authenticat
-  the existing session. This is especially useful when you are using CAS proxying,
-  since it allows you to force re-authentication in proxied applications (for
-  example, when the user has logged out and a new user has logged in in the parent
-  proxy-granting application).
-
-* If your service URI has a 'ticket' parameter, it will now be automatically
-  removed when passing the service as a parameter in any CAS request. This is
-  done because at least some CAS servers will happily accept a service URI with
-  a 'ticket' parameter, which will result in a URI with  multiple 'ticket' 
-  parameters once you are redirected back to CAS (and that in turn can result 
-  in an endless redirection loop).
-
-* Logging has been greatly improved, which should make debugging your CAS
-  installation much easier. Look for the logs under log/cas_client_RAILS_ENV.log
-
-* When you install RubyCAS-Client as a Rails plugin, it will now by default
-  use a custom logger. You can change this by explicitly setting your own
-  logger in your environment.rb, or by modifying the plugin's init.rb.
-
-* CasProxyCallbackController no longer checks to make sure that the incoming
-  request is secure. The check is impossible since the secure header is not 
-  passed on by at least some reverse proxies (like Pound), and if you are using
-  the callback controller then you are almost certainly also using a reverse
-  proxy.
-
-* Cleaned up and updated documentation, fixed some example code.
+See History.txt

data/History.txt

@@ -0,0 +1,162 @@
+= RubyCAS-Client Changelog
+
+== 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. (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.
+    
+* Changes to existing functionality:
+  * The 'service' parameter in the logout method has been renamed to
+    'destination' to better match the behaviour of other CAS clients. So for
+    example, when you call logout_url("http://foo.example"), the method will
+    now return "https://cas.example?destination=https%3A%2F%2Ffoo.example"
+    instead of the old "https://cas.example?service=https%3A%2F%2Ffoo.example".
+    RubyCAS-Server has been modified to deal with this as of version 0.6.0.
+  * We now accept HTTP responses from the CAS server with status code 422 since 
+    RubyCAS-Server 0.7.0+ generates these in response to requests that are 
+    processable but contain invalid CAS data (for example an invalid service 
+    ticket).
+  * Some behind-the-scenes changes to the way previous authentication info is
+    reused by the Rails filter in subsequent requests (see the note below 
+    in the 2.0.1 release). From the user's and integrator's point of view 
+    there shouldn't be any obvious difference from 2.0.1.
+  * Redirection loop interception: The client now logs a warning message when it 
+    believes that it is stuck in a redirection loop with the CAS server. If more 
+    than three of these redirects occur within one second, the client will
+    redirect back to the login page with renew=1, forcing the user to try
+    authenticating again. 
+  * Somewhat better handling and logging of errors resulting from CAS server
+    connection/response problems.
+
+* Bug Fixes:
+  * Fixed bug where the the service/destination parameter in the logout url
+    would sometimes retain the 'ticket' value. The ticket is now automatically
+    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
+
+* The Rails filter no longer by default redirects to the CAS server on 
+  every request. This restores the behaviour of RubyCAS-Client 1.x.
+  In other words, if a session[:cas_user] value exists, the filter
+  will assume that the user is authenticated without going through the
+  CAS server. This behaviour can be disabled (so that a CAS re-check is 
+  done on every request) by setting the 'authenticate_on_every_request' 
+  option to true. See the "Re-authenticating on every request" section 
+  in the README.txt for details. 
+
+== Version 2.0.0 :: 2008-02-14
+
+* COMPLETE RE-WRITE OF THE ENTIRE CLIENT FROM THE GROUND UP. Oh yes.
+* Core client has been abstracted out of the Rails adapter. It should now
+  be possible to use the client in other frameworks (e.g. Camping).
+* Configuration syntax has completely changed. In other words, your old
+  rubycas-client-1.x configuration will no longer work. See the README
+  for details.
+* Added support for reading extra attributes from the CAS response (i.e. in
+  addition to just the username). However currently this is somewhat useless
+  since RubyCAS-Server does not yet provide a method for adding extra
+  attributes to the responses it generates.
+
+------------------------------------------------------------------------------
+
+== 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
+  take it out of beta and release version 1.0.
+* Non-SSL CAS URLs will now work. This may be useful for demo purposes, 
+  but certainly shouldn't be used in production. The client automatically
+  disables SSL if the CAS URL starts with http (rather than https). [rubywmq]
+
+== Version 0.12.0
+
+* Prior to redirecting to the CAS login page, the client now stores the
+  current service URI in a session variable. This value is used to
+  validate the service ticket after the user comes back from the CAS
+  server's login page. This should address issues where redirection
+  from the CAS server resulted in a slightly different URI from the original
+  one used prior to login redirection (for example due to variations in the
+  way routing rules are applied by the server).
+* The client now handles malformed CAS server responses more gracefully.
+  This makes debugging a malfunctioning CAS server somewhat easier.
+* When receiving a proxy-granting ticket, the cas_proxy_callback_controller
+  can now take a parameter called 'pgt' (which is what ought to be used
+  according to the published CAS spec) or 'pgtId' (which is what the JA-SIG
+  CAS server uses).
+* Logging has been somewhat quieted down. Many messages that were previously
+  logged as INFO are now logged as DEBUG.
+
+== Version 0.11.0
+
+* Added this changelog to advise users of major changes to the library.
+* Large chunks of the library have been re-written. Beware of the possibility
+  of new bugs (although the re-write was meant to fix a whole slew of existing
+  bugs, so you're almost certainly better off upgrading).
+* service and targetService parameters in requests are now properly URI-encoded,
+  so the filter should behave properly when your service has query parameters.
+  Thanks sakazuki for pointing out the problem.
+* You can now force the CAS client to re-authenticate itself with the CAS server
+  (i.e. override the authentication stored in the session) by providing a new
+  service ticket in the URI. In other words, the client will authenticate with
+  CAS if: a) you have a 'ticket' parameter in the URI, and there is currently no
+  authentication info in the session, or b) you have a 'ticket' parameter in the
+  URI and this ticket is different than the ticket that was used to authenticat
+  the existing session. This is especially useful when you are using CAS proxying,
+  since it allows you to force re-authentication in proxied applications (for
+  example, when the user has logged out and a new user has logged in in the parent
+  proxy-granting application).
+* If your service URI has a 'ticket' parameter, it will now be automatically
+  removed when passing the service as a parameter in any CAS request. This is
+  done because at least some CAS servers will happily accept a service URI with
+  a 'ticket' parameter, which will result in a URI with  multiple 'ticket' 
+  parameters once you are redirected back to CAS (and that in turn can result 
+  in an endless redirection loop).
+* Logging has been greatly improved, which should make debugging your CAS
+  installation much easier. Look for the logs under log/cas_client_RAILS_ENV.log
+* When you install RubyCAS-Client as a Rails plugin, it will now by default
+  use a custom logger. You can change this by explicitly setting your own
+  logger in your environment.rb, or by modifying the plugin's init.rb.
+* CasProxyCallbackController no longer checks to make sure that the incoming
+  request is secure. The check is impossible since the secure header is not 
+  passed on by at least some reverse proxies (like Pound), and if you are using
+  the callback controller then you are almost certainly also using a reverse
+  proxy.
+* Cleaned up and updated documentation, fixed some example code.

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}

@@ -3,7 +3,10 @@
 Author::    Matt Zukowski <matt AT roughest DOT net>; inspired by code by Ola Bini <ola.bini AT ki DOT se> and Matt Walker <mwalker AT tamu DOT edu>
 Copyright:: (c) 2008 Urbacon Ltd.
 License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
-Website::   http://code.google.com/p/rubycas-client and http://rubyforge.org/projects/rubycas-client
+Websites::   http://code.google.com/p/rubycas-client
+             http://github.com/gunark/rubycas-client
+             http://rubyforge.org/projects/rubycas-client
+            
 
 
 === RubyCAS-Client is a Ruby client library for Yale's Central Authentication Service (CAS) protocol.
@@ -16,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
 
@@ -23,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
@@ -43,17 +52,27 @@ 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
 
 <i>Note that from this point on we are assuming that you have a working CAS server up and running!</i>
 
-After installing RubyCAS-Client as a plugin (see above), add the following to your app's <tt>config/environment.rb</tt>:
+After installing RubyCAS-Client as a plugin (see above), add the following to your app's <tt>config/environment.rb</tt>
+(make sure that you put it at the bottom of the file, *after* the Rails Initializer):
   
   CASClient::Frameworks::Rails::Filter.configure(
     :cas_base_url => "https://cas.example.foo/"
@@ -76,6 +95,11 @@ filter. For example:
 If you want to do something with this username (for example load a user record from the database), you can append another 
 filter method that checks for this value and does whatever you need it to do.
 
+<b>Note:</b> If Rails complains about missing constants, try adding this before the CASClient configuration:
+
+  require 'casclient'
+  require 'casclient/frameworks/rails/filter'
+
 
 ==== A more complicated example
 
@@ -91,19 +115,19 @@ Here is a more complicated configuration showing most of the configuration optio
     :login_url     => "https://cas.example.foo/login",
     :logout_url    => "https://cas.example.foo/logout",
     :validate_url  => "https://cas.example.foo/proxyValidate",
-    :session_username_key => :cas_user,
-    :session_extra_attributes_key => :cas_extra_attributes
+    :username_session_key => :cas_user,
+    :extra_attributes_session_key => :cas_extra_attributes,
     :logger => cas_logger,
-    :authenticate_on_every_request => true
+    :enable_single_sign_out => true
   )
 
-Note that it is normally not necessary to specify <tt>:login_url</tt>, <tt>:logout_url</tt>, and <tt>:validate_url</tt>.
+Note that normally it is not necessary to specify <tt>:login_url</tt>, <tt>:logout_url</tt>, and <tt>:validate_url</tt>.
 These values are automatically set to standard CAS defaults based on the given <tt>:cas_base_url</tt>.
 
-The <tt>:session_username_key</tt> value determines the key under which you can find the CAS username in the Rails session hash.
+The <tt>:username_session_key</tt> value determines the key under which you can find the CAS username in the Rails session hash.
 
 Any additional info that the CAS server might have supplied about the user during authentication will be found under the
-<tt>:session_extra_attributes_key</tt> value in the Rails session hash (i.e. given the above configuration, you would find this
+<tt>:extra_attributes_session_key</tt> value in the Rails session hash (i.e. given the above configuration, you would find this
 info under <tt>session[:cas_extra_attributes]</tt>).
 
 An arbitrary Logger instance can be given as the :logger parameter. In the example above we log all CAS activity to a 
@@ -119,29 +143,49 @@ 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 session[:cas_user] 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
 
-Your Rails application's controller(s) will probably have some sort of logout function. In it you will likely 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:
+Your Rails application's controller(s) will probably have some sort of logout function. Here you can do any necessary local
+cleanup, and then call <tt>CASClient::Frameworks::Rails::Filter.logout(controller)</tt>. For example:
 
-class ApplicationController < ActionController::Base
+  class ApplicationController < ActionController::Base
+    
+    # ...
   
-  # ...
-
-  def logout
-    reset_session
-    redirect_to CAS::Filter.logout_url(self, request.referer)
+    def logout
+      # optionally do some local cleanup here
+      # ...
+      
+      CASClient::Frameworks::Rails::Filter.logout(self)
+    end
   end
-end
 
+By default, the logout method will clear the local Rails session, do some local CAS cleanup, and redirect 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. 
 
 ==== Gatewayed (i.e. optional) authentication
 
@@ -161,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
 
@@ -221,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!
@@ -272,4 +319,4 @@ GNU General Public License for more details.
 
 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
+Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA