Learning Management Systems (LMS) like Blackboard, Moodle, Canvas, and BrightSpace's Desire2Learn all support a protocol called Learning Tools Interoperability (LTI) which can be used to connect learning tools like WeBWorK to the LMS in a standardized fashion.

This page documents how to setup LTI authentication for WeBWorK 2.18 and beyond. For prior versions of WeBWorK see https://webwork.maa.org/wiki/LTI-Advanced_Authentication.

LTI Authentication

Before you can use WeBWorK's LTI features you need to do some initial setup. This will need to be done by a system administrator and in particular often requires administrator access to both WeBWorK and your Learning Management System.

First Time WeBWorK Setup

Start by making a copy of the distribution configuration file needed with the following command.

cp /opt/webwork/webwork2/conf/authen_LTI.conf.dist /opt/webwork/webwork2/conf/authen_LTI.conf

In localOverrides.conf uncomment the line that reads #include("conf/authen_LTI.conf"); by removing the # from the beginning of the line.

Now determine if you will be using LTI version 1.1 or 1.3. Note that both versions can be used by one WeBWorK server for different courses if needed.

If you will be using LTI 1.1, then uncomment the line in authen_LTI.conf that reads #include('conf/authen_LTI_1_1.conf'); by removing the # from the beginning of the line and copy the LTI 1.1 distribution configuration file with

cp /opt/webwork/webwork2/conf/authen_LTI_1_1.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_1.conf

If you will be using LTI 1.3, then uncomment the line in authen_LTI.conf that reads #include('conf/authen_LTI_1_3.conf'); by removing the # from the beginning of the line and copy the LTI 1.3 distribution configuration file with

cp /opt/webwork/webwork2/conf/authen_LTI_1_3.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_3.conf

Note that all WeBWorK LTI configuration variables that do not have a $LTI{v1p?} prefix are in the authen_LTI.conf file, and are used by both versions of LTI. All variables that have the $LTI{v1p1} prefix are in the authen_LTI_1_1.conf file, and are only used by LTI 1.1. All variables that have the $LTI{v1p3} prefix are in the authen_LTI_1_3.conf file, and are only used by LTI 1.3.

The followed are the variables defined in authen_LTI.conf. Some of these are described in more detail later in this document.

$debug_lti_parameters: Set this to 1 to enable debugging. Getting LTI authentication set up can be tricky, and this can with troubleshooting the issues. Note that for LTI 1.1 most of these messages are displayed in the browser, but for LTI 1.3 you will need to inspect the logs/webwork2.log file to see the error messages. Make sure to set this back to 0 for production use.

$debug_lti_grade_passback: Set this to 1 to get debugging information when using grade pass back. As with the previous option, the messages for LTI 1.1 are displayed in the browser, but most LTI 1.3 messages will be in the logs/webwork2.log file. Make sure that this is also set to 0 for production use.

$authen{user_module}: This is a list of authentication modules in the order that they will be considered when a request is received by WeBWorK. Usually you will not need to modify this from the default values.

$authen{admin_module}: This is a list of authentication modules tha are allowed for signing in to the admin course. By default only "WeBWorK::Authen::Basic_TheLastOption" is allowed, which means that only username and password sign in is allowed. If you want to allow signing in to the admin course via LTI, then you can uncomment "WeBWorK::Authen::LTIAdvantage" (for LTI 1.3) or "WeBWorK::Authen::LTIAdvanced" (for LTI 1.1). This is not recommended.

$LTIVersion: Set this to the LTI version that the courses on your server will be using. This is either "v1p1" for LTI version 1.1, or "v1p3" for LTI version 1.3. This can also be set in a course's course.conf file to make a course use a different LTI version than the site wide default.

$LTIAccountCreationCutoff: WeBWorK will automatically create users when logging in via the LMS for the first time for users with a permission level below what this is set to. This is set to "ta" by default.

$LMSManageUserData: If set to 1 (the default setting), then WeBWorK's user demographic data will be kept up to date with the data from the LMS.

$external_auth: If set to 1, then the username and password fields will not be displayed on the WeBWorK login page. Instead a message will be shown informing users to sign in via the LMS. This is set to 0 by default.

$LTIGradeMode, $LTIGradeOnSubmit, $LTICheckPrior, and $LTIMassUpdateInterval: These are for grade passback. Details on these will be given later in this document.

@LTIConfigVariables: If any of the listed variables are uncommented, then an "LTI" tab will be available on the "Course Configuration" page in courses. The settings for the uncommented variables can be changed for an individual course by the instructor in that tab.

