Integrate IU Login (formerly CAS) with a website

On this page:


Overview

At Indiana University, there are several different ways for applications to set up IU Login (formerly CAS) authentication with CAS, including login and validation.

Important:

Follow these best practices:

  • Applications using CAS must operate entirely over TLS (that is, the casurl must be an HTTPS URL).
  • Enabling HTTP Strict Transport Security (HSTS) is highly recommended.
  • To be sure they are authenticating to IU's CAS, users must be able to see the URL https://cas.iu.edu/. Therefore, applications must redirect to CAS and not render the login page inside an iframe or use other similar techniques.

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

At IU, CAS authentication works as follows:

  1. Your web application redirects the user to:
     https://cas.iu.edu/cas/login?cassvc=IU&casurl=https://yoursite.iu.edu
    • cassvc is the IU custom application code.
    • casurl is the URL of your service.

    See Logging in below.

  2. The user logs in at cas.iu.edu, and is redirected to your web application at https://yoursite.iu.edu as follows:
     https://yoursite.iu.edu?casticket=ST-1234-cvbfglkDFGbfbnvbjh-wsa451.uits.indiana.edu

    Note that casticket is equivalent to ticket on the CAS 1 Architecture page.

  3. Your web application (yoursite.iu.edu) validates with CAS by sending a request to:
     https://cas.iu.edu/cas/validate?cassvc=IU&casticket=ST-1234-cvbfglkDFGbfbnvbjh-wsa451.uits.indiana.edu&casurl=https://yoursite.iu.edu

    If the validation is successful, CAS sends back a two-line response with "yes" on the first and "username" on the second. If validation fails, CAS responds with "no".

    See Validating a CAS ticket below.

  4. When the user has finished with the web application, you may choose to log the user out of CAS. See Logging out.
Note:
CAS 2.0 at IU is fully interoperable with the standard CAS protocol. Because standard CAS 2.0 does not require an application code, it will default to IU AppCode. However, the CAS 1.0 validation assertion will return "<username>/r/n" instead of the Unix-style "/n" only.

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, and will also need to communicate (via the URL) what kind of authentication you want CAS to perform with an application code; see CAS application codes at IU. A common example of an application code is IU, which restricts your application to users with a valid IU Active Directory credential. You will also need to pass the return URL, normally https://yoursite.iu.edu, so that CAS will know where to redirect users upon successful login. A properly formatted redirect URL using the above information would look like:

 https://cas.iu.edu/cas/login?cassvc=IU&casurl=https://yoursite.iu.edu

The CAS server 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, CAS requires a valid username and passphrase combination before the user can proceed. If the user had 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://cas.iu.edu/cas/login?cassvc=appCode&casurl=https://pathForYourApplication");

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

 https://yoursite.iu.edu?casticket=ST-1234-cvbfglkDFGbfbnvbjh-wsa451.uits.indiana.edu

Validate a CAS 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 application code IU and a return URL of https://yoursite.iu.edu):

 https://cas.iu.edu/cas/validate?cassvc=IU&casticket=ST-1234-cvbfglkDFGbfbnvbjh-wsa451.uits.indiana.edu&casurl=https://yoursite.iu.edu

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

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

The cassvc and casurl parameters passed here to the validation service must match the values passed in the login request.

If validation is successful, CAS sends back a two-line response with "yes" on the first and "username" on the second. If validation fails, CAS simply responds with "no".

Notes:
  • The ticket must be validated within two seconds.
  • TLS 1.2 or higher is required for CAS.

Log out

You can provide a logout with the URL:

https://cas.iu.edu/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, you should direct your users to close their browsers when they have finished.

Test with the CAS stage environment

UITS recommends integrating your test systems with the non-production IU Login stage environment for CAS. This environment is available to verify changes to the CAS infrastructure prior to release.

To point your application to the stage environment, change the configured CAS URL to https://cas-stage.iu.edu. To verify that your application is pointing to the stage environment, log in; you will be directed to the https://cas-stage.iu.edu login page instead of the production URL, https://cas.iu.edu.

Notes

  • Your casurl value must be URL encoded. Replace any non-ASCII characters with a percent sign ( % ) followed by the appropriate hexadecimal digits (for example, replace a space in your URL with %20 ). For a complete list of ASCII character codes, see ASCII Code - The extended ASCII table. For more about URL encoding, see the w3schools.com HTML URL Encoding Reference.
  • CAS tickets may be validated only once.
  • 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. See IU Login (formerly CAS) with PHP on Webserve/IU Sitehosting. Make sure they meet your security needs before using them with your application.

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

    Note:
    Webserve is scheduled for retirement on December 23, 2019, and will be replaced by IU Sitehosting. All sites hosted on Webserve must be migrated to IU Sitehosting by that date or content will be inaccessible.
  • If you have an IU GitHub account, you can access these CAS Integration Examples. For information on GitHub at IU, see About GitHub at IU.

To contact the Identity Management Systems (IMS) team, email  ithelp@iu.edu .

Note:

To stay informed or provide feedback about IU Login (formerly CAS), or to ask questions about developing with it, use the cas-discuss-l mailing list. To subscribe, send email to cas-discuss-l-subscribe@iu.edu.

This is document atfc in the Knowledge Base.
Last modified on 2019-08-27 08:57:24.

Contact us

For help or to comment, email the UITS Support Center.