rubycas-client 1.1.0 → 2.0.0

data/{CHANGES → CHANGELOG.txt}

@@ -1,5 +1,18 @@
 = RubyCAS-Client Changelog
 
+== 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

data/{LICENSE → LICENSE.txt}

@@ -1,36 +1,3 @@
-Copyright (c) 2006 Karolinska Institutet
-(Karolinska Institutet, Stockholm, Sweden).
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
-
- 3. Neither the name of Karolinska Institutet nor the names of its contributors
-    may be used to endorse or promote products derived from this software
-    without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY KAROLINSKA INSTITUTET AND CONTRIBUTORS ``AS IS''
- AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- ARE DISCLAIMED.  IN NO EVENT SHALL KAROLINSKA INSTITUTET OR CONTRIBUTORS BE 
- LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
-===============================================================================
-
 		  GNU LESSER GENERAL PUBLIC LICENSE
 		       Version 2.1, February 1999
 
@@ -88,7 +55,7 @@ modified by someone else and passed on, the recipients should know
 that what they have is not the original version, so that the original
 author's reputation will not be affected by problems that might be
 introduced by others.
-
+
   Finally, software patents pose a constant threat to the existence of
 any free program.  We wish to make sure that a company cannot
 effectively restrict the users of a free program by obtaining a
@@ -144,7 +111,7 @@ modification follow.  Pay close attention to the difference between a
 "work based on the library" and a "work that uses the library".  The
 former contains code derived from the library, whereas the latter must
 be combined with the library in order to run.
-
+
 		  GNU LESSER GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
@@ -191,7 +158,7 @@ Library.
   You may charge a fee for the physical act of transferring a copy,
 and you may at your option offer warranty protection in exchange for a
 fee.
-
+
   2. You may modify your copy or copies of the Library or any portion
 of it, thus forming a work based on the Library, and copy and
 distribute such modifications or work under the terms of Section 1
@@ -249,7 +216,7 @@ instead of to this License.  (If a newer version than version 2 of the
 ordinary GNU General Public License has appeared, then you can specify
 that version instead if you wish.)  Do not make any other change in
 these notices.
-
+
   Once this change is made in a given copy, it is irreversible for
 that copy, so the ordinary GNU General Public License applies to all
 subsequent copies and derivative works made from that copy.
@@ -300,7 +267,7 @@ Library will still fall under Section 6.)
 distribute the object code for the work under the terms of Section 6.
 Any executables containing that work also fall under Section 6,
 whether or not they are linked directly with the Library itself.
-
+
   6. As an exception to the Sections above, you may also combine or
 link a "work that uses the Library" with the Library to produce a
 work containing portions of the Library, and distribute that work
@@ -362,7 +329,7 @@ restrictions of other proprietary libraries that do not normally
 accompany the operating system.  Such a contradiction means you cannot
 use both them and the Library together in an executable that you
 distribute.
-
+
   7. You may place library facilities that are a work based on the
 Library side-by-side in a single library together with other library
 facilities not covered by this License, and distribute such a combined
@@ -403,7 +370,7 @@ subject to these terms and conditions.  You may not impose any further
 restrictions on the recipients' exercise of the rights granted herein.
 You are not responsible for enforcing compliance by third parties with
 this License.
