Authentication How-To Guide: CAS Integration

One option for integrating your application with HarvardKey authentication services is use of the CAS protocol. Integration activities that you will be responsible for include redirecting to the HarvardKey for authentication, validating the ticket received from HarvardKey, and extracting attributes received in the authentication response after successful ticket validation.

The Jasig CAS community provides a number of software libraries, known as "CAS clients," to facilitate this communication. Using a CAS client usually involves installing its library and making some configuration changes in your application. For example, for a Java-based web application, you'll need to install the Java CAS client and add some XML to the application's configuration. For PHP, you'll need to install phpCAS and include a block of code at the top of restricted PHP pages. Installation and configuration information for frequently used CAS clients can be found below:

You can also find a complete list of official and unofficial CAS clients at the CAS Wiki.

The Process

Once you have installed a CAS client, the steps involved in integrating your application with the Harvard authentication system are as follows:

  1. Secure your application with SSL/TLS.
  2. Register your application with Harvard by submitting this form.
  3. Integrate your application with the CAS protocol.

Configuration URLs

The CAS client needs to be configured with several server URLs referring to the Harvard authentication system's CAS functions. In the pre-production environment, these are as follows (note that some CAS clients use casServerUrlPrefix instead of the validate URL):

In production, the URLs are as follows:

CAS Client Integration Instructions for .NET

Download the .NET CAS client binary distribution from the Jasig project site. Extract the contents of the distribution .zip file, and copy the .dll (and .pdb files for stepping into CAS client source in debugger) to either of the following locations:

  • Deployed in the /bin directory of the web application
  • Add to the .NET global assembly cache

The .NET CAS client integrates with an ASP.NET application by customizing the application's web.config file. The client is implemented as an ASP.NET IHttpModule, in this case CasAuthenticationModule. This module uses Windows Forms Authentication.

The configuration segment below shows the CAS client-specific configuration elements of the web.config file:

<?xml version="1.0"?>

<configuration>

    <!-- Register casClientConfig Section -->
    
    <configSections>
        <section name="casClientConfig" type="DotNetCasClient.Configuration.CasClientConfiguration, DotNetCasClient"/>
    </configSections>

    .....    
    .....
    .....
    
    <!-- Place a casClientConfig configuration element directly under the root configuration element. -->
    <!-- The position of the casClientConfig element in the web.config file is unimportant. -->
    
    <casClientConfig 
        casServerLoginUrl="https://www.pin1.harvard.edu/cas/login" 
        casServerUrlPrefix="https://www.pin1.harvard.edu/cas/" 
        serverName="your.app.host.xxx.harvard.edu" 
        notAuthorizedUrl="~/NotAuthorized.aspx" 
        cookiesRequiredUrl="~/CookiesRequired.aspx" 
        redirectAfterValidation="true" 
        renew="false" 
        singleSignOut="true" 
        ticketTimeTolerance="5000" 
        ticketValidatorName="Cas20" 
        serviceTicketManager="CacheServiceTicketManager" />
        
    .....    
    .....
    .....
            
    <system.web>
        
        <!-- Configure ASP.NET Forms Authentication -->
        
        <authentication mode="Forms">
            <forms 
                loginUrl="https://www.pin1.harvard.edu/cas/login" 
                timeout="30" 
                defaultUrl="~/Default.aspx" 
                cookieless="UseCookies" 
                slidingExpiration="true" 
                path="/example/" />
        </authentication>
        
        .....
        ..... 

        <!-- Register CasAuthenticationModule with the ASP.NET request/response pipeline. Register with httpModules Section: -->
        
        <httpModules>
            <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient"/>
        </httpModules>
        
    </system.web>
    
    .....    
    .....
    .....    
    
    <!-- Register CasAuthenticationModule with the ASP.NET request/response pipeline. Register with modules Section: -->
    
    <system.webServer>
        <validation validateIntegratedModeConfiguration="false"/>
        <modules>
            <remove name="DotNetCasClient"/>
            <add name="DotNetCasClient" type="DotNetCasClient.CasAuthenticationModule,DotNetCasClient"/>
        </modules>
    </system.webServer>

    .....    
    .....
    .....

</configuration>


For a detailed description and more information on using of each element, please see the sample application configuration available in the .NET CAS client source repository and the .NET CAS client project site.

Get Authenticated User Name

The CasAuthenticationModule sets the principal of the current HTTP context:

ICasPrincipal p = HttpContext.Current.User;
string uid = p.Identity.Name;