Introduction

There are many ways to make use of the CAS architecture. CAS can be used as a basic local login mechanism for a stand-alone web application, but it also scale up to an enterprise-level central authentication system for all HTTP-based services, as part of an Active Directory domain.

This page describes some of the more common usage scenarios and explains how to implement them using RubyCAS-Server. When discussing the client side of the CAS equation, we often refer to RubyCAS-Client, however any full-featured CAS client can be used (this should be true for the CAS server as well).

Before looking at any of these scenarios, you should have a look at the basic configuration guide for RubyCAS-Server. The various configurations described below assume that you already have a basic RubyCAS-Server up and running and are ready to start thinking about how to integrate it with other applications and services.

Scenarios

Four main scenarios are covered:

1. Company Intranet, with several websites/web-applications, all protected by CAS, using an Active Directory authentication back-end
2. Public Website with a home page accessible anonymously and various sub-pages accessible only to authenticated members or administrators
3. Web-Based Portal, acting as a central entry point to portlets and other web-based services
4. Web Services (SOAP, XML-RPC, REST, etc.), i.e. machines talking to other machines over HTTP, using CAS for authentication

---

Scenario 1: Company Intranet

Your company or organization has several web applications, all of which should be accessible only to authenticated users. Accessing any page within these websites should automatically redirect the user to the CAS login screen. Your user accounts are stored and managed by Active Directory. This is, more or less, the canonical CAS usage scenario.

Requirements

You will need:

• RubyCAS-Server
• A basic SSL certificate for your RubyCAS-Server
• CAS client libraries for all of your client applications (RubyCAS-Client for Rails, phpCAS for PHP, etc.; see http://www.ja-sig.org/products/cas/client/index.html).

Note that it is perfectly fine for your CAS server and your CAS-protected web applications to reside on the same server machine.

RubyCAS-Server Configuration

The standard configuration described in the HowToConfigure guide more or less covers everything you need here.

The default webrick server is probably good enough, unless you expect the CAS server to receive heavy traffic (i.e. you are in a large organization, with thousands of users). If performance is an issue, have a look at the Apache + mongrel/passenger configuration discussed in Scenario 2: Public Website.

Since under this scenario our user database is stored in Active Directory, we will use the ActiveDirectoryLDAP authenticator. An example of an AD authenticator configuration is provided in the default RubyCAS-Server configuration. Uncomment this and modify it for your needs. You should create a basic user account in AD for the CAS server, and provide the username and password in the configuration. RubyCAS-Server needs this account to log in to the AD LDAP serve, in order to validate any given user credentials.

Your websites to be protected by CAS should be configured as described in the HowToConfigure guide. Be sure that the appropriate CAS filters are enacted for all content that needs to be protected. For example, in Rails this means adding the CAS filter to your base ApplicationController. In PHP, it means including the phpCAS code at the top of every page.

---

Scenario 2: Public Website with High Load and/or Optional Authentication

Your web application(s) are publicly accessible by anonymous users, but on the homepage you want to provide a Login link allowing members to authenticate with CAS. Once authenticated, users should see a customized version of the home page (for example with a "Hello, John Smith!" message). Some areas should also require CAS authentication (i.e. no anonymous access).

Optional Authentication with CAS Gatewaying

Have a look at Scenario 1 above and the HowToConfigure guide for general info on setting up the CAS server and CAS client. The only difference here has to do with how you set up the CAS client. Namely, we will use CAS' "gateway" mechanism, which makes authentication optional.

When you come to configuring the CAS client, you'll want to use the gateway option. For a Rails application, you would do something like the following:

class MyController < ApplicationController
  before_filter CASClient::Frameworks::Rails::GatewayFilter, :only => :index
  before_filter CASClient::Frameworks::Rails::Filter, :except => :index
end

Now the 'index' action will be protected by the CAS GatewayFilter. All other actions will be handled by the normal CAS Filter.

With the GatewayFilter, if the incoming user already has an open CAS session, this will be detected and the filter will set session:cas_user to the user's CAS username. If they do not yet have an open CAS session, they will still be allowed through but session:cas_user will be nil.

You'll also want to provide some sort of "Login" link that users can click on to authenticate themselves. Here's how to do it in a Rails view:

<%= link_to("Login", CASClient::Frameworks::Rails::Filter.client.login_url) unless session[:cas_user] %>

If you also want a "Logout" link:

<% if session[:cas_user] %>
  Hello, <%= session[:cas_user] %>!<br />
  <%= link_to("Logout", CASClient::Frameworks::Rails::Filter.client.logout_url) %>
<% end %>

Performance/Scalability

By default RubyCAS-Server runs using the built-in WEBrick web server. This works out of the box with minimal configuration, but since WEBrick is implemented entirely in Ruby, it's performance in high-load situation may not be up to par.

Apache + Mongrel + Reverse Proxy + Clustering

One solution is to use the Mongrel web server instead of WEBrick. This is easily done by changing the 'server' option in your RubyCAS-Server configuration file from 'webrick' to 'mongrel'. However, unlike WEBrick, Mongrel does not in itself support SSL. This is obviously a problem since CAS requires all transactions to be done over SSL.

To get around this, you will have to put your Mongrel instance behind a reverse HTTPS proxy. Using a reverse proxy also opens up the possibility of clustering and load-balancing multiple instances of RubyCAS-Server. If you're already using Apache and aren't afraid to edit some complicated .conf files, you can try configuring Apache as a reverse proxy using ''mod_proxy''. For a simpler, stand-alone solution, try Pound.

A guide for configuring Apache for reverse proxying with Mongrel is available here. For Pound, try here.

As a bonus, the reverse-proxy configuration easily allows for distributed clustering, since the proxy can redirect CAS server requests to multiple RubyCAS-Servers residing on different machines (although currently all of the RubyCAS-Server instances must share the same database).

Apache + Phusion Passenger

Another, high-performance solution is to run RubyCAS-Server under using the Phusion Passenger module for Apache. This is quickly becoming the preferred option over the Mongrel configuration described above, as it is somewhat easier to configure and deploy (although it is somewhat less powerful/customizable in terms of clustering).

For detailed instructions see DeployingUnderPhusionPassenger.

---

Scenario 3: Web Based Portal

To be written

See this post for some general ideas on how to use CAS in a portal-type deployment. The key point here is that this is best done by using proxy ticketing. Also, read the section "How to act as a CAS proxy" in the RubyCAS-Client documentation: http://rubycas-client.rubyforge.org/

---

Scenario 4: Web Services (SOAP, RPC, REST, etc.)

To be written

See this post for some general ideas on how to use CAS to authenticate web service clients.