Overview

Cold Fusion does not include a filter-style authentication framework like web servers (Apache, Tomcat, IIS). Therefore, in order to integrate CAS into a Cold Fusion application, some CAS code must be integrated into the application itself. This document will outline the work necessary to integrate the CAS CF code into your application.

Module Versions

The Cold Fusion client module comes in three flavors:

• The default cas_auth custom tag provides authentication using an in-memory cache of authentication credentials. This module should work for most installations.
• cas_auth_dbcache uses a database table to store the authentication credential cache. The database version of the module was developed specifically to support Cold Fusion installations that run with a cluster of application servers.

Choosing a module

The installation of both modules are similar and the installation instructions below will note the parts of the configuration that are specific to each version of the module.

Installation

1. Obtain the code
   Scroll down to the Files section, or click on the attachments tab of this page, and download the module of your choice.
2. Deploy code files
   The Cold Fusion modules are designed to be invoked as Custom Tags or CFCs. Copy the chosen module to the Custom Tags directory of your Cold Fusion server.
3. Enable Authentication
   • For a single file
     Make the call to the appropriate cas_auth custom tag at or near the start of the Cold Fusion page. Once called, the custom tag will ensure that only authenticated clients will execute code after the custom tag call. If a client cannot authenticate, they will not be able to pass the CAS login page.

   • For an entire directory / site
     When a file with the name Application.cfm exists in a directory of Cold Fusion files, it is automatically invoked before the execution of any cfm file. For example, if you browse to a file called test.cfm in a directory that contains an Application.cfm file, the application.cfm file will be processed before test.cfm is handled. This property of Cold Fusion can be used to enforce CAS authentication without the need to add a call to the custom tag on each cfm page.
     To deploy a cas-protected Application.cfm, simply create an Application.cfm file in the target directory and include a call to the appropriate cas_auth custom tag in the file.

     Application.cfm files are scoped to the directory in which they reside. If your application makes use of subdirectories, each subdirectory will need its own Application.cfm with the CAS client module call.

4. Configure the Custom Tag
   • cas_auth
     The cas_auth module stores its cache of authentication credentials in memory. This does not require any special storage configuration, but it is important to note that a server restart will require all user sessions to be re-established.

     • The Custom Tag parameters and their required settings are:

       Attribute	Description	Example
       cas_server	The base url of the CAS server	https://cas.ucdavis.edu/cas/

     • Optional Custom Tag parameters are:

       Attribute	Description	Default
       timeout	The number of hours a login session will be valid on the server	2
       cleanInterval	The number of hours to wait between cache cleanings	4

   • cas_auth_dbcache
     The cas_auth_dbcache module requires a database table to be made available to it with a specific set of columns. The table should be configured as follows:

     • The required Custom Tag parameters are:

       Attribute	Description	Example
       cas_server	The base url of the CAS server	https://cas.ucdavis.edu/cas/
       datasource	The name of the Cold Fusion datasource containing the cache table	my_datasource

     • Optional Custom Tag parameters are:

       Attribute	Description	Default
       table_name	The name of the table storing cache entries	cas_dbcache
       cookie_id_column	The name of the column containing the cookie id values	cookie_id
       user_id_column	The name of the column containing authenticated user ids	user_id
       timestamp_column	The name of the column containing the activity timestamp	time_stamp
       timeout	The number of hours a login session will be valid on the server	2
       cleanInterval	The number of hours to wait between cache cleanings	4

   • AuthCAS CFC
     • Please refer to the installation instructions included in the CFC.
5. Retrieving the authenticated user_id
   Once the cas_auth module has run, the authenticated user id can be retrieved from a variable named "AuthUser" that will be defined in both the page and request scope.

Authorization

The cas_auth custom tag modules only provide the most basic form of authorization. Anyone who can authenticate to CAS can pass the cas_auth custom tag checks. If you wish to restrict access to a smaller set of users, you will need to add your own code to inspect the AuthUser variable and make decisions on who may proceed.
Database Example:

<cfset authorized = false>
<cfif isDefined("Request.AuthUser") and Request.AuthUser neq "">
	<cfquery name="auth" datasource="#YOURDATASOURCE#">
		select	*
		from	People
		where	LoginID=<cfqueryparam cfsqltype="cf_sql_varchar" value="#Request.AuthUser#">
	</cfquery>

	<cfif auth.RecordCount GT 0>
		<cfset authorized = true>
		<!--- set request parameters for needed columns of the auth query --->
	</cfif>
</cfif>
<cfif !authorized >
	You are not authorized to access this space.
	<cfabort>
</cfif>

File Example:
Please refer to the example in the following Classlist / User File Configuration section

Classlist / User File Configuration

The UC Davis Cold Fusion Distauth module never included a Classlist / User File authorization feature, however this can be added simply. The following code will check the current authenticated user against a configurable list of auth files. You can either add this code to the auth.cfm file to protect your entire application, or can add the code to individual cfm files to protect specific pages.
Example:

<cffile action="read" file="YOURAUTHORIZATIONFILE" variable="authorizedUsers">
<cfif find(Request.AuthUser&Chr(13)&Chr(10),authorizedUsers) eq 0>
	You are not authorized to access this space.
	<cfabort>
</cfif>

Passthrough / Gateway Configuration

The Cold Fusion client does not currently support Passthrough / Gateway.

IP Restriction Configuration

The UC Davis Cold Fusion Distauth module never included an IP authorization feature, however this can be added simply. The following code will check the current request against a configurable list of IP ranges. You can either add this code to the application.cfm file to protect your entire application, or can add the code to individual cfm files to protect specific pages.
Example:

<cfif right(CGI.REMOTE_ADDR,10) neq "192.168.1.">
	You are not authorized to access this space.
	<cfabort>
</cfif>

Single Sign Out

The cas_auth modules support the CAS single sign out protocol. This means that when a user logs out of CAS by going to the CAS logout url, the CAS server will send a request to the Cold Fusion server with the id of the session that needs to be deleted. The cas_auth modules can properly interpret these requests and delete the appropriate cache entries. However, in order for CAS single sign out to work, your server must have the following properties:

1. The original url used to authenticate must be protected by SSL, (i.e. be an https:// url)
2. The server must either use a commercially signed SSL certificate or a certificate signed by the UC Davis IET Certificate Authority.
   If either of these conditions are not met, the CAS server will refuse to send the logout request. This is required to maintain the security of CAS authentication sessions.

Troubleshooting

If you encounter any issues when deploying a cas_auth module, please email websso@ucdavis.edu for support.

Files