Skip to main content

Configuring CAS (2.0 / 3.0)

info

For clarification on terms in these docs, please refer to the Definition of Terms page

Introduction​

In many cases the CAS configuration for the SP requires only a few key pieces of information to set up basic authentication. The IdP may require more in-depth configuration in order to meet the needs of your integration. You will need to refer to your IdP documentation for any advanced configuration. Because this configuration can differ from IdP to IdP, we are unable to provide specific instructions for every IdP.

Implementation Overview​

  1. Have a running Identity Provider (IdP) that supports CAS SSO protocols to integrate with IE as the Service Provider (SP). See docs for some specific IDPs here.

  2. Configure your IdP server

  3. Share your IdP Details with your IE representative so they can configure your client. For CAS this typically means the IE validation endpoint (aka CAS server url / serviceValidate endpoint).

  4. Construct a Learner Login URL to your instance for students to use for authentication. You'll need a service URL provided by IE and potentially more depending on your circumstances.

  5. Test Authentication making configuration adjustments as needed. This entails you attempt logging in via SSO (Login URL provided by IE as needed) and your IE rep will consult the SP logs and make / suggest changes if required.

  6. Share your SP Redirect URLs for a better user experience. With SSO enabled and accounts controlled by the IDP, learners have no need for the SP Logout or Account pages anymore. These pages will require redirection to equivalent pages in your system, so share redirect URLs with IE to configure.

Have Existing Learners?

Changing your SSO configuration for a client with existing learners comes with some additional challenges. See details here.

Using a Federated IdP?

Using a federated Identity Provider (district level, 3rd party etc) comes with some additional considerations. See details here.

Service Provider Configuration​

What IE needs from you​

Please provide your IE representative the following, so they can configure your SP client.

  1. The serviceValidate endpoint for your CAS server.

    If your CAS server is available at https://casserver.org/, then your CAS serviceValidate endpoint is most likely:

  2. Account Redirect URLs With SSO enabled for your client, learners will have no need for the Login, Register or Account pages on the SP side. These pages should be redirected to relevant pages on the IdP side. Please provide the following types of redirect URLs to your IE representative to configure.

Account Details URL (required)

Usage:​

The account details page is replaced by an "Account Details" button which links to the URL provided.

Details:​

We recommend this URL to point to a corresponding page on the IdP side where learners can adjust their account or profile settings, such as name, email, or password if available. With SSO enabled, any changes made on the IdP side will be reflected on the SP side the next time the user authenticates.

Types of pages on the IdP side to consider:​

  • Profile Settings Page
  • Password Reset Page
  • Home Page

Example:​

https://www.yourdomain.com/settings

Logout URL (required)

Usage:​

This redirects the logout button (in the profile dropdown menu) to the URL provided.

Details:​

This, on it's own, only logs the learner out of the SP platform and not out of SSO or the IdP side. For circumstances like a shared computer terminal, it's important that learners know they aren't logged out of IdP accounts when they log out of the SP platform via this URL.

Types of pages on the IdP side to consider:​

  • Home Page
  • Internal Dashboard Page
  • A Logout URL (if available) to log the user out of the IdP
  • Specific Page letting learners know they're not logged out of their IdP yet (if applicable)

Example:​

https://www.yourdomain.com/logout

  1. Date to begin enforcing SSO Once SSO is complete, when would you like to turn off (redirect) native registration. This is mostly relevant for clients who already have learners utilizing native registration. If you don't have any learners using native registration, this redirect can be configured immediately.

Identity Provider Configuration​

Configure the externalCustomerID​

The cas:user is the unique ID that will identify CAS users coming from the IdP. This value is stored internally as externalCustomerId, and when a learner authenticates, it is used to determine whether to connect them to their pre-existing account or provision them a new one, if this is the learner's first time authenticating. The attributes passed by the IdP will be used to create the new account, or if connecting to a pre-existing account, the attributes passed by the IdP will be used to update it.

Important

To avoid account clashes, the externalCustomerId value must be unique amongst all learners from all clients in the same instance. With sometimes hundreds of clients in the same instance, this can mean 100s of thousands of users. See below for recommendations on how to configure this value.

note

In WSO2 the cas:user is controlled by the field (Subject Claim URI)

