|
Official Canvas Document |
 |
- Background
- Authentication Terminology
- Prerequisites
- Test and Beta Canvas Sites
- Login Release Valve
- Configuring ADFS 2.0 with Canvas
- Set up a Relying Party Trust and Claim Rules for Canvas
- Setup ADFS Single LogOut Workaround
- Configure Canvas to work with the ADFS 2.0 server
- Configure ADFS Single Logout Workaround
- Configure ADFS/SAML in Canvas Authentication
- Configuring ADFS 3.0 or 4.0 with Canvas
- Set up a Relying Party Trust and Claim Rules for Canvas
- Configure Canvas to work with the ADFS 3.0/4.0 server
- Configure ADFS/SAML in Canvas Authentication
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.
- Set up a Relying Party Trust and Claim Rules for Canvas
- Set up ADFS Single LogOut Workaround
- Configure Canvas to work with your ADFS 2.0 server
- Configure ADFS Single LogOut Workaround
- Configure ADFS 2.0 Forms Authentication Login Page Instead of Windows Authentication Prompt
- 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 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
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.
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 check box 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, chose Local Machine and 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 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.
- Set up a Relying Party Trust and Claim Rules for Canvas
- Configure Canvas to work with your ADFS 3.0/4.0 server
- 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
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://yourcanvasdomain.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. The 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 check box 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 "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 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 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 |
