Table of Contents

• Overview
• Before You Register Your Application URL
• Register Your Application URL
• Web Login process
  • Conventions & Definitions
  • CAS URIs
  • Login Securely
  • Ticket Validation (CAS protocol 1.0, AuthN, simple text response)
  • Ticket Validation (CAS protocol 2.0, AuthN, XML response)
  • Ticket Validation (CAS protocol 3.0, AuthN with attributes, SAML response)
  • Logging Out
• Access Control
• Sample Clients
  • Java CAS client
  • UH CAS Demo in Java
  • phpCAS
  • cURL (no attributes requested)
  • CAS Authentication with Spring Security
• Frequently Asked Questions
• Troubleshooting
• Technical Support

...

Overview

UH Login (CAS) is available for University of Hawaiʻi (UH) Web site developers to authenticate users with their UH username and password. It alleviates the problem of having to develop a user authentication system as part of the Web-enabled application (web application) development. It also provides increased security for users by not allowing Web applications to handle their passwords (often using insecure means such as sending it in the clear or unnecessarily storing it).

...

...

...

Before You Register Your Application URL …

Before you register your application URL there are a few details to first consider:

1. Will authentication include the release of attributes to your application?
   1. If yes, UH Data Governance guidelines apply.  For each unique application you must submit a separate request.  What that means is that you cannot register a single URL and host multiple applications under it.  
2. Is your application hosted on a non-UH server?
   1. If yes, your request may be subject to the UH Data Sharing Request process. Please send an inquiry to datagov@hawaii.edu or call call (808) 956-7487.

...

Register Your Application URL

For security purposes, application URLs must be registered in order to prevent unauthorized use.

• Registration Form

...

...

Web Login process

Web applications registered for UH Login use a link or redirect from their main page to the secure HTML CAS form.

To Authenticate Users

• A user enters their UH username and password on the UH Login page.
• After submission, the Web Login Service redirects the user back to your web application along with a service ticket provided by the Web Login Service.
• Your web application then requests that UH Login validate this ticket.
  • If the user supplied the correct authentication credentials (username/password), UH Login will return a success response to your web application.
  • Otherwise, a failure response is returned.

...

...

Conventions & Definitions

• "Client" refers to the end user and/or the web browser.
• "Server" refers to UH Login (CAS).
• "Service" refers to the application the client is trying to access (i.e., your application).
  • "TARGET" for samlValidate
• <LF> is a bare line feed (ASCII value 0x0a).

...

CAS URIs

URIs for CAS use the hostname followed by /cas and ended with the desired service. In the examples that follow, substitute the following for $WEBLOGIN-HOST for the appropriate environment.

• Production
  • https://authn.hawaii.edu/
• Test
  • https://cas-test.its.hawaii.edu/ (testing does not require registration of your URL)
• Future Test
  • https://cas-future-test.its.hawaii.edu/
• Deprecated Production
  • cas-deprecated.its.hawaii.edu

...

...

Log in Securely

...

/login

To have a user login securely put a link on your main page to the "login securely" URL with a request parameter named service and having a value that is the Service URL (i.e., the URL of the main page or a page that will be able to handle an HTTP request with a parameter). This link should be labeled with something like "Login Securely" to establish in your user's mind that the password will not be seen by your application and is handled securely. See the next section on ticket validation for information about how your application finds out the username.

...

...

Ticket Validation (

...

CAS protocol 1.0

...

, AuthN, simple text response)

/validate

This section describes how your Web application finds out the username of a user that has successfully logged in.

...

• Here's an example of the URL used by UH Login to redirect the request back to the Web site (with a sample ticket):

  No Format
  https://myserver/myapp?ticket=ST-3-8tkkJbPThesE1cZjVVtc

  
  

• The server-side processing of your Service URL must validate the extracted authentication token by sending an HTTP GET request with the following parameters:

  No Format
  service=<Service URL> ticket=<service ticket>

  
  

• Using your URL with ticket, send your request to UH Login:

  No Format
  https://$WEBLOGIN-HOST/cas/validate?service=https://myserver/myapp&ticket=ST-95-a1kjb6g4Tcdeh17vfy6g

  
  

  Info
  Append &renew=true to disallow SSO.

  
  

