Skip to main content
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Configuring ADFS (SAML) and Canvas Authentication

Configuring ADFS (SAML) and Canvas Authentication

    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. ADFS 2.0 is a flavor of SAML, which supports SSO.

 

When Instructure 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 an ADFS assertion for a user and the value for the configured identity attribute 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 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 ADFS authentication to work with Canvas.

 

Authentication Terminology

 

Term

Definition

ADFS

Active Directory Federated Services

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.


ADFS is the Identity Provider.

RP

Relying Party.


A Relying Party is usually a website providing information, tools, reports, etc to the end user.  Canvas accepts authentication information from the IdP and provides a learning environment to teachers, students, and admins. Canvas is a Relying Party.


An RP cannot authenticate against a ADFS 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.
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

 

*ADFS doesn't always accept Canvas single logout requests. Some configuration adjustments may be required.

 

Prerequisites

  • Any user that needs to authenticate via ADFS must already have a user account provisioning in Canvas.

  • The login ID field in Canvas must match the username field returned from ADFS.

  • ADFS must be installed and running. This document does not walk through a complete ADFS installation. For information about this, please follow Microsoft’s instructions for installing ADFS 2.0 and IIS and configuring it with Active Directory and setting up an SSL certificate.

  • Canvas supports configuring ADFS 2.0, 3.0, and 4.0.

 

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.


Note: The Canvas metadata contains AssertionConsumerService URLs for each of the production, test, and beta environments.  With a single entity ID, there may be some confusion around how to configure the IdP to work for these three seemingly separate areas.  You should consider all three together as a single Service Provider with a single Entity ID but three possible AssertionConsumerService URLs.


Shibboleth is built to handle this natively so this should not create any problems.  Once you configure Shibboleth to contain your school's metadata, Shibboleth will be able to do authentication with production, test, and beta.


ADFS can also support multiple URLs.


Many IdPs do not have the ability to work with multiple AssertionConsumerService URLs in the metadata.

 

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).

 

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 ADFS 2.0 with Canvas

Configuring ADFS and Canvas to work together involves the following steps.

  1. Set up a Relying Party Trust and Claim Rules for Canvas
  2. Set up ADFS Single LogOut Workaround
  3. Configure Canvas to work with your ADFS 2.0 server
  4. Configure ADFS Single LogOut Workaround
  5. Configure ADFS 2.0 Forms Authentication Login Page Instead of Windows Authentication Prompt
  6. Configure ADFS/SAML in Canvas Authentication

 

Set up a Relying Party Trust and Claim Rules for Canvas

 

Add Relying Party Trust Wizard

 

Select the Add Relying Party Trust option, then click the Start button.

 

Import data about the relying party published online or on a local network

 

In the Select Data Source page, choose the Import data about the relying party published online or on a local network option and enter the Federation Metadata address into the box. Then, click the Next button.

 

Instructure default URL: https://yourcanvasdomain.instructure.com/saml2

If you are using a custom domain for Instructure: https://yourcustomdomain.com/saml2

 

Select Display Name

 

In the Select Display Name page, enter the name of your relying party in the Display name field. This is the name that will show up in the trust list. The content of the name does not affect functionality. Note that this display cannot be edited in the future. Then, click the Next button.

 

Choose Issuance Authorization Rules

 

In the Choose Issuance Authorization Rules page, leave the Permit option checked and click the Next button. In the Ready to Add Trust page, click the Next button.

 

Open the Edit Claim Rules dialog for this relying party trust when the wizard closes

 

In the Finish page, make sure the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes check box is selected, then click the Close button.

 

Add Rule

 

Click the Add Rule button.

 

Send LDAP Attributes as Claims

 

In the Claim rule template drop-down menu, select the Send LDAP Attributes as Claims option, then click the Next button.

 

Configure Rule

 

Populate the screen as shown above; the Active Directory must already be set up in the ADFS 2.0 Attribute Stores section to be used here.


Note that the Claim rule name "UPN = Name ID" is only an example. This is for display inside ADFS only and you will likely want to change it to fill your setup.
This screen is mapping Active Directory LDAP attributes to standard SAML outgoing attributes that the Canvas SAML server will be able to map on its side. Please note we use User-Principal-Name but your institution might use a different value to login that we do.


Click the Finish button.

 

Relying Party Trust Properties

 

