= RubyCAS-Client

Author::    Matt Walker, with modification and docs by Matt Zukowski
Copyright:: Copyright (c) retained by the authors
License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
Website::   http://rubyforge.org/projects/rubycas-client

=== RubyCAS-Client is a Ruby client library for Yale's Central Authentication Service (CAS) protocol.

CAS provides a solid and secure single sign on solution for web-based applications. When a user logs on to your
CAS-enabled website, the CAS client checks with the CAS server to see if the user has been centrally authenticated.
If not, the user is redirected to your CAS server's web-based login page where they enter their credentials, and upon
successful authentication are redirected back to your client web application. If the user has been previously
authenticated with the CAS server (with their "ticket" being held as a session cookie), they are transparently
allowed to go about their business.

This client requires a CAS server to talk to. You can obtain a Java implementation of such a server as well as more info
about the CAS protocol here: http://www.ja-sig.org/products/cas

This CAS client library is designed to work easily with Rails, but can of course be used elsewhere.

=== Installing

You can always download the latest version of RubyCAS-Client from the project's rubyforge page at http://rubyforge.org/projects/rubycas-client.
The library is also available as a gem, which can be installed by:

  gem install rubycas-client
  
The latest development version is availabe via subversion:

  svn checkout svn://rubyforge.org/var/svn/rubycas-client/trunk/ruby
  
Please contact the developers via the {rubyforge.org page}[svn checkout svn://rubyforge.org/var/svn/rubycas-client] if you have bug fixes
or enhancements you would like to contribute back.

=== Here is an example of how to use the library in your Rails application:

Somewhere in your +config/environment.rb+ file add this:

  require_gem 'rubycas-client'

  CAS.cas_server_host = 'login.mycompany.com'
  CAS.cas_server_port = '443'

Then, in your +app/controllers/application.rb+ (or in whatever controller you want to add the CAS filter for):

  before_filter CAS::CASFilter
  
That's it. You should now find that you are redirected to your CAS login page when you try to access any action
in your protected controller. You can of course qualify the +before_filter+ as you would with any other ActionController
filter. For example: +before_filter CAS::CASFilter, :except => [ :unprotected_action, :another_unprotected_action ]

<b>Once the user has been authenticated, their authenticated username is available under +session[:user]+</b>

=== A more complicated example:

The CAS client library provides callback methods that can be overridden to inject your user management business logic.
For example, ordinarily after authentication the user's username is placed in +session[:user]+. Rather than storing
the username you may want to store a User object (e.g. a User ActiveRecord model). Here is an example of how to do this:

In your +config/environment.rb+ file add this:

  require_gem 'rubycas-client'

  CAS.cas_server_host = 'login.mycompany.com'
  CAS.cas_server_port = '443'

  module CAS
    def self.load_user_data(username, cas_payload)
      user = User.find_by_username(username)
      user = User.new(:username => username) if user.nil?
  
      user.last_login = Time.now
      
      return user
    end
  
    def self.save_user_data(user)
      user.save
    end
  end
  
In the above example, +load_user_data+ is overridden to load the user data based on the authenticated username.
+save_user_data+ is also overidden to save any changes made to the user model by the login process (in this case,
the last_login column is updated). See the CAS module documentation for more information on callbacks.

Another feature available in the CAS library is the ability to refresh the authentication ticket with the server
at some specified interval. Normally when the user logs in, their authentication info is stored in the local
web session and no futher queries are made to the CAS server. This may result in a situation where the remote CAS
authentication ticket has expired, but the local session authentication has not. To prevent this from happening
you can specify a +refresh_ticket_interval+ (in minutes) as follows:

  CAS.refresh_ticket_interval = 15
  
The CAS client will now check at every request if the local authentication info is older than 15 minutes. If it is,
it will transparently re-authenticate with the server. Note that because of the way the re-authentication process works,
after re-authenticating the user will have a +ticket+ query variable attached to the end of their current URL for that request
(i.e. http://mycompany.com/somepage/index?ticket=123456789).

== 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
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
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
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