Configuring Microsoft OAuth for Canvas Authentication

[#1]

Overview

This article describes the process of configuring Microsoft’s OAuth protocol as an Identity Provider (IdP) ready to work with Canvas. 

Authentication Terminology

Term	Definition
Entra ID	Microsoft Entra ID is a cloud-based identity and access management service used to access external resources. Example resources include Microsoft 365, the Azure portal, and thousands of other SaaS applications.
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. Microsoft 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.
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.  Users will be logged out of Canvas but will not be logged out of Microsoft.
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.
Tenant	A tenant within Microsoft represents your organization and helps you to manage a specific instance of Microsoft Cloud services for your internal and external users.

Pre-requisites

• Your organization must be using Microsoft Entra ID.

• You likely will need to be able to log in to the Microsoft Entra ID admin console for your organization.

• Unless you plan on using the Just in Time Provisioning feature, users must be created ahead of time with a login_id and an authentication_provider_id of “microsoft” (or the explicit id numeric value of the auth provider) before they will be able to login using the Microsoft Authentication method. See SIS Import Files documentation for more information

• The login_id field in Canvas must match the selected “Login Attribute” claim returned from a successful Microsoft login response.

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: https://<YOURDOMAIN>.instructure.com/login/canvas (This forces Canvas to display the local login page rather than redirecting to the SAML login page).

Configure Microsoft OAuth

1. In Canvas, select Microsoft OAuth authentication by going to the Root Account of your Canvas Instance, selecting the Authentication tab on the left nav, and select Microsoft from the “Add an identity provider to this account” drop-down menu on the right.   

Set Tenants

Canvas requires at least 1 Entra ID tenant id to be populated to establish OAuth connection. How to find your Microsoft Entra tenant ID.

1. Enter at least one Entra ID tenant ID in the Tenants field.
• If only a single tenant is populated, the login will direct users to login to the tenant-branded Microsoft login page. Users who are not a part of that tenant will return “User not found.”

1. To allow both institutional tenant and personal microsoft accounts, list both your tenant id and “microsoft” in the Tenants field, separated by commas. 
• This will take users to the “common” microsoft login method that will allow for account discovery. 
• If you have many institutional Entra ID tenants, they may all be listed with commas between them. 

NOTE: All incoming logins from Microsoft will return a tenant id (tid) in the login claim. For security reasons, the value of the incoming tid claim must match one of the configured tenant ids for a user to successfully login (even if the login attribute matches an existing user).

Set Login Attributes

All login attributes from Entra ID logins are potentially modifiable, except  tid and oid. To ensure user accounts cannot be compromised, only use an attribute besides tid+oid if you are certain it cannot be changed by users in all of your allowed Entra ID tenants.

• tid+oid
• Takes the tenant id and oid claims from logins and concatenates them together. 
• sub
• Uses the sub claim from successful logins
• email
• Uses the email claim from successful logins
• old
• Uses the oid claim from successful logins
• preferred_username
• Uses the preferred_username claim from successful logins

Set Just in Time Provisioning

If just in time provisioning is enabled, the configuration must use tid+oid as the login attribute for security reasons.

Set Federated Attributes

As a complement to JIT provisioning (but not dependent on it) all authentication providers support federated attributes. When users log into Canvas, more information beyond just ID is passed to Canvas, and that information is associated with their existing user accounts. 

Select the Canvas attribute value from the dropdown menu and click the “+ Attribute” button.

This will create a new attribute row where you can select the matching provider attribute. In the below example, users, when logging in, will have their name, sis_user_id and emails in Canvas updated to match the incoming Microsoft claims (Provider Attributes). 

Note: changes to the Canvas email attribute will create a new associated email to the user and not replace or remove the old value.

Debugging

Once your Microsoft configuration has been saved, additional options will appear. Click Start Debugging to launch the debugger tool. The debugger will start listening for a login event from Microsoft.

Clicking refresh after Canvas has received an attempted login event from Microsoft will display information about the claims sent as part of the login (including the tid the user login event originated from).