LTI Authentication (for WeBWorK 2.18 or newer)

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 (for both LTI versions)

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 conf/localOverrides.conf uncomment the line that reads #include("conf/authen_LTI.conf"); by removing the # from the beginning of the line.

Now determine which version of LTI you will be using, either LTI 1.1 or LTI 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 conf/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 conf/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

There are some other options in conf/authen_LTI.conf that can be set as well. They are as follows:

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

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

• $LMSManageUserData: If set to 1, 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 users will not be able to log in to the course directly, but will be required to access the course via links in the LMS. The login page shows a message that directs users to login through the LMS. Note that if this is set to 1, then you may also want to set $permissionLevels{change_password} = 'ta' to prevent students from changing passwords (since they can't be used anyway).
  • IMPORTANT: This prevents ALL users from logging with a username and password including instructors and TAs. For this reason, you may want to set $external_auth = 0; which allows username and password sign in. Students will not be able to login to webwork directly unless a password is created for them, and it may be necessary to inform them (possibly repeatedly) that they can only log in to WeBWorK through the LMS.

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

Note that there are some other variables not described here that are described in other sections of this document.

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 conf/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. 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 conf/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 conf/authen_LTI_1_3.conf file.

The other variables that will need to be set in the conf/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 conf/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.

There are some other options that can be set as well.

• $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 conf/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 conf/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 conf/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 reasonably complicated.

There are some other options that can be set as well.

• $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 conf/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 conf/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 set up 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, e.g. 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 $LTIBasicConsumerSecret.
• What kind of user information is provided to WeBWorK.

The specifics in setting up the LMS vary depending on what LMS you use. Instructions for Blackboard, Moodle and Canvas are below. Note, when the instructions refer to the "LTI" or "Tool", that is WeBWorK. A couple of other things to think about:

• Its usually best to have WeBWorK open in a new window. There are usually settings you can set which will control this. However feel free to experiment with other settings until you find a mode you like.
• If you want to get fancy 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

The instructions are here. Brief instructions and a screenshot follow.

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

Moodle

The instructions are here. Basic instructions and a screenshot follow

1. Go to Site administration > Plugins > Activity modules > LTI > Manage external tool types and click "Add External Tool Configuration"
2. Input the Tool Name and the WeBWorK server address as the Tool Base URL
3. Input the Consumer Key (any word e.g. webwork) and the Shared Secret (e.g. $LTIBasicConsumerSecret).
4. In Privacy set both "Share" configurations to "Always". If you have https available its safer to also enable "Force SSL".

Canvas

The instructions are here. The basic instructions and a screenshot follow.

1. Go to Settings > Apps > View App Configurations > Add App
2. Choose "Manual Entry" for configuration type.
3. The "Launch URL" is the url of the course and can be left blank. The "Domain" is just the server address
4. Input the Consumer Key (any word e.g. webwork) and the Shared Secret (e.g. $LTIBasicConsumerSecret).
5. You should set "Privacy" to "Public".

Warning: A recent Canvas security related change prevents copying the LTI key and LTI consumer secret when course content is copied to a new course. Those values need to be set again manually in the new course. See: the forum post by Tim Payer.

Desire2Learn (D2L) BrightSpace

See LTI-Advanced_Authentication_for_D2L

Adding Links To WeBWorK

Once you have set up your WeBWorK configuration files and added WeBWorK as an LTI Tool to your LMS you will need to make a link/assignment in the LMS that students can use to get to WeBWorK. This needs to be done in every LMS course which uses WeBWorK. Again, the process for this varies depending on what LMS you are using. I'll describe the basic process for Moodle, Blackboard and Canvas. Be aware that each LMS has its own quirks and possibilities. In some LMS you can make a link in the side bar as a "course tool", or as a "module", or add it to the navigation bar. In some LMS the links go in the "Content Area". In some LMS the links go in the "Assignment List". Consult your LMS documentation for a full description on where and how LTI links can be included. A couple of other things to think about:

• Its usually best to have WeBWorK open in a new window. There are usually settings you can set which will control this. However feel free to experiment with other settings until you find a mode you like.
• If you want to get fancy 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

The documentation is here. A screenshot and basic instructions follow.

1. Go to Conent > Build Content > (Create) Web Link
2. Add a Name for your link and the URL of the course you are linking to. You can get the url using "copy link location" on the link to the course in the main WeBWorK page. Alternatively the url structure is: http://webwork.server.edu/webwork2/CourseName
3. Check "This link is a Tool Provider"*

• You may need to enable "LTI" in Customization => Tool Availability if the checkbox for "This link is a Tool Provider" is not shown

Moodle

The documentation is here. A screenshot and basic instructions follow.

1. Go to a Course, Turn "Editing" on, and click "Add an activity or resource".
2. Choose "External Tool" and click "Add".
3. Pick an activity name and add the URL of the course you are linking to. You can get the url using "copy link location" on the link to the course in the main WeBWorK page. Alternatively the url structure is: http://webwork.server.edu/webwork2/CourseName

Canvas

The documentation is here. A screenshot and basic instructions follow.

1. Go to your Course, then Assignments, then add an assignment.
2. Select "External Tool" for Submission type.
3. Input the URL of the course you are linking to. You can get the url using "copy link location" on the link to the course in the main WeBWorK page. Alternatively the url structure is: http://webwork.server.edu/webwork2/CourseName

Warning: A recent Canvas security related change prevents copying the LTI key and LTI consumer secret when course content is copied to a new course. Those values need to be set again manually in the new course. See: the forum post by Tim Payer.

Automatic Student Account Management

WeBWorK can be configured to automatically manage and create student accounts in WeBWorK. In particular if a student does not have an account in WeBWorK then the first time they log in a WeBWorK account will be created for them. The username will be determined by $LTI{v1p?}{preferred_source_of_username} (see above for the details) and they will automatically be assigned all "visible" homework sets.

Now you should be all set up. You can test it out by creating a test student in your LMS and using the link to log into WeBWorK from the LMS. Logging into WeBWorK in this way should not require a password, the WeBWorK user for the student should be automatically created, and the user should also automatically be assigned all "visible" homework sets. In particular you should keep the following in mind about automatic account creation.

• Students created via the LMS will not have a password. In particular they will not be able to sign into WeBWorK directly. The variable $external_auth is set to 0 by default, and the username and password fields are displayed on the WeBWorK login page. This can be confusing to students, since they still will not be able to sign in. So you may want to change $external_auth to 1. In that case the username and password fields will not be displayed on the WeBWorK login page, and instead a message will be shown that directs users to login through the LMS (the $LTI{v1p?}{LMS_name} and $LTI{v1p?}{LMS_url} variables are used for this).
• On the other hand setting $external_auth = 1; prevents ALL users from signing into WeBWorK directly including instructors and TAs. For this reason you may want to set $external_auth = 0; to allow direct sign in to WeBWorK. Students still will not be able to sign in to webwork directly unless a password is created for them. So it will be necessary to inform them that they can only log in to WeBWorK through the LMS, and that the username and password fields on the login page will not work for them.
• Note that if $external_auth is set to 1, then you may also want to set $permissionLevels{change_password} = 'ta' to prevent students from changing passwords (since they usually can't be used anyway).

• Accounts with a permission level of TA or higher are not automatically created by default for security reasons. So you will have to add your TA's and other professors manually.
• Students created via the LMS are assigned all visible sets. However, the due dates of these sets are not adjusted to take late registrations into account unless you get fancy.
• ADVANCED: You can define the local routines which can be used to modify newly created users and newly assigned sets. For example, you can give newly created users a random student_id/password or you can alter the due dates of a student depending on how late they register.

The account creation feature is controlled entirely inside authen_LTI.conf. The important parameters are:

• $LMSManageUserData: WeBWorK will try to keep your student's data up to date with the LMS if this flag is on. Student data doesn't change much so you could turn it off with relatively few side effects.
  • If you enable this feature then you should not let students change their email address, since their changes will constantly be overwritten. To do that set $permissionLevels{change_email} = "ta";.
  • If you use a $LTI{v1p?}{LTI_modify_user} subroutine then you should turn this feature off.

• $LTIAccountCreationCutoff: For security reasons users with permission levels of ta or higher are not automatically created. In other words you will need to manually add professor users to a course before they can log in via the LMS. If you want to allow professors to be created automatically set this variable to 'professor'. If you want to turn off the account creation feature set this variable to 'guest' or 'student'.

• $LTI{v1p?}{LMSrolesToWeBWorKroles}: If your LMS uses roles not listed in this hash you will need to add those roles so that users get the right WeBWorK permission level.

• $LTI{v1p?}{LTI_modify_user}: This is a subroutine which you can use to modify a newly created user before they are actually added to WeBWorK. You would use this if you wanted to, for example, analyze the LTI context parameter for a section number and set the student's section, or create a random string which you set as the student ID and the students password. The basic subroutine looks like:

$LTI{v1p?}{LTI_modify_user} = sub { 
    # The self object from LTIAdvanced.pm or LTIAdvantage.pm
    my $self = shift; 
    # The user object to be modified 
    my $user = shift; 

    # Parse context_id for additional information.  E.G.   
    my @course_id=split /-/, $self -> {"context_id"}; 
    $user->{"section"} = $course_id[4]; 
}; 

• $LTI{v1p?}{LTI_modify_set}: This is a subroutine which you can use to modify newly created sets before they are assigned to users. You would use this if you wanted to, for example, modify the due date of the set before it is assigned, adding extra days based on the number of sets assigned. The basic subroutine looks like:

$LTI{v1p?}{LTI_modify_user_set} = sub { 
    # The self object from LTIAdvanced.pm or LTIAdvantage.pm
    my $self = shift; 
    my $globalSet = shift; 
    # The userSet object to be modified 
    my $userSet = shift; 
    my $numberOfSetsAssigned = $self->{numberOfSetsAssigned}; 
    my $daysPerSetMakeup = 2; 
    my $reasonableNumberOfDays = $numberOfSetsAssigned*$daysPerSetMakeup +1; 
    if ($reasonableNumberOfDays < 2) {$reasonableNumberOfDays = 2;} 
    my $niceDueTime = $globalSet->due_date + $reasonableNumberOfDays*86400; 
    my $niceAnswerTime = $niceDueTime + 600; 
    $userSet->due_date($niceDueTime); 
    $userSet->answer_date($niceAnswerTime); 
};

Additional Authentication Setups

Students created via the LMS will not have neither a student id nor an initial password. In particular they will not be able to log into WeBWorK directly. The $external_auth is set to one by default and actually prevents them from seeing the WeBWorK login page. They will need to log in via the LMS unless you get fancy. In particular since they are not allowed to log in to WeBWorK directly you should consider setting $permissionLevels{change_password} = "ta";. This will prevent students from messing with their WeBWorK password. If you do want to allow students to log into WeBWorK directly you have a couple of options.

• Native WeBWorK Logins - Set $external_auth to zero and give students permission to change their password. Students will not have a password by default and will not be able to log in via WeBWorK. However if they use the User Settings page to give themselves a password then they can log in via WeBWorK.

• LDAP Logins - If your LMS uses an LDAP system for authentication you can also set up WeBWorK to use LDAP authentication (see LDAP Authentication). When set up properly this will allow students to log into WeBWorK using their LDAP/LMS credentials (once their account is created in WeBWorK, of course). To do this you should first comment out the following lines in authen_ldap.conf

   #$authen{user_module} = {
   #	"*" => "WeBWorK::Authen::LDAP",
   #};

In authen_LTI.conf you should change the definition of $authen{user_module} to

   $authen{user_module} = [ 
       {  "*" => "WeBWorK::Authen::LTIAdvanced", }, #preferred authorization method
       {  "*" => "WeBWorK::Authen::LDAP",}  #fallback authorization method
   ];

You should also make sure that $external_auth is set to zero.

Make LTI connections for a single course

• LTI -- The LTI connection between Canvas, Blackboard, Moodle and WeBWorK was introduced in release 2.12 but best practices for configuring the connection are still emerging.

• In webwork2/conf make a copy authen_LTI.conf from authen_LTI.conf.dist if you haven't done so already.
• In localOverrides.conf make sure that authen_LTI.conf is enabled and set global settings for the grading mode and debugging:

   include("conf/authen_LTI.conf");
  $debug_lti_parameters = 0; 
  $LTIGrademode=“”;

• At the end of course.conf for the course using LTI place these statements:

   # Settings to connect this course to 	Canvas via  LTI.
   $LTIGradeOnSubmit = 1;      # or 0 if grade pass-back is not used
   $debug_lti_parameters = 0; # you can set this to 1 for initial setup in order to get additional debugging information
   $LTIBasicConsumerSecret = "XXXsecretXXX";
   $LTIGradeMode = "homework";
   $external_auth = 0;  # this allows both LTI and direct authorization to work simultaneously (use carefully, LTI registered students who try to
                                    # login directly will be told they have an incorrect password since LTI creates a random practice that is never used. 
                                    # instructors will be able to login directly

• • • For more details read Goeff Goehle's blog posts ([1]) and the comments in authen_LTI.conf.dist, and LTIAdvanced.pm

Grade Pass-back

There is an optional subsystem for allowing WeBWorK to pass grades back to the LMS. You can read more about that at LTI-Advanced Grading

Gotchas

• I set $debug_lti_parameters to one but I don't see any debugging info. This means that the LTI authentication module is not getting called, or is getting called without parameters.
  • The LTI parameters are only set in the 'initial' login. Make sure you log out of WeBWorK before trying to log back in via the LMS.
  • If you have multiple authentication plugins activated make sure that $authen{user_module} is not getting overwritten by a different authentication module.
  • If you have https and are forwarding http calls to https, make sure that the link in the LMS is https.
• I get an "OAuth verification failed" error. This means that WeBWorK cannot verify the authentication request sent by the LMS. This usually means that you have trouble with either the consumer secret or your WeBWorK address.
  • Double check that your consumer secrets are the same.
  • Double check that your urls match. In particular the URL you put in the LMS has to match the server url defined in site.conf, localOverrides.conf, and authen_LTI.conf. For example, if you have an "https" in the URL in the LMS then you should have an "https" in the value of $server_root_url.
• I get an "LTIAdvanced was unable to create a username from the user_id or from the mail address." error. WeBWorK uses either the parameter "lis_person_sourcedid" or the parameter "lis_person_contact_email_primary" to build the user id. If neither of these are present the system will fail. Make sure the "privacy" mode is set to "public" (or the most permissive setting) in the LMS to guarantee that it is sending enough info for WeBWorK to create a user.
• I get an "Your authentication failed. Please try again. Please speak with your instructor if you need help." in Canvas, after copying a course to a new semester.