Next follow the instructions for the LTI versions that will be used by your server below.

LTI 1.3 Setup

LTI 1.3 LMS Configuration

First the LMS needs to be configured to use LTI 1.3 authentication. Follow the instructions for your LMS below.

Moodle

Set the external tool configuration settings as shown in the screen shots below. Make sure to change https://webwork.yourschool.edu to the URL for your webwork2 server. You can use a different "Tool name" and add a "Tool description" that is appropriate for you. Note that the "Content Selection URL" is needed for version 4.02 or newer of Moodle in order for instructors to add WeBWorK assignment links to their courses. Make sure to follow the instructions for this later in this document. Older versions of Moodle allow manual link creation.

View the configuration details for the external tool that is created after saving the changes by clicking on the list icon in the top right corner of the created tool. It will look something like the following screenshot. Save these details for the WeBWorK configuration later.

The shown values in the order shown will be the values for the variables $LTI{v1p3}{PlatformID}, $LTI{v1p3}{ClientID}, $LTI{v1p3}{DeploymentID}, $LTI{v1p3}{PublicKeysetURL}, $LTI{v1p3}{AccessTokenURL}, and $LTI{v1p3}{AuthReqURL}, respectively, in the authen_LTI_1_3.conf file. The "Access token URL" will also be the value for the $LTI{v1p3}{AccessTokenAUD} variable.

Canvas

First, a user that has admin privileges in Canvas must create a developer key. On the developer keys page click "+ Develop Key" and select "LTI Key". Set the key settings as shown in the following screen shots. Make sure to change https://webwork.yourschool.edu to the URL of your server. You can use a "Key Name", "Title", and "Description" that are appropriate for you.

Note that some of the following services may not be needed, but I am not sure which ones are so just check them all!

Under "Additional Settings" add the "Domain" of your WeBWorK server and make sure the "Privacy Level" is set to "PUBLIC".

Add the "Assignment Selection" placement as shown below if you want to be able to utilize content selection. Note that this only allows importing a single WeBWorK assignment at a time, and will be available when creating an external tool assignment.

If the "Course Assignments Menu" placement is available, then you may want to add that as well. This will allow importing multiple assignments from WeBWorK at once, and will add a menu item in the "Assignments Settings" drop down menu on the "Assignments" page. The settings for this placement are the same as for "Assignment Selection" shown in the screen shot. Note that this is an experimental feature in Canvas at this time, and must be turned on for your institution through your Canvas customer success manager.

For both placements you can use a different "Text" if you like. This is the text that will describe the placement in the menus when the placement is used. You may also want to set the selection height and width. Those are the height and width of the dialog that opens and displays the available WeBWorK assignments for the course when content selection is used by the instructor.

You can remove any other placements. WeBWorK does not support any of the others at this time.

After saving the developer key you will see the following. Make note of the long number above the "Show Key" button in the details column. That is the client id which will be needed in the next step and will be the value for the $LTI{v1p3}{ClientID} in the WeBWorK authen_LTI_1_3.conf file.

Now go to "Settings" and select the "Apps" tab. Click on "+ App" and select "By Client ID" for the "Configuration Type". Enter the client id from above as shown below. Then click "Submit".

After submitting Canvas will return to the "Apps" tab in "Settings". Find the app you just created and click on the gear icon drop down menu to the right. Select "Deployment ID" and save the deployment ID that is shown. This will be the value for the $LTI{v1p3}{DeploymentID} in the WeBWorK authen_LTI_1_3.conf file.

The other variables that will need to be set in the authen_LTI_1_3.conf file are as follows:

$LTI{v1p3}{PlatformID}: Either 'https://canvas.instructure.com' or 'https://yourschool.instructure.com' (It is not known at the time of this writing which this will need to be in production.)
$LTI{v1p3}{PublicKeysetURL}: 'https://yourschool.instructure.com/api/lti/security/jwks'
$LTI{v1p3}{AccessTokenURL}: 'https://yourschool.instructure.com/login/oauth2/token'
$LTI{v1p3}{AccessTokenAUD}: 'https://yourschool.instructure.com/login/oauth2/token'
$LTI{v1p3}{AuthReqURL}: 'https://yourschool.instructure.com/api/lti/authorize_redirect'

Brightspace (D2L)

A post about LTI 1.3 for Brightspace (D2L) appears at https://sukhjitsehra.github.io/webwork-2.18/.

