vibes-rubycas-client 2.3.0.alpha

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ree-1.8.7-2011.03@rubycas-client

data/CHANGELOG.txt

@@ -0,0 +1 @@
+See History.txt

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.2"
+  gem "rcov", ">= 0"
+end
+
+gem "activesupport", "~> 2.3.11"

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (2.3.12)
+    git (1.2.5)
+    jeweler (1.6.2)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.9.2)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3.11)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.2)
+  rcov
+  shoulda

data/History.txt

@@ -0,0 +1,192 @@
+= RubyCAS-Client Changelog
+
+== Version 2.2.1 :: 2010-06-24
+
+* Removed a 3rd party patch to the logging mechanism that broke the client under
+  some circumstances. Ouch. 2.2.0 should never have made it through QA.
+
+== Version 2.2.0 :: 2010-06-22
+
+RubyCAS-Client is now licensed under the MIT License.
+See http://www.opensource.org/licenses/mit-license.php
+
+* New functionality:
+  * Added config parameter force_ssl_verification (self explanatory) [Roberto Klein]
+  * Added explicit SingleSignutFilter for Rails (convenient?) [Adam Elliot]
+  * Added support for faking out the filter; useful when testing. See
+    http://github.com/gunark/rubycas-client/commit/1eb10cc285d59193eede3d4406f95cad9db9d93a
+    [Brian Hogan]
+
+* Changes to existing functionality:
+  * Unauthorized requests to URLs ending in .xml now show an XML formatted
+    response (<errors><error>#{failure_message}</error></errors>) [Roberto Klein]
+  * Accepts HTTPFound (302) as a successful response from the CAS server (in
+    addition to HTTPSuccess (2xx) [taryneast]
+
+* Bug fixes:
+  * Got rid of warnings if @valid is not initialized in Responses [jamesarosen]
+  * Fixed warning when setting the logger [jamesarosen]
+  * Client should no longer crap out when using CAS v1 and extra_attributes is
+    empty [jorahood]
+
+
+== 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/LICENSE.txt

@@ -0,0 +1,26 @@
+Portions of RubyCAS-Client contributed by Matt Zukowski are copyright (c) 2009 Urbacon Ltd.
+Other portions are copyright of their respective authors.
+
+The MIT License
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+

data/README.rdoc

@@ -0,0 +1,321 @@
+= 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:: Portions contributed by Matt Zukowski are copyright (c) 2009 Urbacon Ltd.
+            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
+            
+
+
+=== 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/].
+
+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
+
+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.
+
+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
+
+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 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://svn.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:
+
+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>
+(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/"
+  )
+  
+(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.
+
+<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
+
+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",
+    :username_session_key => :cas_user,
+    :extra_attributes_session_key => :cas_extra_attributes,
+    :logger => cas_logger,
+    :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>.
+These values are automatically set to standard CAS defaults based on the given <tt>:cas_base_url</tt>.
+
+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>: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 
+<tt>log/cas.log</tt> file in your Rails app's directory.
+
+==== Re-authenticating on every request (i.e. the "single sign-out problem")
+
+By default, the Rails filter will only authenticate with the CAS server when no session[:cas_user] value exists. Once the user 
+has been authenticated, no further CAS forwarding is done until the user's session is wiped. This saves you
+the trouble of having to do this check yourself (since in most cases it is not advisable to go through the CAS server
+on every request -- this is slow and would potentially lead to problems, for example for AJAX requests). However,
+the disadvantage is that the filter no longer checks to make sure that the user's CAS session is still actually open.
+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.
+
+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 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. 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
+    
+    # ...
+  
+    def logout
+      # optionally do some local cleanup here
+      # ...
+      
+      CASClient::Frameworks::Rails::Filter.logout(self)
+    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
+
+"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
+  
+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
+
+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]
+  proxy_ticket = CASClient::Frameworks::Rails::Filter.client.request_proxy_ticket(service_uri, proxy_granting_ticket)
+  
+<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::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!
+
+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.
+
+== Testing
+
+In some cases, especially those using Cucumber or other tools that simply can't work with 
+CAS, it may be necessary to work around CAS instead.  
+
+In your test or Cucumber step definition, simply fake out CAS.
+
+  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.
+
+== 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.