Connect to IU Login with the CAS protocol

• Overview
  • CAS basics
  • Requirements
  • Recommendations
• Integrate your service
  • Before you begin
  • Connect your service
• How CAS works at IU
  • Log in
  • Validate ticket
  • Log out
• CAS URI extensions
  • /login as credential requester and acceptor
  • /serviceValidate

Overview

CAS basics

IU Login supports the CAS 2.0 protocol; see CAS Protocol 2.0 Specification.

You can access the official CAS clients at https://apereo.github.io/cas/6.6.x/integration/CAS-Clients.html.

Requirements

UITS requires that you adhere to these practices when implementing CAS:

• Applications using CAS must operate entirely over TLS (that is, the service URL must be an HTTPS URL).
• To be sure they are authenticating to IU's CAS, users must be able to see https://idp.login.iu.edu/. Therefore, applications must redirect to IU Login and not render the login page inside an iframe or use other similar techniques.
  Important:

  The infrastructure supporting connections to https://cas.iu.edu/ was retired on February 7, 2022. If you have applications still connected to the legacy infrastructure, begin the migration process immediately by completing the CAS Integration Request form.

If you come across a page that does not adhere to these requirements or otherwise seems suspicious, follow the instructions in Report a suspected information or information technology (IT) security issue at IU.

Recommendations

UITS strongly encourages you to adhere to the following best practices when using CAS:

• Enabling HTTP Strict Transport Security (HSTS) is highly recommended.
• All of these requests take place through normal web transfers, either by use of redirects or through standard page requests. All communication with the CAS server is handled via SSL. Applications are strongly encouraged to use SSL on their web servers as well.
• Applications should maintain their own states with a user, so the login process with CAS should only happen once per session. After the initial login and validation, the application should not have to redirect the user back to CAS within the same session.
• Compiled modules are available. Make sure they meet your security needs before using them with your application.

  Be aware that the CAS ISAPI filter does not work on IIS 7.x, and will not be supported further.

Integrate your service

Before you begin

You'll need to understand your role as a Service Owner and the role of the Service Provider you will be sponsoring:

• Service Owner: The department and individuals within Indiana University that are sponsoring the CAS service integration being requested. Service Owners are responsible for facilitating all communications and updates from the Service Provider to the Identity Management Systems (IMS) team. Every Service Provider must have a sponsoring department and contacts.
• Service Provider: The organization that is providing a service to users who have identities established at IU. This organization can be inside or outside IU, but it must have an IU sponsor.

UITS strongly recommends integrating your test systems with the pre-production IU Login environment. This environment is available to verify changes to the IU Login infrastructure prior to release.

Connect your service

After familiarizing yourself with the roles above, follow the steps below to connect your service to IU Login 2.0:

1. Working with the Service Provider, complete the CAS Integration Request form.
2. When you are notified that the integration has been set up, update your application to connect to IU Login 2.0. For details, see the example below.

How CAS works at IU

At IU, CAS authentication works as follows:

1. Your web application redirects users to:

   https://idp.login.iu.edu/idp/profile/cas/login?service=https://yoursite.iu.edu

   Above, service is the URL of your service.

   For details, see Log in below.

2. Users log in at idp.login.iu.edu, and are redirected to your web application at https://yoursite.iu.edu as follows:

   https://yoursite.iu.edu?ticket=ST-1234LSDFJMVAKFHK234HVNLJ2FM

3. Your web application (yoursite.iu.edu) validates with CAS by sending a request to:

   https://idp.login.iu.edu/idp/profile/cas/serviceValidate?ticket= ST-1234LSDFJMVAKFHK234HVNLJ2FM&service=https://yoursite.iu.edu

   If the validation is successful, CAS sends back a response with the "username". If validation fails, CAS responds with an error message code.

   For details, see Validate ticket below.

4. When the user has finished with the web application, you may choose to log the user out of CAS. For details, see Logging out below.

Log in

The login process begins when a user first requests a page from your CAS-integrated application. Your site will need to redirect the user to the IU Login page. You will need to pass the return URL, normally https://yoursite.iu.edu, so that IU Login will know where to redirect users upon successful login. A properly formatted redirect URL using the above information would look like:

https://idp.login.iu.edu/idp/profile/cas/login?service=https://yoursite.iu.edu

