Usage Scenarios

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:

Company Intranet, with several websites/web-applications, all protected by CAS, using an Active Directory authentication back-end
Public Website with a home page accessible anonymously and various sub-pages accessible only to authenticated members or administrators
Web-Based Portal, acting as a central entry point to portlets and other web-based services
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 installation 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 + 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 installation 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 installation 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:

Rails 3 and later (using rubycas-client-rails)

class MyController < ApplicationController
  before_filter RubyCAS::GatewayFilter, :only => :index
  before_filter RubyCAS::Filter, :except => :index
end

Rails 2.x

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 + Phusion Passenger

One high-performance solution is to run RubyCAS-Server under using the Phusion Passenger module for Apache or nginx. For detailed instructions see Deploying Under Phusion Passenger.

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: https://github.com/rubycas/rubycas-client

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