Find the Relying Party Trust in the ADFS 2.0 list of trusts, then select the Properties option in the right menu. Click the Encryption tab, then click the certificate View button.

 

Install Certificate

 

Click the Install Certificate button.

 

Certificate Import Wizard

 

In the Certificate Import Wizard, chose Local Machine and click the Next button.

 

Advanced Tab

 

In the Certificate Store page, select the default option, then click the Next button. You will be redirected to the Encryption tab of the properties window. Click the Apply button, then click the Advanced tab.

 

Secure Hash Algorithm

 

In the advanced tab, set the Secure Hash Algorithm to SHA-1. Apply any changes and close out of the properties window.

 

Thumbprint value

 

Under ADFS 2.0 > Service > Certificates, the SSL certificate information should be listed. Double-click the certificate and located the Signing Certificate. Click the Details tab to see a long list of fields & values from your certificate. Scroll down until you find the Thumbprint field and write down the value. You may notice that the Thumbprint Algorithm is sha1; if it is sha256 you may need to adjust the previous step. Make sure you have the Thumbprint value written down as it is needed in Canvas.

 

Setup ADFS Single LogOut Workaround

When you click logout of Canvas, you may be greeted with this, or a similar message:

 

The SAMLRequest logout parameter breaks ADFS’s ability to actually log a user out, or at least at first glance. But this error is not an ADFS error, it is an IIS page error. The issue here is the length of the query string parameter in the SAMLRequest logout. Look here for the real tech jargon.The fix is fairly simple: force IIS to allow a specific query string parameter.

 

1. Open up your IIS Manager.

2. Find the adfs/ls directory.

3. Select the Request Filtering icon.

4. Select the Query Strings tab.

5. Click the Allow Query String link.

6. Add a new Query String called SAMLRequest, then click the OK button.

7. Click the Edit Feature Settings link.

8. Change the Maximum Query String Length (Bytes) to 4096.

*You may need to restart the adfs/ls IIS web pages to get the changes to work.

 

Configure Canvas to work with the ADFS 2.0 server

To configure ADFS 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.

 

Configure the fields on this screen as follows:

IdP Entity ID

Required. An entity ID is a globally unique name for a SAML entity, either an Identity Provider (IdP) or a Service Provider (SP).

 

in almost all cases, an entity ID is an absolute URL but it's important to note that an entity ID is a name, not a location. That is, an entity ID need not resolve to an actual web resource.

Log Out URL

https:// your.adfserverurl.com /adfs/ls/?wa=wsignout1.0

Note: This URL will require the user to close their browser to end their session, but will take them back to your ADFS server’s log out page where you can display a warning about this.

Change Password URL

URL to redirect users to to change their password inside ADFS.

Certificate Fingerprint

SSL Certificate Thumbprint for your ADFS server that we wrote down in a previous step.

Login Attribute

Should match what you selected in the Claim Rule setup, in our case it was User-Principal-Name > Name ID.

Identifier format

Usually set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Authentication Context

No Value

Login Label

Enter a label for 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:

Enter a URL that a user will be 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.

Position

1

 

Configure ADFS Single Logout Workaround

IIS, the web server that runs behind ADFS, currently limits the length of URL including query parameters. The IIS server needs to be modified to accommodate a longer query parameter, called "SAMLRequest=".

 

Configure ADFS/SAML in Canvas Authentication

Learn how to configure authentication in Canvas.

 

Configuring ADFS 3.0 or 4.0 with Canvas

Configuring ADFS and Canvas to work together involves the following steps.

  1. Set up a Relying Party Trust and Claim Rules for Canvas
  2. Configure Canvas to work with your ADFS 3.0/4.0 server
  3. Configure ADFS/SAML in Canvas Authentication

 

Note: The steps below show how to configure ADFS 3.0 with Canvas. The configuration for 4.0 is similar enough that you should be able to follow the same steps to configure 4.0.

 

Set up a Relying Party Trust and Claim Rules for Canvas

 

Add Relying Party Trust Wizard

 

Select the Add Relying Party Trust option, then click the Start button.

 

Select Data Source

 

In the Select Data Source page, choose the Import data about the relying party publishing online or on a local network option and enter the Federation Metadata address into the box. Then, click the Next button.

 

Instructure default URL: https://yourcanvasdomain.instructure.com/saml2

