|
Official Canvas Document |
 |
- Background
- Authentication Workflow
- Authentication Terminology
- Prerequisites
- Test and Beta Canvas Sites
- Login Release Valve
- Configuring CAS to work with Canvas
- Add Canvas as a registered service in CAS
- Obtain CAS base URL
- Configure baseURL into Canvas
- Configure CAS in Canvas Authentication
- Troubleshooting
- Additional Reading
- References
Background
Single Sign On (SSO) is a functionality that many schools will configure during the implementation phase of transitioning to Canvas online with their institution. SSO provides many benefits, not the least being that after users sign in to 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. CAS supports SSO.
When Canvas receives a successful identity assertion from any of its 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 Canvas receives a CAS response for a user and the value for the username is "fred," Canvas 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.
Administrators can view/modify/create logins for users by clicking on the user account name in the search results for users. The search for user will search for email, SIS identifier, login username, etc.
This article describes the process of configuring and debugging CAS authentication to work with Canvas.
Authentication Workflow
Authentication Terminology
| 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. CAS is the Identity Provider. |
| Service | A Service is usually a website providing information, tools, reports, etc to the end user. Canvas provides a learning environment to teachers, students, and admins and is therefore the Service. A service cannot authenticate against a CAS unless it is listed in the list of approved services. |
| SSO | Single Sign On. This is what happens when a user isn't required to log in to a second service because information about the authenticated user is passed to the service. |
| 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. |
| Login ID | Username in Canvas terminology. When information about an authenticated user is returned to Canvas, a user with a login id matching the incoming data is looked for. |
| SIS ID | Unique ID of a user in Canvas. Used to link a user to an outside system, often a Student Information System (SIS) |
| SIS | Student Information System |
Prerequisites
- Any user that needs to authenticate via CAS must already have a user account provisioning in Canvas.
- The login id field in Canvas 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://github.com/apereo/cas/blob/master/docs/cas-server-documentation/index.md
Test and Beta Canvas Sites
Each Canvas account comes with a .test and .beta site. Information about these sites is described in detail elsewhere. You will want to test your authentication setup in the test area first before moving to production.
Login Release Valve
You may lock yourself out of Canvas while you are working setup authentication. If this happens, there is a way to log in to Canvas using local authentication. Simply go to /login/canvas. For instance: http://<yourcanvasname>.instructure.com/login/canvas (This forces Canvas to display the local login form rather than redirecting to the SAML login page).
Institutions using LDAP or SAML authentication can now use the same authentication to register observers in Canvas. For LDAP institutions, observers will enter the student's LDAP credentials directly from the registration page. For SAML institutions, observers will be redirected to the authentication page and log in with the credentials of the student they are observing. This authentication process is also used when observers add additional observees to their accounts.
Configuring CAS to work with Canvas
Configuring Canvas to accept authentication from a CAS Identity Provider includes the following steps:
- Add Canvas as a registered service in CAS
- Obtain CAS base URL
- Enter CAS base url into Canvas
- Configure CAS in Canvas Authentication
Add Canvas as a registered service in CAS
Note: Some CAS IdPs are set up to allow any service. In this case you can safely skip to step 2.
Adding Canvas as a registered service will vary. Information about doing this with the most common CAS implementation by APEREO can be found at https://github.com/apereo/cas/blob/master/docs/cas-server-documentation/installation/Configuring-Dep....
Obtain CAS base URL
You will need to know the base URL of your CAS IdP. This URL will be entered in Canvas. This URL will look something like the following:
https://schoolname.edu/cas
Configure baseURL into Canvas
To configure CAS in Canvas, you may choose to include some or all of the following information as part of the configuration as shown in the table below.
| Modify the data fields as follows: | |
| CAS URL | Enter the base url from step 2.Note: Make sure your URL does not end in /login. It should end with /cas. |
| Login Label | Enter a label for the usernames. This is used in a few places inside Canvas to refer to the username. This might be student number, an ID, username, or any number of other names. If you enter no value then Canvas will use Login ID. |
| Unknown User Url | Set this to a URL you want the user redirected to if their account is not found. If no value is entered, Canvas will simply display a page indicating that there was a problem logging in. |
Configure CAS in Canvas Authentication
Learn how to configure authentication in Canvas.
Troubleshooting
| Symptom | Possible Cause | Remedy |
| User can't login | User doesn't exist in CanvasorUser's login_id in Canvas 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 Canvas. | Create userorUpdate login id in Canvas or change CAS response. |
| User is randomly logged out of Canvas | CAS can do backchannel logouts. | Determine whether this behavior is desired. Modify CAS to support longer sessions or disable this feature.For more information read https://github.com/apereo/cas/blob/master/docs/cas-server-documentation/installation/Logout-Single-S... |
| Canvas reports "Unable to login" | See above orCanvas 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. |
Additional Reading
References
https://github.com/apereo/cas/tree/master/docs/cas-server-documentation