• After validating the service ticket, UH Login will return a text document indicating success or failure.

  Code Block
  xml xml title On ticket validation success:
  yes<LF> username<LF>

  
  

  Code Block
  xml xml title On ticket validation failure:
  no<LF> <LF>

...

Ticket Validation (

...

CAS protocol 2.0, AuthN, XML response)

...

/serviceValidate

This section describes how your Web application finds out the username of a user that has successfully logged in.

...

• Here's an example of the URL used by UH Login to redirect the request back to the Web site (with a sample ticket):

  No Format
  https://myserver.example.edu/myapp?ticket=ST-7655-K6dyN9ystYwdOZynSnak-cas

  
  

• The server-side processing of your Service URL must validate the extracted authentication token by sending an HTTP GET request with the following parameters:

  No Format
  service=<Service URL> ticket=<service ticket>

  
  

• Using your URL with ticket, send your request to UH Login:

  No Format
  https://$WEBLOGIN-HOST/cas/serviceValidate?service=https://myserver.example.edu/myapp&ticket=ST-7655-K6dyN9ystYwdOZynSnak-cas

  
  

  Info
  Append &renew=true to disallow SSO.

  
  

• After validating the service ticket, UH Login will return an XML-fragment indicating success or failure.

  Code Block
  xml xml title On ticket validation success:
  <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'> <cas:authenticationSuccess> <cas:user>joebogus</cas:user> </cas:authenticationSuccess> </cas:serviceResponse>

  
  

  Code Block
  xml xml title On ticket validation failure:
  <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'> <cas:authenticationFailure code="INVALID_TICKET"> Ticket ST-7655-K6dyN9ysFOOdOZynSnak-cas not recognized </cas:authenticationFailure> </cas:serviceResponse>

  
  

  Info
  title Error codes
  The following values may be used as the "code" attribute of authentication failure responses. INVALID_REQUEST not all of the required request parameters were present INVALID_TICKET the ticket provided was not valid, or the ticket did not come from an initial login and "renew" was set on validation. The body of the <cas:authenticationFailure> block of the XML response SHOULD describe the exact details. INVALID_SERVICE the ticket provided was valid, but the service specified did not match the service associated with the ticket. CAS MUST invalidate the ticket and disallow future validation of that same ticket. INTERNAL_ERROR an internal error occurred during ticket validation

...

...

...

Ticket Validation (

...

CAS protocol 3.0, AuthN with attributes, SAML response):

/samlValidate

This section describes how your Web application determines the username and possibly additional attributes for a user that has successfully logged in.

...

...

Logging Out (SLO)

...

/logout

Web applications that login a user must handle their own session state and should offer the user the ability to log out of their session. Without the logout service provided by CAS, a user returning to the web application's Service URL, will be automatically logged back in because of the ticket-granting cookie also provided by CAS stored by the client. This is a single sign-on feature across web applications that use UH Login. There are two basic ways to "log out"; logout from application and UH Login single sign-on or logout from application and force re-authentication to UH Login.

...

• url (DISABLED)

  Note

  Although Aperero's CAS protocol documentation describes the use the the url parameter, the Aperero developers have disabled it in recent versions of CAS to prevent potential abuse. Their explanation of the situation may be found in this thread from the cas-users mailing list. The url parameter defined in the former CAS 2.0 specification is not a valid parameter in CAS 3.0 anymore. CAS Servers MUST ignore given url parameters.

  
  

Examples

• To logout a user and prevent her from automatically logging back into a Web application, the Web application can forward the user to the Logout URL of UH Login. That URL will destroy the ticket-granting cookie that enables the single sign-on feature and gives the user a page that informs them that they have logged out of UH Login.

  No Format
  https://$WEBLOGIN-HOST/cas/logout

  
  

• To logout a user and prevent her from automatically logging back into a Web application, the Web application can forward the user to the Logout URL of UH Login. That URL will destroy the ticket-granting cookie that enables the single sign-on feature and redirect the user to the URL identified by the service parameter.

  No Format
  https://$WEBLOGIN-HOST/cas/logout?service=https://myserver/myapp

  
  

  Info
  The URL provided by the service parameter must be registered to use UH Login.

  
  

...

Access Control

It is every developer's responsibility to perform any necessary access control (authorization, AuthZ) after a user has logged on to their Web site. This is may be done by using information as attributes for the user. The affiliation, campus, or campus affiliation data should be enough to filter out unauthorized users. Alternatively, you choose explicitly may allow or disallow by username. Ultimately, it is up to each developer to determine how to implement access controls based on available information.