LTI 1.3 WeBWorK Configuration

Now configure WeBWorK for LTI 1.3 authentication.

In the authen_LTI_1_3.conf file set the LTI 1.3 basic authentication parameters $LTI{v1p3}{PlatformID}, $LTI{v1p3}{ClientID}, $LTI{v1p3}{DeploymentID}, $LTI{v1p3}{PublicKeysetURL}, $LTI{v1p3}{AccessTokenURL}, $LTI{v1p3}{AccessTokenAUD}, $LTI{v1p3}{AuthReqURL} to the values found in the LMS configuration above.

Set $LTIVersion = 'v1p3'; in authen_LTI.conf. You may instead set this in the course.conf files of the courses that you want to use LTI 1.3 for, leave $LTIVersion = 'v1p1'; in authen_LTI.conf if most of the courses on your server will be using LTI 1.1.

There are some other options that can be set as well. Some of these are discussed in more detail in other sections of this document.

$LTI{v1p3}{LMS_name}: This is a string that is used to name the LMS for end users. It is used in messages displayed for users by WeBWorK.

$LTI{v1p3}{LMS_url}: This is a URL that should take users to a place they can log in to their LMS. It is also used in messages displayed for users by WeBWorK together with the LMS_name above.

$LTI{v1p3}{preferred_source_of_username}: When a user logs into WeBWorK from the LMS WeBWorK needs to determine the username of the person logging in. This determines which parameter sent from the LMS to use for the WeBWorK username. This is "email" by default, but can be set to any parameter included in the JWT sent from the LMS that uniquely identifies users.
- You can set $debug_lti_parameters = 1 in authen_LTI.conf to help find which parameter to use for this.
- If this variable is set to "email", then by default the entire email address is used. If you don't want to use the entire email address you can also set $LTI{v1p3}{strip_domain_from_email} = 1 and WeBWorK will remove the domain name from the email address when creating the username.

$LTI{v1p3}{fallback_source_of_username}: If the parameter set for $LTI{v1p3}{preferred_source_of_username} is not present in the JWT sent from the LMS, then the parameter set for this variable will be used instead if it is present in the JWT. This is not set by default.

$LTI{v1p3}{lowercase_username}: If set to 1, then all usernames (as determined by the options above) will be converted to lowercase.

$LTI{v1p3}{preferred_source_of_student_id}: The parameter sent from the LMS to use for the WeBWorK student id. This is optional and is not set by default.
- You can set $debug_lti_parameters = 1 in authen_LTI.conf to help find which parameter to use for this.

$LTI{v1p3}{StateKeyLifetime}: When the WeBWorK responds to an initial LMS request it includes state and nonce values in that request. These values are saved in the database until the response from the LMS to that request is received. This variable controls how long in seconds this data will be saved in the database before it is considered stale and deleted. It should be short enough to accomodate normal server and networking delays. Note that if authentication is successful this will be deleted before this lifetime expires in any case. This is only to ensure that keys from failed authentication attempts don't pile up in the database.

$LTI{v1p3}{LMSrolesToWeBWorKRoles}: This is a mapping of roles used by the LMS to WeBWorK roles. Add roles to this if your LMS uses a role that is not present in the mapping already.

$LTI{v1p3}{modify_user}: This can be set to a routine that can modify the student id and other user data when a user signs in from the LMS.

$LTI{v1p3}{modify_user_set}: When users are added to the system they are also assigned all visible sets. This can be set to a routine that can modify the sets before they are assigned.

LTI 1.1 Setup

LTI 1.1 WeBWorK Configuration

In authen_LTI_1_1.conf set $LTI{v1p1}{BasicConsumerSecret}. This acts like a global password and is used to authenticate all communication between WeBWorK and the LMS. So pick something secure.

Set $LTIVersion = 'v1p1'; in authen_LTI.conf (this is the default setting). You may instead set this in the course.conf files of the courses that you want to use LTI 1.1 for, and set $LTIVersion = 'v1p3'; in authen_LTI.conf if most of the courses on your server will be using LTI 1.3.

There are some other options that can be set as well. Some of these are discussed in more detail in other sections of this document.

$LTI{v1p1}{LMS_name}: This is a string that is used to name the LMS for end users. It is used in messages displayed for users by WeBWorK.

$LTI{v1p1}{LMS_url}: This is a URL that should take users to a place they can log in to their LMS. It is also used in messages displayed for users by WeBWorK together with the LMS_name above.

