README.rdoc in rubycas-client-2.2.1 vs README.rdoc in rubycas-client-2.3.0.rc1

- old
+ new

@@ -1,15 +1,15 @@ = 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> +Authors:: Matt Zukowski <matt AT roughest DOT net> and Matt Campbell <matt AT soupmatt DOT com>; inspired by code by Ola Bini <ola.bini AT ki DOT se> and Matt Walker <mwalker AT tamu DOT edu> Copyright:: Portions contributed by Matt Zukowski are copyright (c) 2009 Urbacon Ltd. + Portions contributed by Matt Campbell, Rich Yarger and Rahul Joshi are copyright (c) 2011 Vibes Media LLC. Other portions are copyright of their respective authors. License:: MIT License -Websites:: http://github.com/gunark/rubycas-client - http://code.google.com/p/rubycas-client - http://rubyforge.org/projects/rubycas-client - +Websites:: http://github.com/rubycas/rubycas-client + http://github.com/rubycas/rubycas-client/wiki + http://rubydoc.info/github/rubycas/rubycas-client/master/frames === 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 @@ -34,31 +34,33 @@ API documentation (i.e. the RDocs) are available at http://rubycas-client.rubyforge.org == Installation +<b>NOTE:</b> For compatibility with Rails 3 have a look at https://github.com/zuk/rubycas-client-rails + +The current version of RubyCAS-Client should work with Rails 2.3.6 and up. For compatibility with +older Rails try using an older version of the client. + You can download the latest version of RubyCAS-Client from the project's rubyforge page at http://rubyforge.org/projects/rubycas-client. 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 + ./script/plugin install git://github.com/gunark/rubycas-client.git 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 + ./script/plugin install -x http://svn.github.com/gunark/rubycas-client.git -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 If you'd rather jump right in, have a look at the example Rails and Merb applications pre-configured for CAS authentication: @@ -106,11 +108,11 @@ 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 = 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", @@ -147,11 +149,11 @@ 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, +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). @@ -228,16 +230,15 @@ 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 = 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 @@ -253,16 +254,13 @@ 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). - +Run rails using a server that handles multiple concurrent requests. In development, you can use Phusion Passenger Standalone, +POW (http://pow.cx/), unicorn and many others. In production, I imagine you already support multiple concurrent requests. + 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: @@ -313,9 +311,15 @@ CASClient::Frameworks::Rails::Filter.fake("homer") This functionality was present in the original version of this plugin. The value of the username is stored in session[:cas_user] (or the user specified field) and session[:casfilteruser] for backwards-compatibility. + +If you need to fake out extra attributes, you can do so like this: + + CASClient::Frameworks::Rails::Filter.fake("homer", {:role => "user", :email => "homer@test.foo"}) + +And the extra attributes will get put in the proper place in the session. == License RubyCAS-Client is licensed for use under the terms of the MIT License. See the LICENSE.txt file bundled with the official RubyCAS-Client distribution for details.