Project Example with the FCS CAS Authentication

1. Introduction

CAS (Central Authentication Service) is a service used to authenticate users in a centralized way, which can be used by external web sites. The project FCS CAS provides a CAS service at the Dalhousie University for users that have CSID (Faculty of Computer Science ID) authentication, which generally includes all students, staff, and faculty in the Faculty of Computer Science. The service is intended to be used for various client projects, including web applications built by faculty and students that use CSID authentication. The CAS service provides this service in a safe and secure way, so that possible vulnerabilities in the client projects do not compromise user's CSID and password. However, even though the project developers and maintainers are making the best effort to make the service secure, we cannot make any guarantees that the data will not be compromised.

1.1 Licence and Warranty

The best effort is made by project developers and maintainers to make the service secure, but they do no make any warranties. THE SERVICE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.

The software used to run the service is not completely open-sourced at the moment due to continued clean-up and code proof-reading, but our plan is to make it completely open-source in the future and some parts are already in the open-source domain.

2. Protocol Description and Usage Example

The service is based on the CGI::AuthRegister module and a relatively simple protocol described by this module. We describe an overview of the protocol in this section.

In the protocol description, we distinguish three actors in the protocol: server, client, and user.
Server is the CAS server, or CAS service, which is used as the authentication service.
Client is a client application that uses the service. The application is normally implemented as a web application.
User is a user of the client application, who has a CSID and can be identified at the server using a password.

The process of user authentication for the client via server can be described in the following steps:
Step 1: Session Check
Step 2: CAS Forward
Step 3: Authentication
Step 4: Proof Response
Step 5: Verification

Step 1: Session Check: is done by the client each time the user accesses the client application. The client application most likely has some form of maintaining session information, probably using a cookie or hidden variables. The application should require authentication only if there is no existing session or if session timed out. It the most simple case, we could always require authentication for one action. The client should proceed to Step 2 only if there is no valid session and the client requires user to authenticate.

Step 2: CAS Forward: If user authentication is required, we should forward the user to the CAS server while providing the link back to the client application. The CAS forward is done via a link, which can be attached to a Login anchor or button. Let us use an example with the actual FCS CAS server, which is located at the address https://cas.cs.dal.ca. Let us assume that our client application is at the URL https://MY.SITE/APP.CGI. In other to authenticate the user, the client should provide the following link for authentication:
https://cas.cs.dal.ca/?r=https://MY.SITE/APP.CGI
The part that starts with ?r=https://... is the redirection link back to your site. In the standard terminology, this link is called redirect URI, and we refer to it also as the parameter r, or redirect_uri. The parameter r contains the link for the CGI script that will receive back the authentication proof from the user that was received from the CAS server.

As another example we can use this page with the URL https://cas.cs.dal.ca/example/client-fcs.cgi. The CAS forward link in this case is:
https://cas.cs.dal.ca/?r=https://cas.cs.dal.ca/example/client-fcs.cgi
If you have a CSID, you can click on the link above. After authentication, you will come back to this page and the result of the authentication should be shown in the space below this line:

Step 3: Authentication: The authentication is performed at the CAS site, and if successful, the client will be redirected back with a link to your CGI script provided as the r parameter in Step 2. This redirection is part of Step 4.

Step 4: Proof Response: This step will happen when the user has been successfully authenticated, and by clicking a "Proceed" link, the user will invoke the client's CGI script provided as the r parameter, with two data items passed: CSID (`username') and a secret token (`stoken').

The redirect URI that was provided should point to a CGI program (e.g., written in Perl, PHP, Python, or some other language), that can accept these data items using the POST method. After that, the CGI program should verify the items by contacting directly the CAS service in the next step.

Step 5: Verification: The client application needs the verify the username and the secret token stoken in this step by sending a POST request to the CAS server with the following parameters

• rt with the value verify (rt stands for `request type'),
• username with the provided username, and
• stoken with the provided secret token (stoken).

3. An Implementation Approach

We describe here an implementation approach of connecting a client application with the CAS server. We will follow the protocol steps:
Step 1: Session Check
Step 2: CAS Forward
Step 3: Authentication
Step 4: Proof Response
Step 5: Verification

3.1 Perl Implementation

A Perl CGI program that needs to use the CAS service could use the module CGI::AuthRegister, available through CPAN. This is an example of how it can be used:

#!/usr/bin/perl

use CGI::AuthRegister;
$CGI::AuthRegister::SiteId = 'My_site';
$CGI::AuthRegister::SiteName = 'My Site';

&require_https;  # Require HTTPS connection

# Require CAS login
my $status =
  &require_login(-cas=>"https://cas.cs.dal.ca/",
		 -return_status=>1);
#status: logged out, 1, not logged in, login failed

my $note = "You can use the link below to login using FCS CSID:".
 "<br><code>\n".
 "<a href=\"https://cas.cs.dal.ca/?r=https://MY.SITE/$ENV{SCRIPT_NAME}\"\n".
           >https://cas.cs.dal.ca/?r=https://MY.SITE/$ENV{SCRIPT_NAME}".
 "</a></code>\n";

if ($status eq 'logged out') {
   # User has just logged out
   $note = "You have logged out. $note";
   }
elsif ($status eq 'not logged in') {
   # User is not logged in
}
elsif ($status eq 'login failed') {
   # User's login attempt failed
   $note = "Login failed. $note";
}
elsif ($status == 1) {
   # User is logged in successfully
   my $csid = $CGI::AuthRegister::UserId;
   $note = "You are logged in as CSID: $csid<br>\n".
   "You can logout using the link: ".
   "<a href=\"$ENV{SCRIPT_NAME}?logout\">Logout</a>\n".
   "<br>To reload this page without data, click here:\n".
   "<a href=\"$ENV{SCRIPT_NAME}\">Reload</a>\n";
}

print "<html><body><p><b>Note:<\/b> $note\n";

4. Contact and the Team

This service is in a pilot phase. If your plan to use it or you are using it, please send an email to vlado@dnlp.ca (Vlado Keselj). Send any questions or comments to this email as well.

People involved in the project: Vlado Keselj, Jeff Allen, Manjula Devaraj, and Raghav Sampangi.