$LTI{v1p1}{preferred_source_of_username}: When a user logs into WeBWorK from the LMS WeBWorK needs to determine the username of the person logging in. This determines which parameter sent from the LMS to use for the WeBWorK username. This can be lis_person_sourcedid, lis_person_contact_email_primary (the default), or another parameter sent from the LMS that uniquely identifies users. This setting is required.
- If this variable is set to "lis_person_sourcedid" then the sourced_id will be used as the WeBWorK username. Note: The LMS may not provide this parameter, and if it is provided it is usually an obscure identifier that is likely not a good choice for a username.
- If this variable is set to "lis_person_contact_email_primary" then the email address provided by the LMS will be used for the WeBWorK username.
  - By default the entire email address is used. If you don't want to use the entire email address you can also set $LTI{v1p1}{strip_domain_from_email} = 1 and WeBWorK will strip off the server portion of the email address when creating the username.
- You can set $debug_lti_parameters = 1 in authen_LTI.conf to help find which parameter to use for this.

$LTI{v1p1}{fallback_source_of_username}: If the parameter set for $LTI{v1p1}{preferred_source_of_username} can not be found, then the parameter set for this variable will be used instead if it can be found in the parameters. This is not set by default.

$LTI{v1p1}{lowercase_username}: If set to 1, then all usernames (as determined by the options above) will be converted to lowercase.

$LTI{v1p1}{preferred_source_of_student_id}: The parameter sent from the LMS to use for the WeBWorK student id. This is optional and is not set by default.
- You can set $debug_lti_parameters = 1 in authen_LTI.conf to help find which parameter to use for this.

$LTI{v1p1}{NonceLifeTime}: When the LMS sends a user to WeBWorK it makes a request identified by a "Nonce". This variable controls how long the Nonce is valid, in seconds, from the time it is created by the LMS. It should be short enough to prevent "casual" man-in-the-middle attacks. However, you may need to set it to something longer if your servers/network are slow or if the clocks on your servers are not synced.

$LTI{v1p1}{OverrideSiteURL}: When the authentication request is being validated WeBWorK will check to see if the address that the user clicked in in the LMS is the same as the address of the WeBWorK server. If you have a load balancing system where the WeBWorK server address may not be the same as the address the student clicked on in the LMS then you may need to set this variable to the address in the LMS.

$LTI{v1p1}{OverrideSiteProtocolDomain}: This is similar to the $LTI{v1p1}{OverrideSiteURL} except that only the protocol (http or https) and host name portion of the URL given here are substituted for the protocol and host name of the request, leaving the URL path in the request the same.

$LTI{v1p1}{modify_user}: This can be set to a routine that can modify the student id and other user data when a user signs in from the LMS.

$LTI{v1p1}{modify_user_set}: When users are added to the system they are also assigned all visible sets. This can be set to a routine that can modify the sets before they are assigned.

LTI 1.1 LMS Configuration

Next you need to configure your LMS. In general you will need to provide the LMS the following things:

The address of your WeBWorK server. Note: The address here needs to exactly match the address of your webwork server as defined in site.conf, i.e., it should be the combination of $server_root_url and $webwork_url
The "Tool Provider Key" or "Consumer Key". This is just some made up word, like "webwork" or "smargleborg".
The "Tool Provider Secret" or "Consumer Secret". This is the password used to identify the LMS to your WeBWorK site (and vice versa) and should be the same as $LTI{v1p1}{BasicConsumerSecret}.
What user information is submitted to WeBWorK.

The specifics in setting up the LMS vary depending on which LMS you use. Instructions for Blackboard, Moodle, Canvas, and BrightSpace's Desire2Learn are below. An instructor can perform these instructions at the course level, and this will apply to only that course, or an LMS administrator can do this at the system level so that it applies to all courses on the system.

You can also try to have the LMS provide section or recitation information by setting a custom parameter. In all of the configurations there is a "Custom Fields" section. You would specify "section = #" or "recitation = #" to set the section or recitation.

Blackboard

In the Administrator Panel (under Building Blocks) click LTI Tool Providers and then Register Provider Domain
Input the address of the WeBWorK server in Provider Domain
Use Set Globally for Default configuration and input the Tool Provider Key (any word, e.g. webwork) and the Tool Provider Secret ($LTI{v1p1}{BasicConsumerSecret})
Enable Send User Data. (Restricting to ssl is safer if you have https enabled.) Then enable all three user fields.