Configuring CAS and Canvas Authentication

Document created by jivedocs@instructure.com Employee on Jun 29, 2015Last modified by jivedocs@instructure.com Employee on Aug 8, 2016
Version 8Show Document
  • View in full screen mode

    Official Canvas Document

Canvas + Logo transparent (WHITE)- 300px.png

 

 

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

Screen Shot 2015-06-25 at 1.34.52 PM.png

Authentication Terminology

 

TermDefinition
CASCentral Authentication Service
IdPIdentity 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.
ServiceA 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.
SSOSingle 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.
SLOSingle 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 IDUsername 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 IDUnique ID of a user in Canvas.
Used to link a user to an outside system, often a Student Information System (SIS)
SISStudent 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/Jasig/cas/blob/master/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:

  1. Add Canvas as a registered service in CAS
  2. Obtain CAS base URL
  3. Enter CAS base url into Canvas
  4. 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 JASIG can be found at https://github.com/Jasig/cas/blob/master/cas-server-documentation/installation/Service-Management.md

 

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 URLEnter the base url from step 2.Note: Make sure your URL does not end in /login. It should end with /cas.
Login LabelEnter 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 UrlSet 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

 

SymptomPossible CauseRemedy
User can't loginUser 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 CanvasCAS can do backchannel logouts.Determine whether this behavior is desired. Modify CAS to support longer sessions or disable this feature.For more information read http://jasig.github.io/cas/development/installation/Logout-Single-Signout.html.
Canvas reports "Unable to login"See above orCanvas may not be able to contact the CAS server to validate the user's informationMake sure the CAS server does not have firewall rules preventing outside connections.

 

Additional Reading

Importing CSV data into Canvas: http://guides.instructure.com/m/4214/l/164118-how-do-i-format-csv-text-files-for-uploading-data-into-canvas

 

Editing user accounts: http://guides.instructure.com/m/4214/l/73700-how-do-i-edit-a-user-s-details-in-my-account

 

Manually adding user accounts: http://guides.instructure.com/m/4214/l/73704-how-do-i-manually-add-a-new-user-to-my-account

 

References

https://github.com/Jasig/cas/blob/master/cas-server-documentation/index.md

1 person found this helpful

Attachments

    Outcomes