Background
Single Sign On (SSO) is a functionality that many companies will configure during the implementation phase of Bridge to bring the platform online with their institution. SSO provides many benefits, not the least being that after users sign into one of the services at an institution they are automatically authenticated into any other service that uses SSO. The user is only required to remember one set of credentials.
When Bridge receives a successful identity assertion from supported authentication integrations, it searches for a user 'login' that matches the value of the asserted identity. If it finds a matching login, it logs in the associated user account.
For example, if Instructure Bridge receives a CAS response for a user and the value for the username is 'fred', Bridge will search for a login with a username of 'fred'. If one is found, the associated user is logged in, otherwise the login is unsuccessful. If user provisioning is on, a user with the unique identifier 'fred' will be created.
This article describes the process of configuring and debugging CAS authentication to work with Bridge.
Definitions
| Term | Definition |
|---|---|
| CAS | Central Authentication Service |
| IdP |
Identity Provider. The job of the IdP is to identify users based on credentials. The IdP typically provides the login screen interface and presents information about the authenticated user to Service Providers after successful authentication.
|
| Service |
A Service is usually a website providing information, tools, reports,
etc to the end user. Bridge provides a learning environment to
authors, learners, and admins and is therefore the Service. A service cannot authenticate against a CAS unless it is listed in the list of approved services. |
| SLO |
Single Logout. When a user logs out of a service, some IdP's can
subsequently log the user out of all other services the user has
authenticated to. CAS supports this out of the box. |
| SSO | Single Sign On. This is what happens when a user isn't required to login to a second service because information about the authenticated user is passed to the service. |
| Unique Identifier (UID) | Username in Bridge terminology. When information about an authenticated user is returned to Bridge, Bridge searches for a user with a UID matching the incoming data. |
Prerequisite
- Any user that needs to authenticate via CAS must already have a user account in Bridge.
- The login id field in Bridge must match the username field returned from CAS.
- CAS must be installed and running. This document does not walk through the CAS installation. For information about this, please visit https://wiki.jasig.org/display/JSG/Home.
Configuration
Configuring Bridge to accept authentication from a CAS Identity Provider includes the following steps:
- Add Bridge as a registered service in CAS
- Obtain CAS base URL
- Enter CAS base url into Bridge
Step 1: Add Bridge as a registered service in CAS.
Note: Some CAS IdP's are setup to allow any service. In this case you can safely skip to step 2.
Adding Bridge as a registered service will vary. Information about doing this with the most common CAS implementation by JASIG can be found at 5.7. Service Management - CAS User Manual - Apereo Wiki
Step 2: Obtain CAS base URL
You will need to know the base URL of your CAS IdP. This URL will be entered in Bridge. This URL will look something like the following: https://companyname.com/cas
Step 3: Obtain CAS base URL
Provide the CAS base URL to the Implementations team at Instructure and they will input your URL for you.
Make sure your URL does not end in /login or something like that. It should end with /cas.
Troubleshooting
| Symptom | Possible Cause | Remedy |
|---|---|---|
| User can't login |
User doesn't exist in Bridge or User's login id in Bridge doesn't match incoming CAS response. The CAS response will have a piece of XML that looks like <cas:user>username</cas:user> where username must match a user's login id in Bridge. |
Create user or Update login id in Bridge or change CAS response. |
| Bridge reports "unable to login" | See above or Bridge may not be able to contact the CAS server to validate the user's information | Make sure the CAS server does not have firewall rules preventing outside connections. |