...

Sample Clients

• Apereo documentation on CAS clients
• Jasig CAS Client for Java - Spring Boot Support

...

Java client

Aperero provides an example of SAML 1.1 Ticket Validation Filter.

...

...

UH CAS Demo in Java

UH ITS' own Frank Duckart wrote the following CAS demo using Java and Servlets:

...

Probably not a great idea, but it is also possible to create a CAS client login using JSP only:
Project Repo:  https://github.com/fduckart/uh-jsp-casdemo

...

...

phpCAS client

The phpCAS module is a PHP library that interacts with CAS and allows you to work with user and authentication objects. It also allows for attribute release. The latest phpCAS version may be obtained from the phpCAS Github page. Documentation for phpCAS can be found here.

...

Array ( [0] => yes [1] => jschmidt [2] => )

...

cURL client (no attributes requested)

Below is a PHP script using cURL to establish a connection with the CAS server.

...

<?php
# Test CAS URLs
$CAS_LOGIN_URI      = "https://$WEBLOGIN-HOST/cas/login";
$CAS_VALIDATE_URI   = "https://$WEBLOGIN-HOST/cas/validate";
$CAS_LOGOUT_URI     = "https://$WEBLOGIN-HOST/cas/logout";

$single_signon = TRUE;

# Here is where we check if the user has authenticated.  If we cannot find a ticket,
# redirect the user to the CAS login page.
if ( ! isset($_GET["ticket"]) )
{
    $location = "Location: ".$CAS_LOGIN_URI."?service=".urlencode($_SERVER["SCRIPT_URI"]);

    # If we haven't enabled single sign-on, the user has to renew each time.
    if ( ! $single_signon )
    {
        $location = $location."&renew=true";
    }

    header($location);
    exit();
}
else
{
    # Initialize our CURL session with the CAS validation URL.  Supply the server script and ticket.
    $validate_string    = $CAS_VALIDATE_URI."?service=".urlencode($_SERVER["SCRIPT_URI"])."&ticket=".$_GET["ticket"];

    $ch = curl_init($validate_string);

    # set the option to return the results
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

    $cas_return = explode("\n", curl_exec($ch));

    # This dumps out the return values from our cURL request.  Later we check whether or not the user successfully authenticated.
    echo "CAS return via cURL: ";
    print_r($cas_return);
    echo "<br />";

    if ( $cas_return[0] == "yes" )
    {
        echo "User successfully authenticated via CAS<br />";
        for ( $i=0; $i<count($cas_return); $i++ )
        {
            echo "Cas Return #$i: ".$cas_return[$i]."<br />";
        }
    }
    else
    {
        echo "User not validated<br />";
    }
}

?>

...

...

Spring Security CAS Authentication

...

• http://docs.spring.io/spring-security/site/docs/4.0.4.RELEASE/reference/htmlsingle/#cas

...

Frequently Asked Questions (FAQ)

Why does my site automatically login a returning user after they logout of their session with my site?

...

A future enhancement could make single sign-on an option for the user so the default will be no single sign-on. If the user chooses to enable single sign-on when authenticating to UH Login, only those apps that don't use the renew parameter will permit single sign-on if the user doesn't logout via the Logout URL from a previously visited app.

Why can't I login successfully to the CAS test environment?

There are several reasons for this and one or both may be applicable:

1. Currently you need to use a UH VPN to access CAS test.  (not a requirement for production CAS, nor will it ever be)
2. CAS test points to a test LDAP instance that may not have your current password.  Send an email to the IAM team to request a "password sync" if needed.

Can anyone use my Web site?

...

Since this feature is not compatible with our existing business rules, IAM will be disabling this feature during the 2014 calendar year.

...

Troubleshooting

...

Application Not Authorized to Use UH Login

Problem:

Your application cannot successfully authentication against CAS.

Example error message:

Solutions:

...

Reference: CAS Users mailing list thread on time synchronization

...

...

Technical Support

There is an active UH community of developers and a good chance that at least one of them has experience with your scenario.  It is well worth joining this community's email list if you've not already done so.  For details, visit App Developers Forum page.  Note that the ITS Identity and Access Management team also participates on this list.