-
+
   11. If, as a consequence of a court judgment or allegation of patent
 infringement or for any other reason (not limited to patent issues),
 conditions are imposed on you (whether by court order, agreement or
@@ -455,7 +422,7 @@ conditions either of that version or of any later version published by
 the Free Software Foundation.  If the Library does not specify a
 license version number, you may choose any version ever published by
 the Free Software Foundation.
-
+
   14. If you wish to incorporate parts of the Library into other free
 programs whose distribution conditions are incompatible with these,
 write to the author to ask for permission.  For software which is
@@ -489,7 +456,7 @@ SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 DAMAGES.
 
 		     END OF TERMS AND CONDITIONS
-
+
            How to Apply These Terms to Your New Libraries
 
   If you develop a new library, and you want it to be of the greatest

data/Manifest.txt

@@ -0,0 +1,16 @@
+CHANGELOG.txt
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+init.rb
+lib/casclient.rb
+lib/casclient/client.rb
+lib/casclient/frameworks/rails/cas_proxy_callback_controller.rb
+lib/casclient/frameworks/rails/filter.rb
+lib/casclient/responses.rb
+lib/casclient/tickets.rb
+lib/casclient/version.rb
+lib/rubycas-client.rb
+setup.rb

data/README.txt

@@ -0,0 +1,257 @@
+= RubyCAS-Client
+
+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
+
+
+=== RubyCAS-Client is a Ruby client library for Yale's Central Authentication Service (CAS) protocol.
+
+CAS provides a secure single sign on solution for web-based applications. The user logs in to your
+organization's CAS server, and is automatically authenticated for all other CAS-enabled applications.
+
+For general information about the open CAS protocol, please have a look at http://www.ja-sig.org/products/cas.
+
+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/].
+
+
+== Getting help and reporting problems
+
+If you need help, try posting to the RubyCAS discussion group at http://groups.google.com/group/rubycas-server.
+
+To report problems, please use the Google Code issue tracker at http://code.google.com/p/rubycas-client/issues/list.
+
+
+== 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:
+
+  cd <your rails app>
+  ./script/plugin install http://rubycas-client.googlecode.com/svn/trunk/rubycas-client
+
+Alternatively, the library is also installable as a RubyGem[http://rubygems.org]:
+
+  gem install rubycas-client
+  
+If your Rails application is under Subversion control, you can also install the plugin as an svn:external, ensuring that
+you always have the latest bleeding-edge version of RubyCAS-Client:
+
+  ./script/plugin install -x http://rubycas-client.googlecode.com/svn/trunk/rubycas-client
+
+
+== 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].
+
+==== 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>:
+  
+  CASClient::Frameworks::Rails::Filter.configure(
+    :cas_base_url => "https://cas.example.foo/"
+  )
+  
+(Change the <tt>:cas_base_url</tt> value to your CAS server's base URL; also note that many CAS servers are configured
+with a base URL that looks more like "https://cas.example.foo/cas".)
+
+Then, in your <tt>app/controllers/application.rb</tt> (or in whichever controller you want to add the CAS filter for):
+
+  before_filter CASClient::Frameworks::Rails::Filter
+  
+That's it. You should now find that you are redirected to your CAS login page whenever you try to access any action
+in your protected controller. You can of course qualify the <tt>before_filter</tt> as you would with any other ActionController
+filter. For example: 
+
+  before_filter CASClient::Frameworks::Rails::Filter, :except => [ :unprotected_action, :another_unprotected_action ]
+
+<b>Once the user has been authenticated, their authenticated username is available under <tt>session[:cas_user]</tt>,</b>
+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.
+
+
+==== A more complicated example
+
+Here is a more complicated configuration showing most of the configuration options along with their default values
+(this does not show proxy options, which are covered in the next section):
+
+  # enable detailed CAS logging
+  cas_logger = CASClient::Logger.new(RAILS_ROOT+'/log/cas.log')
+  cas_logger.level = Logger::DEBUG
+
+  CASClient::Frameworks::Rails::Filter.configure(
+    :cas_base_url  => "https://cas.example.foo/",
+    :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
+    :logger => cas_logger
+  )
+
+Note that it is normally 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.
+
+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
+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 
+<tt>log/cas.log</tt> file in your Rails app's directory.
+
+
+==== 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:
+
+class ApplicationController < ActionController::Base
+  
+  # ...
+
+  def logout
+    reset_session
+    redirect_to CAS::Filter.logout_url(self, request.referer)
+  end
+end
+
+
+==== Gatewayed (i.e. optional) authentication
+
+"Gatewaying" essentially allows for optional CAS authentication. 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 anonymous users to be able to access the page without first logging in.
+
+To allow users to access a page without authenticatin, simply use <tt>CASClient::Frameworks::Rails::GatewayFilter</tt>
+in place of <tt>CASClient::Frameworks::Rails::Filter</tt> in your controller. For example, you may want to require
+CAS authentication for all actions in a controller except the index action:
+
+  class ExampleController < ApplicationController
+    before_filter CASClient::Frameworks::Rails::GatewayFilter, :only => :index
+    before_filter CASClient::Frameworks::Rails::Filter, :except => :index
+    
+    # ...
+  end
+  
+
+==== 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.
+An example where this is useful might be a portal site, where the user logs in to a central website and then gets forwarded to
+various other sites that run independently of the portal system (but are always accessed via the portal). The exact mechanism
+behind this is rather complicated so I won't go over it here. If you wish to learn more about CAS proxying, a great walkthrough
+is available at http://www.ja-sig.org/wiki/display/CAS/Proxy+CAS+Walkthrough.
+
+RubyCAS-Client fully supports proxying, so a CAS-protected Rails application can act as a CAS proxy.
+
+Additionally, RubyCAS-Client comes with a controller that can act as a CAS proxy callback receiver. This is necessary because
+when your application requests to act as a CAS proxy, the CAS server must contact your application to deposit the proxy-granting-ticket
+(PGT). Note that in this case the CAS server CONTACTS YOU, rather than you contacting the CAS server (as in all other CAS operations).
+
+Confused? Don't worry, you don't really have to understand this to use it. To enable your Rails app to act as a CAS proxy, 
+all you need to do is this:
+
+In your <tt>config/environment.rb</tt>:
+
+  # enable detailed CAS logging for easier troubleshooting
+  cas_logger = CASClient::Logger.new(RAILS_ROOT+'/log/cas.log')
+  cas_logger.level = Logger::DEBUG
+
+  CASClient::Frameworks::Rails::Filter.configure(
+    :cas_base_url => "https://cas.example.foo/",
+    :proxy_retrieval_url => "https://cas-proxy-callback.example.foo/cas_proxy_callback/retrieve_pgt",
+    :proxy_callback_url => "https://cas-proxy-callback.example.foo/cas_proxy_callback/receive_pgt",
+    :logger => cas_logger
+  )
+  
+In <tt>config/routes.rb</tt> make sure that you have a route that will allow requests to /cas_proxy_callback/:action to be routed to the
+CasProxyCallbackController. This should work as-is with the standard Rails routes setup, but if you have disabled the default
+route, you should add the following:
+
+  map.cas_proxy_callback 'cas_proxy_callback/:action', :controller => 'cas_proxy_callback'
+  
+Now here's a big giant caveat: <b>your CAS callback application and your CAS proxy application must run on separate Rails servers</b>.
+In other words, if you want a Rails app to act as a CAS ticket-granting proxy, the cas_proxy_callback controller
+must run on a different server. This is because Rails does not properly support handling of concurrent requests. The CAS proxy mechanism
+acts in such a way that if your proxy application and your callback controller were on the same server
+you would end up with a deadlock (the CAS server would be waiting for its callback to be accepted by your Rails server,
+but your Rails server wouldn't respond to the CAS server's callback until the CAS server responded back first).
+
+The simplest workaround is this:
+
+1. Create an empty rails app (i.e. something like <tt>rails cas_proxy_callback</tt>)
+2. Make sure that you have the CAS plugin installed. If you installed it as a gem, you don't have to do anything since
+   it is already installed. If you want to install as a plugin, see the instructions in the "Installing" section above.
+3. Make sure that the server is up and running, and configure your proxy_callback_url and proxy_retrieval_url to point
+   to the new server as described above (or rather, make Pound point to the new server, if that's how you're handling https).
+   
+That's it. The proxy_callback_controller doesn't require any additional configuration. It doesn't access the database
+or anything of that sort.
+
+Once your user logs in to CAS via your application, you can do the following to obtain a service ticket that can then be used
+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
+  
+<tt>ticket</tt> should now contain a valid service ticket. You can use it to authenticate other services by sending it and 
+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}
+  
+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!
+
+Note that #request_proxy_ticket returns a CASClient::ProxyTicket object, which is why we need to call #ticket on it 
+to retrieve the actual service ticket string.
+
+===== Additional proxying notes and caveats
+
+<b>The proxy url must be an https address.</b> Otherwise CAS will refuse to communicate with it. This means that if you are using
+the bundled cas_proxy_callback controller, you will have to host your application on an https-enabled server. This can be a bit
+tricky with Rails. WEBrick's SSL support is difficult to configure, and Mongrel doesn't support SSL at all. One workaround is to
+use a reverse proxy like Pound[http://www.apsis.ch/pound/], which will accept https connections and locally re-route them
+to your Rails application. Also, note that <i>self-signed SSL certificates likely won't work</i>. You will probably need to use
+a real certificate purchased from a trusted CA authority (there are ways around this, but good luck :)
+
+
+== SSL Support
+
+Make sure you have the Ruby OpenSSL library installed. Otherwise you may get errors like:
+
+  no such file to load -- net/https
+
+To install the library on an Debian/Ubuntu system:
+
+  sudo apt-get install libopenssl-ruby
+
+For other platforms you'll have to figure it out yourself.
+
+
+
+== License
+
+This program is free software; you can redistribute it and/or modify
+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.
+
+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 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/Rakefile

@@ -1,22 +1,56 @@
+require 'rubygems'
 require 'rake'
+require 'rake/clean'
 require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
 require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'casclient', 'version')
 
-desc 'Default: run unit tests.'
-task :default => :test
+AUTHOR = ["Matt Zukowski", "Matt Walker"]  # can also be an array of Authors
+EMAIL = "matt at roughest dot net"
+DESCRIPTION = "Client library for the Central Authentication Service (CAS) protocol."
+GEM_NAME = "rubycas-client" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "rubycas-client" # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
 
-desc 'Test the cas_auth plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
+
+NAME = "rubycas-client"
+REV = nil
+#REV = `svn info`[/Revision: (\d+)/, 1] rescue nil
+VERS = ENV['VERSION'] || (CASClient::VERSION::STRING + (REV ? ".#{REV}" : ""))
+                          CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "rubycas-client documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
 end
 
-desc 'Generate documentation for the cas_auth plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'CasAuth'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+  p.extra_deps = ['activesupport']
 end