Configuring Google SAML and Canvas Authentication

[#1]

Official Canvas Document

This article describes the process of configuring Google as an Identity Provider (IdP) ready to work with Canvas.

• Configure Google SAML (SSO)
• Calculate the Fingerprint
• Configure Canvas Authentication

Authentication Terminology

Term	Definition
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. Google is the Identity Provider.
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.
Metadata	Information about the SP or IdP.  This metadata is almost always provided in the form of XML.  The metadata about your Canvas instance is located at http://<YOURDOMAIN>.instructure.com/saml2 (replace <YOURDOMAIN> with the first portion of your Canvas domain).
SAML	Security Assertion Markup Language
SIS	Student Information System
SIS ID	Unique ID of a user in Canvas. Used to link a user to an outside system, often a Student Information System (SIS).
SLO	Single Logout When a user logs out of a service, some IdPs can subsequently log the user out of all other services the user has authenticated to.  Google supports this but may occasionally experience issues such as preventing a successful logout. Users will be logged out of Canvas but may not be logged out of Google.
SP	Service Provider An SP 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 Provider. Note: An SP cannot authenticate against an IdP unless the IdP is known to the SP.  Likewise, an IdP will not send assertions to an SP that it does now know about.
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.

 

Pre-requisites

• Any user that needs to authenticate via Google SAML must already have a user account provisioned in Canvas.
• The login_id field in Canvas must match the selected field returned from Google.
• Canvas does not automatically create user accounts from successful single-sign-ons. User accounts must either be created manually in the web interface or through the SIS import CSVs.
• Your organization must be using Google Apps.
• You must be able to log in to the admin console for your organization.

NOTE: To complete the steps in this documentation, you will need to use your Production environment of Canvas. Testing Google SAML authentication will not work in Test or Beta.

Login Release Valve

You may lock yourself out of Canvas while you are working on setting up authentication. If this happens, there is a way to log in to Canvas using local authentication.  Simply go to /login/canvas. For instance: http://<YOURDOMAIN>.instructure.com/login/canvas (This forces Canvas to display the local login page rather than redirecting to the SAML login page).

Configure Google SAML (SSO)

You will be in both the Google Apps admin console, as well as in Canvas, so have both sites open in different tabs.

1. In Canvas, select Google SAML authentication by going to the Authentication tab on the left, and select SAML (rather than “Google”) from the drop-down menu on the right.

2. In another tab or window, log in to the Google Apps administration Console.

3. From the Admin console Home page, go to Apps and then Web and mobile apps.

4. Click Add App and select Add custom SAML app at the bottom.

5. Basic Information for your Custom App

1. Enter Canvas for the App Name [1]
2. Optionally add an icon for your Canvas App [2]
   • Download this image
3.  Click Continue [3]

6. You will need the information on this screen for configuring SAML with Canvas.

1. Copy the Google SSO URL and paste it into the Canvas Log On URL (in your other tab/window) [1]
2. Copy the Google Entity ID and paste it into the Canvas IdP Entity ID (in your other tab/window) [2]
   • Optional: Download Metadata from Option 1
3. Copy Certificate and paste into a text document, we'll use this under the Calculate the Fingerprint section below [3]
4. Click Continue

7. Service Provider Details

1. Enter https://<YOURDOMAIN>.instructure.com/login/saml for ACS URL [1]
   • (Ex: https://school.instructure.com/login/saml)
2. Enter http://<YOURDOMAIN>.instructure.com/saml2 for Entity ID [2]
   • (Ex: http://school.instructure.com/saml2)
   • (Note: use HTTP, not HTTPS in this field)
3. Enter https://<YOURDOMAIN>.instructure.com for Start URL [3]
   • (Ex: https://school.instructure.com)
4. Check the Signed Response checkbox [4]
5. Change Name ID Format to Email [5]
6. Click Continue

8. Click Finish

9. You have added the SAML App to Google, now you also need to turn on the app for your users:

• Click on USER ACCESS

• Select ON for everyone [1] and then click on SAVE [2]

10. If everything went well then your screen should look like this.

Now you are ready to calculate the certificate fingerprint and configure Canvas.

Calculate the Fingerprint

1. Open the metadata xml file (downloaded from the Google IdP Information page) in a text editor or using Google Chrome or Firefox.
2. Copy the data contained between the <ds:X509Certificate>
3. Calculate fingerprint using https://www.samltool.com/fingerprint.php
   1. Copy the fingerprint from step 6 above
   2. Paste the x509certificate (Example below), leave the Algorithm as sha1 and click CALCULATE FINGERPRINT

1. 1. Copy either the FingerPrint or Formatted FingerPrint
      • Additional information is found here

Configure Canvas Authentication

Note: Google SAML configurations do not need to be in the first position. You just need to use a discovery URL when there is more than one method of authentication possible.

1. Complete the configuration in Canvas:
   1. IdP Entity ID: Enter Entity ID from Google tab/window (already performed in a previous step)
   2. Log On URL: Enter SSO URL from Google tab/window (already performed in a previous step)
   3. Log Out URL: Enter https://accounts.google.com/logout
   4. Certificate Fingerprint: Copy the formatted fingerprint calculated the "Calculate the Fingerprint" section.
   5. Login Attribute: Select NameID
   6. Identifier Format: Select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   7. Ensure that the Authentication Context selected is classes:Password.
   8. Message Signing: RSA-SHA1
      • ***Note: If the IdP Metadata is publicly hosted and that public URL to the IdP metadata has been inputted in the Canvas configuration "Metadata URI" section, the Message Signing will accept "RSA-SHA256". If this is the case do not forget to calculate the fingerprint with the "sha256" algorithm (from the "Calculate the Fingerprint" section)
   9. Click Save

Test Login

Now that the Google SAML App and Canvas Authentication have been configured, we can now test authentication.

• Canvas SAML Debugger Tool

1. Make sure a Canvas user has been provisioned first. Login attribute should be admin@<yourgoogledomain>.com

2. Click Test SAML Login from Google Admin Console [1]

3. This will redirect to Canvas and if everything is set up correctly, the user login will be a success!

Congratulations! Google SAML SSO has been configured for Canvas LMS