IU Login maintains its own state with each user, and can determine if the user has a logged-in session. If the user has not authenticated yet, IU Login requires a valid username and passphrase combination before the user can proceed. If the user has already logged in, the process continues silently.

The following is some quasi-code to help show the process of logging in if the user is not authenticated:

if (!$authenticated) { $_SESSION['CAS']= true;
header("Location:https://https://idp.login.iu.edu/idp/profile/cas/login?service=https://pathForYourApplication");

In either case, once the user has authenticated, IU Login redirects the user back to the original application specified by the service value, generating and transmitting a unique string called a "CAS ticket"; a CAS ticket may look like this example:

https://yoursite.iu.edu?ticket=ST-1234LSDFJMVAKFHK234HVNLJ2FMST

Validate ticket

Once CAS redirects the user back to your site, the validation phase begins. Your application must now take the newly provided CAS ticket and send a request to CAS to check if the ticket is valid. The validation request must be in the following format (using the service URL in the format of https://yoursite.iu.edu):

https://idp.login.iu.edu/idp/profile/cas/serviceValidate?ticket=ST-1234LSDFJMVAKFHK234HVNLJ2FM&service=https://yoursite.iu.edu

This snippet of code provides instruction to validate the user, if authenticated, by getting the user's CAS ticket and seeing if it's good:

if ($authenticated) {      
  //validate since authenticated   
  if (isset($_GET["ticket"])) { 

The service parameter passed here to the validation service must match the values passed in the login request.

To see a full example of simple validation code, see /serviceValidate.

If validation is successful, CAS sends back an XML response that contains the "username".

Log out

You can provide a logout with the following URL:

https://idp.login.iu.edu/idp/profile/cas/logout

However, this is not reliable; the only secure way to log out from CAS is to close the browser. If secure logout is an issue with your service, direct your users to close their browsers when they have finished.

CAS URI extensions

/login as credential requester and acceptor

This HTTP request parameter may be passed to /login while it is acting as a credential requester. It is case sensitive, and must be handled by /login.

• service (optional): The identifier of the application the client is trying to access. In almost all cases, this will be the URL of the application. As an HTTP request parameter, this URL value must be URL-encoded.

Simple login example:

https://idp.login.iu.edu/idp/profile/cas/login?service=https%3A%2F%2Fwww.example.org%2Fservice

For more about the /login URI, see /login as credential requester.

/serviceValidate

/serviceValidate checks the validity of a service ticket and returns an XML-fragment response. /serviceValidate must also generate and issue proxy-granting tickets when requested. /serviceValidate must not return a successful authentication if it receives a proxy ticket. UITS recommends that if /serviceValidate receives a proxy ticket, the error message in the XML response should explain that validation failed because a proxy ticket was passed to /serviceValidate.

The following HTTP request parameters may be specified to /serviceValidate. They are case sensitive and must all be handled by /serviceValidate.

• service (required): The identifier of the service for which the ticket was issued, as discussed in section 2.5.1 of CAS Protocol 2.0 Specification. As an HTTP request parameter, the "service" value must be URL-encoded.
• ticket (required): The service ticket issued by /login
• pgtUrl (optional): The URL of the proxy callback. As an HTTP request parameter, the "pgtUrl" value must be URL-encoded.
• renew (optional): If this parameter is set, ticket validation will only succeed if the service ticket was issued from the presentation of the user's primary credentials. It will fail if the ticket was issued from a single sign-on session.

On ticket validation success:

<?xml version="1.0" encoding="UTF-8"?>
<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
	<cas:authenticationSuccess>
		<cas:user>username</cas:user>
	</cas:authenticationSuccess>
</cas:serviceResponse>

One example of ticket validation failures:

<?xml version="1.0" encoding="UTF-8"?>
<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
	<cas:authenticationFailure code='INVALID_TICKET'>
		E_TICKET_EXPIRED
	</cas:authenticationFailure>
</cas:serviceResponse>

Simple validation example:

https://idp.login.iu.edu/idp/profile/cas/serviceValidate?service=https%3A%2F%2Fwww.example.org%2Fservice&ticket=ST-1234LSDFJMVAKFHK234HVNLJ2FM

For more about the /serviceValidate URI, see /serviceValidate [CAS 2.0].