Skip to content
This repository
Newer
Older
100644 329 lines (216 sloc) 17.826 kb
906bb769 »
2012-09-09 add code climate badge
1 {<img src="http://travis-ci.org/rubycas/rubycas-client.png" />}[http://travis-ci.org/rubycas/rubycas-client]
2 {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/rubycas/rubycas-client]
3
229959f6 »
2011-12-19 Add Travis Status image to README [ci skip]
4 = RubyCAS-Client
f7819666 »
2008-01-10 Initial import.
5
6adb8991 »
2011-09-19 merge in changes from vibes and bump version to 2.3.0.rc1
6 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>
0f21e6a1 »
2009-09-30 re-licensed under MIT
7 Copyright:: Portions contributed by Matt Zukowski are copyright (c) 2009 Urbacon Ltd.
fda7fe78 »
2011-06-21 fix typos in README
8 Portions contributed by Matt Campbell, Rich Yarger and Rahul Joshi are copyright (c) 2011 Vibes Media LLC.
0f21e6a1 »
2009-09-30 re-licensed under MIT
9 Other portions are copyright of their respective authors.
10 License:: MIT License
6adb8991 »
2011-09-19 merge in changes from vibes and bump version to 2.3.0.rc1
11 Websites:: http://github.com/rubycas/rubycas-client
12 http://github.com/rubycas/rubycas-client/wiki
13 http://rubydoc.info/github/rubycas/rubycas-client/master/frames
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
14
15 === RubyCAS-Client is a Ruby client library for Yale's Central Authentication Service (CAS) protocol.
16
17 CAS provides a secure single sign on solution for web-based applications. The user logs in to your
18 organization's CAS server, and is automatically authenticated for all other CAS-enabled applications.
19
20 For general information about the open CAS protocol, please have a look at http://www.ja-sig.org/products/cas.
21
22 If your organization does not already have a CAS server, you may be interested in RubyCAS-Client's sister project,
23 RubyCAS-Server[http://code.google.com/p/rubycas-server/].
24
e46bdedd »
2009-02-25 added info about installing as a plugin from git, where to find RDocs…
25 The RubyCAS-Client package includes adapters for Rails and Merb, although the client library itself can be
26 adapted for other frameworks (for example an implementation for Camping is available via the Picnic[http://github.com/zuk/picnic/tree/master]
27 library).
28
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
29
30 == Getting help and reporting problems
31
32 If you need help, try posting to the RubyCAS discussion group at http://groups.google.com/group/rubycas-server.
33
34 To report problems, please use the Google Code issue tracker at http://code.google.com/p/rubycas-client/issues/list.
35
e46bdedd »
2009-02-25 added info about installing as a plugin from git, where to find RDocs…
36 API documentation (i.e. the RDocs) are available at http://rubycas-client.rubyforge.org
37
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
38
39 == Installation
40
27d51487 »
2011-01-27 fixed rdoc format typo
41 <b>NOTE:</b> For compatibility with Rails 3 have a look at https://github.com/zuk/rubycas-client-rails
4bdb7d0c »
2011-01-27 added note about rubycas-client-rails
42
724cfe2a »
2011-09-01 Rails.logger needs to be prefixed with ::
43 The current version of RubyCAS-Client should work with Rails 2.3.6 and up. For compatibility with
44 older Rails try using an older version of the client.
45
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
46 You can download the latest version of RubyCAS-Client from the project's rubyforge page at
47 http://rubyforge.org/projects/rubycas-client.
48
e46bdedd »
2009-02-25 added info about installing as a plugin from git, where to find RDocs…
49 However, if you're using Rails, it's easier to install the CAS client as a plugin:
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
50
51 cd <your rails app>
71bac301 »
2010-07-15
52 ./script/plugin install git://github.com/gunark/rubycas-client.git
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
53
54 Alternatively, the library is also installable as a RubyGem[http://rubygems.org]:
55
56 gem install rubycas-client
57
58 If your Rails application is under Subversion control, you can also install the plugin as an svn:external, ensuring that
59 you always have the latest bleeding-edge version of RubyCAS-Client:
60
71bac301 »
2010-07-15
61 ./script/plugin install -x http://svn.github.com/gunark/rubycas-client.git
e46bdedd »
2009-02-25 added info about installing as a plugin from git, where to find RDocs…
62
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
63
64 == Usage Examples
65
f634e29e »
2008-11-20 link to merb and rails examples
66 If you'd rather jump right in, have a look at the example Rails and Merb applications pre-configured for CAS
67 authentication:
68
69 http://github.com/gunark/rubycas-client/tree/master/examples
70
71
72 Otherwise, continue reading for a step-by-step guide for integrating RubyCAS-Client with Rails:
73
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
74
75 ==== Using RubyCAS-Client in Rails controllers
76
77 <i>Note that from this point on we are assuming that you have a working CAS server up and running!</i>
78
4d468233 »
2008-03-06 documentation improvements based on recent user feedback
79 After installing RubyCAS-Client as a plugin (see above), add the following to your app's <tt>config/environment.rb</tt>
80 (make sure that you put it at the bottom of the file, *after* the Rails Initializer):
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
81
82 CASClient::Frameworks::Rails::Filter.configure(
83 :cas_base_url => "https://cas.example.foo/"
84 )
85
86 (Change the <tt>:cas_base_url</tt> value to your CAS server's base URL; also note that many CAS servers are configured
87 with a base URL that looks more like "https://cas.example.foo/cas".)
88
89 Then, in your <tt>app/controllers/application.rb</tt> (or in whichever controller you want to add the CAS filter for):
90
91 before_filter CASClient::Frameworks::Rails::Filter
92
93 That's it. You should now find that you are redirected to your CAS login page whenever you try to access any action
94 in your protected controller. You can of course qualify the <tt>before_filter</tt> as you would with any other ActionController
95 filter. For example:
96
97 before_filter CASClient::Frameworks::Rails::Filter, :except => [ :unprotected_action, :another_unprotected_action ]
98
99 <b>Once the user has been authenticated, their authenticated username is available under <tt>session[:cas_user]</tt>,</b>
100 If you want to do something with this username (for example load a user record from the database), you can append another
101 filter method that checks for this value and does whatever you need it to do.
102
f4e079a0 »
2008-04-17 moved note about 'requires'
103 <b>Note:</b> If Rails complains about missing constants, try adding this before the CASClient configuration:
104
105 require 'casclient'
106 require 'casclient/frameworks/rails/filter'
107
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
108
109 ==== A more complicated example
110
111 Here is a more complicated configuration showing most of the configuration options along with their default values
112 (this does not show proxy options, which are covered in the next section):
113
114 # enable detailed CAS logging
724cfe2a »
2011-09-01 Rails.logger needs to be prefixed with ::
115 cas_logger = CASClient::Logger.new(::Rails.root+'/log/cas.log')
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
116 cas_logger.level = Logger::DEBUG
117
118 CASClient::Frameworks::Rails::Filter.configure(
119 :cas_base_url => "https://cas.example.foo/",
120 :login_url => "https://cas.example.foo/login",
121 :logout_url => "https://cas.example.foo/logout",
122 :validate_url => "https://cas.example.foo/proxyValidate",
0d40af75 »
2008-03-12 fixed misnamed config keys in documentation (thanks to Emrys Ingersol…
123 :username_session_key => :cas_user,
2a8ff836 »
2009-03-09 fixed missing comma in example code
124 :extra_attributes_session_key => :cas_extra_attributes,
669206e0 »
2008-02-27 the Rails filter no longer by default redirects to CAS on every request
125 :logger => cas_logger,
075ef81c »
2009-08-18 added note about having to add :enable_single_sign_out => true to the…
126 :enable_single_sign_out => true
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
127 )
128
4d468233 »
2008-03-06 documentation improvements based on recent user feedback
129 Note that normally it is not necessary to specify <tt>:login_url</tt>, <tt>:logout_url</tt>, and <tt>:validate_url</tt>.
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
130 These values are automatically set to standard CAS defaults based on the given <tt>:cas_base_url</tt>.
131
0d40af75 »
2008-03-12 fixed misnamed config keys in documentation (thanks to Emrys Ingersol…
132 The <tt>:username_session_key</tt> value determines the key under which you can find the CAS username in the Rails session hash.
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
133
134 Any additional info that the CAS server might have supplied about the user during authentication will be found under the
0d40af75 »
2008-03-12 fixed misnamed config keys in documentation (thanks to Emrys Ingersol…
135 <tt>:extra_attributes_session_key</tt> value in the Rails session hash (i.e. given the above configuration, you would find this
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
136 info under <tt>session[:cas_extra_attributes]</tt>).
137
138 An arbitrary Logger instance can be given as the :logger parameter. In the example above we log all CAS activity to a
139 <tt>log/cas.log</tt> file in your Rails app's directory.
140
669206e0 »
2008-02-27 the Rails filter no longer by default redirects to CAS on every request
141 ==== Re-authenticating on every request (i.e. the "single sign-out problem")
142
143 By default, the Rails filter will only authenticate with the CAS server when no session[:cas_user] value exists. Once the user
144 has been authenticated, no further CAS forwarding is done until the user's session is wiped. This saves you
145 the trouble of having to do this check yourself (since in most cases it is not advisable to go through the CAS server
146 on every request -- this is slow and would potentially lead to problems, for example for AJAX requests). However,
147 the disadvantage is that the filter no longer checks to make sure that the user's CAS session is still actually open.
148 In other words it is possible for the user's authentication session to be closed on the CAS server without the
149 client application knowing about it.
150
8f755923 »
2008-11-20 added login_url method to Rails filter for obtaining the current logi…
151 To address this, RubyCAS-Client now supports the new "Single Sign-Out" functionality in CAS 3.1, allowing the server to
152 notify the client application that the CAS session is closed. The client will automatically intercept Single Sign-Out
153 requsts from the CAS server, but in order for this to work you must configure your Rails application as follows:
154
155 1. The Rails session store must be set to ActiveRecord: <tt>config.action_controller.session_store = :active_record_store</tt>
927c623e »
2011-02-14 changed RAILS_ROOT to Rails.root
156 2. The server must be able to read and write to Rails.root/tmp/sessions. If you are in a clustered environment,
8f755923 »
2008-11-20 added login_url method to Rails filter for obtaining the current logi…
157 the contents of this directory must be shared between all server instances.
158 3. Cross-site request forgery protection must be disabled. In your <tt>application.rb</tt>: <tt>self.allow_forgery_protection = false</tt>.
159 (Or rather you may want to disable forgery protection only for actions that are behind the CAS filter.)
075ef81c »
2009-08-18 added note about having to add :enable_single_sign_out => true to the…
160 4. Finally, you must add <tt>:enable_single_sign_out => true</tt> to your CAS client config (a similar option must be
161 enabled on the CAS server, if you're using RubyCAS-Server).
8f755923 »
2008-11-20 added login_url method to Rails filter for obtaining the current logi…
162
163 The best way to debug single-sign out functionality is to configure your CAS client with logging (see above) and then watch the
164 log to ensure that single-sign out requests from the server are being processed correctly.
165
669206e0 »
2008-02-27 the Rails filter no longer by default redirects to CAS on every request
166
8f755923 »
2008-11-20 added login_url method to Rails filter for obtaining the current logi…
167 Alternatively, it is possible to disable authentication persistence in the client by setting the <tt>:authenticate_on_every_request</tt>
168 configuration option to true as, in the example in the previous section. However, this is not recommended as it will almost
169 certainly have a deleterious impact on performance and can interfere with certain HTTP transactions (AJAX requests, for example).
669206e0 »
2008-02-27 the Rails filter no longer by default redirects to CAS on every request
170
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
171
172 ==== Defining a 'logout' action
173
16685c8d »
2008-03-13 implemented new logout method for Rails filter to simplify implementi…
174 Your Rails application's controller(s) will probably have some sort of logout function. Here you can do any necessary local
175 cleanup, and then call <tt>CASClient::Frameworks::Rails::Filter.logout(controller)</tt>. For example:
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
176
4d468233 »
2008-03-06 documentation improvements based on recent user feedback
177 class ApplicationController < ActionController::Base
178
179 # ...
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
180
4d468233 »
2008-03-06 documentation improvements based on recent user feedback
181 def logout
16685c8d »
2008-03-13 implemented new logout method for Rails filter to simplify implementi…
182 # optionally do some local cleanup here
183 # ...
8366bfac »
2008-04-01 minor formatting adjustment
184
16685c8d »
2008-03-13 implemented new logout method for Rails filter to simplify implementi…
185 CASClient::Frameworks::Rails::Filter.logout(self)
4d468233 »
2008-03-06 documentation improvements based on recent user feedback
186 end
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
187 end
188
16685c8d »
2008-03-13 implemented new logout method for Rails filter to simplify implementi…
189 By default, the logout method will clear the local Rails session, do some local CAS cleanup, and redirect to the CAS
190 logout page. Additionally, the <tt>request.referer</tt> value from the <tt>controller</tt> instance is passed to the
191 CAS server as a 'destination' parameter. This allows RubyCAS server to provide a follow-up login page allowing
192 the user to log back in to the service they just logged out from using a different username and password. Other
193 CAS server implemenations may use this 'destination' parameter in different ways.
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
194
195 ==== Gatewayed (i.e. optional) authentication
196
197 "Gatewaying" essentially allows for optional CAS authentication. Users who already have a pre-existing CAS SSO session
198 will be automatically authenticated for the gatewayed service, while those who do not will be allowed to access the service
199 without authentication. This is useful for example when you want to show some additional private content on a homepage to
200 authenticated users, but also want anonymous users to be able to access the page without first logging in.
201
202 To allow users to access a page without authenticatin, simply use <tt>CASClient::Frameworks::Rails::GatewayFilter</tt>
203 in place of <tt>CASClient::Frameworks::Rails::Filter</tt> in your controller. For example, you may want to require
204 CAS authentication for all actions in a controller except the index action:
205
206 class ExampleController < ApplicationController
207 before_filter CASClient::Frameworks::Rails::GatewayFilter, :only => :index
208 before_filter CASClient::Frameworks::Rails::Filter, :except => :index
209
210 # ...
211 end
212
5a077488 »
2008-11-20 info on how to provide 'Login' link in gatewayed actions
213 To provide a login URL for unauthenticated users:
214
215 <%= link_to("Login", CASClient::Frameworks::Rails::Filter.login_url(controller)) %>
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
216
217 ==== How to act as a CAS proxy
218
219 CAS 2.0 has a built-in mechanism that allows a CAS-authenticated application to pass on its authentication to other applications.
220 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
221 various other sites that run independently of the portal system (but are always accessed via the portal). The exact mechanism
222 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
223 is available at http://www.ja-sig.org/wiki/display/CAS/Proxy+CAS+Walkthrough.
224
225 RubyCAS-Client fully supports proxying, so a CAS-protected Rails application can act as a CAS proxy.
226
227 Additionally, RubyCAS-Client comes with a controller that can act as a CAS proxy callback receiver. This is necessary because
228 when your application requests to act as a CAS proxy, the CAS server must contact your application to deposit the proxy-granting-ticket
229 (PGT). Note that in this case the CAS server CONTACTS YOU, rather than you contacting the CAS server (as in all other CAS operations).
230
231 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,
232 all you need to do is this:
233
234 In your <tt>config/environment.rb</tt>:
235
236 # enable detailed CAS logging for easier troubleshooting
724cfe2a »
2011-09-01 Rails.logger needs to be prefixed with ::
237 cas_logger = CASClient::Logger.new(::Rails.root+'/log/cas.log')
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
238 cas_logger.level = Logger::DEBUG
239
240 CASClient::Frameworks::Rails::Filter.configure(
241 :cas_base_url => "https://cas.example.foo/",
242 :proxy_callback_url => "https://cas-proxy-callback.example.foo/cas_proxy_callback/receive_pgt",
243 :logger => cas_logger
244 )
245
246 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
247 CasProxyCallbackController. This should work as-is with the standard Rails routes setup, but if you have disabled the default
248 route, you should add the following:
249
250 map.cas_proxy_callback 'cas_proxy_callback/:action', :controller => 'cas_proxy_callback'
251
252 Now here's a big giant caveat: <b>your CAS callback application and your CAS proxy application must run on separate Rails servers</b>.
253 In other words, if you want a Rails app to act as a CAS ticket-granting proxy, the cas_proxy_callback controller
254 must run on a different server. This is because Rails does not properly support handling of concurrent requests. The CAS proxy mechanism
255 acts in such a way that if your proxy application and your callback controller were on the same server
256 you would end up with a deadlock (the CAS server would be waiting for its callback to be accepted by your Rails server,
257 but your Rails server wouldn't respond to the CAS server's callback until the CAS server responded back first).
258
259 The simplest workaround is this:
260
b9c3ec52 »
2011-06-11 make single sign out and proxy ticket storage modular and clean up th…
261 Run rails using a server that handles multiple concurrent requests. In development, you can use Phusion Passenger Standalone,
262 POW (http://pow.cx/), unicorn and many others. In production, I imagine you already support multiple concurrent requests.
263
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
264 That's it. The proxy_callback_controller doesn't require any additional configuration. It doesn't access the database
265 or anything of that sort.
266
267 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
268 to authenticate another application:
269
270 service_uri = "http://some-other-application.example.foo"
271 proxy_granting_ticket = session[:cas_pgt]
008ac4aa »
2009-07-17 fixed errors in proxy docs, as pointed out by Bryan Larsen
272 proxy_ticket = CASClient::Frameworks::Rails::Filter.client.request_proxy_ticket(service_uri, proxy_granting_ticket)
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
273
008ac4aa »
2009-07-17 fixed errors in proxy docs, as pointed out by Bryan Larsen
274 <tt>proxy_ticket</tt> should now contain a valid proxy ticket. You can use it to authenticate other services by sending it together with
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
275 the service URI as parameters to your target application:
276
008ac4aa »
2009-07-17 fixed errors in proxy docs, as pointed out by Bryan Larsen
277 http://some-other-application.example.foo?service=#{CGI::escape(proxy_ticket.service)}&ticket=#{proxy_ticket.ticket}
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
278
279 This is of course assuming that http://some-other-application.example.foo is also protected by the CAS filter.
280 Note that you should always URI-encode your service parameter inside URIs!
281
282 Note that #request_proxy_ticket returns a CASClient::ProxyTicket object, which is why we need to call #ticket on it
283 to retrieve the actual service ticket string.
284
285 ===== Additional proxying notes and caveats
286
287 <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
288 the bundled cas_proxy_callback controller, you will have to host your application on an https-enabled server. This can be a bit
289 tricky with Rails. WEBrick's SSL support is difficult to configure, and Mongrel doesn't support SSL at all. One workaround is to
290 use a reverse proxy like Pound[http://www.apsis.ch/pound/], which will accept https connections and locally re-route them
291 to your Rails application. Also, note that <i>self-signed SSL certificates likely won't work</i>. You will probably need to use
292 a real certificate purchased from a trusted CA authority (there are ways around this, but good luck :)
293
294
295 == SSL Support
296
297 Make sure you have the Ruby OpenSSL library installed. Otherwise you may get errors like:
298
299 no such file to load -- net/https
300
301 To install the library on an Debian/Ubuntu system:
302
303 sudo apt-get install libopenssl-ruby
304
305 For other platforms you'll have to figure it out yourself.
306
1eb10cc2 »
2009-05-27 added ability to fake out CAS authenticatio
307 == Testing
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
308
1eb10cc2 »
2009-05-27 added ability to fake out CAS authenticatio
309 In some cases, especially those using Cucumber or other tools that simply can't work with
310 CAS, it may be necessary to work around CAS instead.
311
312 In your test or Cucumber step definition, simply fake out CAS.
313
314 CASClient::Frameworks::Rails::Filter.fake("homer")
315
316 This functionality was present in the original version of this plugin.
317 The value of the username is stored in session[:cas_user] (or the user specified field) and session[:casfilteruser] for backwards-compatibility.
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
318
b9c3ec52 »
2011-06-11 make single sign out and proxy ticket storage modular and clean up th…
319 If you need to fake out extra attributes, you can do so like this:
320
321 CASClient::Frameworks::Rails::Filter.fake("homer", {:role => "user", :email => "homer@test.foo"})
322
323 And the extra attributes will get put in the proper place in the session.
324
acc30043 »
2008-02-12 added README documentation and mising LICENSE file
325 == License
326
0f21e6a1 »
2009-09-30 re-licensed under MIT
327 RubyCAS-Client is licensed for use under the terms of the MIT License.
328 See the LICENSE.txt file bundled with the official RubyCAS-Client distribution for details.
Something went wrong with that request. Please try again.