Configuring ADFS (SAML) and Canvas Authentication

Document created by jivedocs@instructure.com Employee on Jun 29, 2015Last modified by Ryan Adamson on Jun 28, 2017
Version 11Show 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. 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.

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

 

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

 

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

 

 

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

 

 

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://yourinstitution.instructure.com/saml2

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

 

 

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. Content of the name does not affect functionality. Note that this display cannot be edited in the future. Then, click the Next button.

 

 

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 Finish page, make sure the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes checkbox is selected, then click the Close button.

 

 

Click the Add Rule button.

 

 

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

 

 

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.

 

 

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.

 

 

Click the Install Certificate button.

 

 

In the Certificate Import Wizard, click the Next button.

 

 

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.

 

 

In the advanced tab, set the Secure Hash Algorithm to SHA-1. Apply any changes and close out of the properties window. Under ADFS 2.0 > Service > Certificates, the SSL certificate information should be listed. Double click the certificate and located the Signing Certif.

 

 

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 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 server
  3. Configure ADFS/SAML in Canvas Authentication

 

Set up a Relying Party Trust and Claim Rules for Canvas

 

 

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

 

 

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://yourinstitution.instructure.com/saml2

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

 

 

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. Content of the name does not affect functionality. Note that this display cannot be edited in the future. Then, click the Next button.

 

 

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.

 

 

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.

 

 

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

 

 

Click the Add Rule button.

 

 

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

 

 

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 "SAM-Account-Name > 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 SAM-Account-Name but your institution might use a different value to login that we do.


Click the Finish button.

 

 

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.

 

 

Click the Install Certificate button.

 

 

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

 

 

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

 

 

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

 

 

Click the OK button.

 

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

 

 

In the Advanced tab, set the Secure Hash Algorithm to SHA-1. Apply any changes and close out of the properties window. Under AD FS > Service > Certificates, the SSL certificate information should be listed. Double click the certificate and located the Signing Certif.

 

 

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

 

Additional Information

The Canvas mobile apps do not support Basic Authentication, Windows Authentication, or Kerberos.  See below for switching to forms-based authentication. 

 

Configure ADFS 2.0 Forms Authentication Login Page Instead of Windows Authentication Prompt

After installing ADFS 2.0 for SharePoint, a Windows login prompt may be shown when the SharePoint site forwarded to the ADFS server instead of the ADFS Forms Authentication login screen.

 

 

The reason for this is that the ADFS website tries to use Windows Authentication before trying to use the Forms authentication which displays the login page below.

 

Use Forms Authentication Login Page Instead of Windows Authentication Prompt

 

ADFS is often configured to use a Windows login prompt as shown below when the user is forwarded to the ADFS server instead of the ADFS Forms Authentication login screen.

 

 

This login screen is not always appropriate and may result in user confusion. It also does not work in the mobile Canvas Apps.

 

Failing to authenticate with the windows authentication prompt will result in a screen like that found below.

 

 

The reason for this is that the ADFS website tries to use Windows Authentication before trying to use the Forms authentication. Forms authentication looks similar to the screen below. It uses a regular HTML page with a form on it for capturing user credentials.

 

 

Forms Authentication

To set up ADFS to use Forms authentication, follow these steps on the ADFS server:

 

1. Open IIS and navigate to Default Website\adfs\ls. Right click and select the Explore option.

 

 

2. Open the web.config file with Notepad, and look for the localAuthenticationTypes section.

 

 

3. Move the line for Forms above the line for Integrated and save the web.config file. This will force the ADFS application to use the Login Page authentication before trying to use Windows Authentication.

2 people found this helpful

Attachments

    Outcomes