If you are using a custom domain for Instructure: https://yourcustomdomain.com/saml2

 

Select Display Name

 

In the Select Display Name page, enter the name of your relying party in the Display name field. This is the name that will show up in the trust list. The content of the name does not affect functionality. Note that this display cannot be edited in the future. Then, click the Next button.

 

I do not want to configure multi-factor authentication settings for this relying party trust at this time

 

In the Configure Multi-Factor Authentication Now? page, leave the I do not want to configure multi-factor authentication settings for this relying party trust at this time option checked and click the Next button.

 

Choose Issuance Authorization Rules

 

In the Choose Issuance Authorization Rules page, leave the Permit option checked and click the Next button. In the Ready to Add Trust page, click the Next button.

 

In the Ready to Add Trust page, click the Next button.

 

Open the Edit Claim Rules dialog for this relying party trust when the wizard closes

 

In the Finish page, make sure the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes check box is selected, then click the Close button.

 

Add Rule

 

Click the Add Rule button.

 

Send LDAP Attributes as Claims

 

In the Claim rule template drop-down menu, select the Send LDAP Attributes as Claims option, then click the Next button.

 

Configure Rule

 

Populate the screen as shown above; the Active Directory must already be set up in the AD FS Attribute Stores section to be used here.


Note that the Claim rule name "UPN = Name ID" is only an example. This is for display inside ADFS only and you will likely want to change it to fill your setup.
This screen is mapping Active Directory LDAP attributes to standard SAML outgoing attributes that the Canvas SAML server will be able to map on its side. Please note we use User-Principal-Name but your institution might use a different value to login that we do.


Click the Finish button.

 

Relying Party Trust Properties

 

Find the Relying Party Trust in the AD FS list of trusts, then select the Properties option in the right menu. Click the Encryption tab, then click the certificate View button.

 

Install Certificate

 

Click the Install Certificate button.

 

Certificate Import Wizard

 

In the Welcome to the Certificate Import Wizard page, select Local Machine click the Next button.

 

Certificate Store

 

In the Certificate Store page, select the default option, then click the Next button.

 

Completing the Certificate Import Wizard

 

In the Completing the Certificate Import Wizard page, click the Finish button.

 

The import was successful

 

Click the OK button.

 

Properties Tab

 

Navigate back to the Encryption tab of the properties window. Click the Apply button, then click the Advanced tab.

 

Secure Hash Algorithm

 

In the Advanced tab, set the Secure Hash Algorithm to SHA-1. Apply any changes and close out of the properties window.

 

Thumbprint Value

 

Under AD FS > Service > Certificates, the SSL certificate information should be listed. Double-click the certificate and located the Signing Certificate. Click the Details tab to see a long list of fields & values from your certificate. Scroll down until you find the Thumbprint field and write down the value. You may notice that the Thumbprint Algorithm is sha1; if it is sha256 you may need to adjust the previous step. Make sure you have the Thumbprint value written down as it is needed in Canvas.

 

Configure Canvas to work with the ADFS 3.0/4.0 server

To configure ADFS 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.

 

Configure the fields on this screen as follows:

IdP Entity ID

Required. An entity ID is a globally unique name for a SAML entity, either an Identity Provider (IdP) or a Service Provider (SP).

 

in almost all cases, an entity ID is an absolute URL but it's important to note that an entity ID is a name, not a location. That is, an entity ID need not resolve to an actual web resource.

Log Out URL

https:// your.adfserverurl.com /adfs/ls/

Note: This URL will require the user to close their browser to end their session, but will take them back to your ADFS server’s log out page where you can display a warning about this.

Change Password URL

URL to redirect users to to change their password inside ADFS.

Certificate Fingerprint

SSL Certificate Thumbprint for your ADFS server that we wrote down in a previous step.

Login Attribute

Should match what you selected in the Claim Rule setup, in our case it was User-Principal-Name > Name ID.

Identifier format

Usually set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Authentication Context

No Value

Login Label

Enter a label for 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:

Enter a URL that a user will be 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.

Position

1

 

Configure ADFS/SAML in Canvas Authentication

Learn how to configure authentication in Canvas.

Was this article helpful? Yes No


Have a question about Canvas? Ask in the Q&A forum:
Embed this guide in your Canvas course:

Note: You can only embed guides in Canvas courses. Embedding on other sites is not supported.