Requirements​

  • Must be unique across the instance: The value of the externalCustomerId must be unique across all learners of every client in an instance. This means that if you share an instance with other clients (almost everyone), then your ID must not clash with other client's learners.

  • Some good options include:

    • Email Addresses
    • An ID random enough to be sufficiently collision resistant
    • Appending the school domain name to an ID like this [email protected]

Recommendations​

  • An ID that doesn't change: Since this value used to sync learner to their accounts or create a new account if one doesn't exist for a learner, it's recommended that this value be from a source that doesn't change. If the value does change, then the learner will receive a fresh account upon authenticating and will lose all previous progress.

    • Email Address: Sending an email as the externalCustomerId can occasionally cause this if learner's email is tied to their name in a way where any changes to their name causes a change to their email. That said, email addresses are used by many clients without much headache. Though it isn't the perfect solution, a majority of our clients consider it good enough.

    • Unique IDs: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID like this [email protected], has the benefits of being both unique and unchanging. This tends to be the optimal approach and is what we recommend first if available.

Configure Attributes​

We support the following attributes that can be mapped from your IdP. The attributes returned in the authentication request, as well as the attribute names, will vary depending on the IdP. Check with your IdP to determine the available attributes.

The following list of attributes are available for mapping to any attribute returned from your IdP.

AttributeTypeDescriptionRequired?
firstnamestringThe first name of the learnerRecommended
lastnamestringThe last name of the learnerRecommended
emailstringThe email address of the learnerRecommended
ref1stringData to be associated with the user in reports. examples: role, department, major, title, year, studentIdOptional
ref2stringData to be associated with the user...Optional
ref3stringData to be associated with the user...Optional

Example​

The following is an example of a successful CAS ticket validation:

<?xml version="1.0" encoding="UTF-8"?>
<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
  <cas:authenticationSuccess>
    <cas:user>test</cas:user>
    <cas:attributes>
      <cas:firstname>bob</cas:firstname>
      <cas:lastname>jones</cas:lastname>
      <cas:email>[email protected]</cas:email>
    </cas:attributes>
  </cas:authenticationSuccess>
</cas:serviceResponse>

Learner Access Restrictions​

All access restrictions, or lack there of, are handled on the IdP side of things. So if applicable, make sure sufficent role permissions have been granted to the learners who'll need access to the IE platform before they need it.

From IE's perspective, there's not much downside to providing access to all accounts in the IdP side (ie no restrictions) as learners who need access to the IE content may change, and any learners who no longer need access or who never needed it will typically avoid.

Authentication​

Direct your users to login to your CAS server with the "service" query parameter set to the URI Encoded Service URL.

https://<CAS Server Domain>/login?service=<URI Encoded Service URL>

To build this URL, follow these steps:​

1. Construct the Service URL​

Start with the Base URL:​

Start by constructing the base of the URL depending on which IE product you're configuring for. Combine the https protocol, IE product domain, and cas access path:

Add License ID:​

Next, you'll need to specify a License ID to connect the incoming student with your Client in our system. You can obtain your client's License ID from your IE representative. Treat this License ID as a secret, similar to a password.

Add a licenseId query parameter and value to Base Service URL (params are case sensitive):

Add Redirects (Optional):​

You can optionally specify a URL of a page to redirect the user to after successful authentication. After the SP validates the ticket from your CAS server, it will grant the user access and direct them to the specified returnTo URL, or the student dashboard if no URL was provided.

To do this, add a returnTo query parameter and value to the URL (params are case sensitive). Note: both a returnTo and a licenseId can be specified within the same request:

2. URI Encode the Service URL​

Once you have a complete Service URL, it must be URI encoded before it can be added to the CAS login URL. This will ensure structural integrity during URL parsing.

3. Add to CAS Login URL via Service Parameter​

Lastly, add a service query parameter to the CAS Login URL and set its value to the URI encoded Service URL:

Testing Authentication​

It's important to test the authentication flow before going live. This will ensure that the integration has been configured successfully before learners attempt to access their content.

To test, simply

  1. Authenticate from an incognito browser, using the SP login URL to authenticate into the IE platform through SSO.
  2. Notify your IE representative Once notified, IE will consult the SSO logs and verify the correct user details are being sent over.

Troubleshooting​

If authenitcation was successful, you should be redirected to the IE platform and logged in. If you are not logged in, and are still located on the IdP side, there's most likely an issue with the configuration on the IdP side.

If on the other hand you are seeing an error, notify your IE representative for next steps. Please include any error messages you see, as well as the page URL used to authenticate and the page URL of the error.