View source for LTI Authentication (for WeBWorK 2.17 or older)

Note: This documentation is for a feature scheduled for release in WeBWorK version 2.12

Learning Management Systems (LMS) like Blackboard, Moodle and Canvas all support a protocol called [http://www.imsglobal.org/lti/ Learning Tools Interoperability] (LTI) which can be used to connect learning tools like WeBWorK to the LMS in a standardized fashion.  The most common version is 1.2 and is supported by Blackboard, Moodle, Canvas, and others.  WeBWorK has previously supported LTI based authentication through the LTIBasic module.  That module has been rewritten to include a fuller range of features, including the ability to pass back grades.  This guide includes instructions for the initial configuration and authentication parameters supported by LTIAdvanced.  You can read about the grade passback features at [[LTI-Advanced Grading]].

== First Time Setup ==

=== WeBWorK Setup ===

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.  All of the configuration for WeBWorK is done in the '''authen_LTI.conf''' file located in the '''webwork2/conf''' directory.  First you should copy '''authen_LTI.conf.dist''' to '''authen_LTI.conf'''.  Then you need to uncomment the line

    #include("conf/authen_LTI.conf");

in '''localOverrides.conf'''.  Now there are some things you will need to do in '''authen_LTI.conf'''.  The only thing you must set is the LTI Consumer Secret.  This acts like a global password and is used to authenticate all communication between WeBWorK and the LMS.  So pick something reasonably complicated.

    $LTIBasicConsumerSecret = ""; #This must be set 

There are some other options that can be set as well.  I'll go through them in order of most things you will most likely need to think about to less likely.

* '''$debug_lti_parameters''' - Getting things set up for the first time can be tricky and the error messages are kept vague by default (for security).  Set this flag to 1 to have WeBWorK split out a lot more information about the LTI authentication process.  This can be a big help with troubleshooting.

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

* '''$preferred_source_of_username''' - When a user logs into WeBWorK from the LMS WeBWorK needs to determine the username of the person logging in.  The default is to use the email address of the student logging in as their user name.  This is because many/most LMS do not actually provide a traditional username (also called a "sourcedid").  This variable controls if the email or the sourcedid is used as the username for the student in WeBWorK.  
** If this variable is set to "lis_person_sourcedid" then the sourcedid is used as the WeBWorK username.  Note:  Many LMS do not provide this parameter. 
** If this variable is set to "lis_person_contact_email_primary" then webwork will use the entire email address as the username.  If you don't want to use the entire email address you can also set '''$strip_address_from_email=1''' and WeBWorK will strip off the server portion of the email address when creating the username. 

* '''$LTIBasicToThisSiteURL''' -  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 will need to set this variable to the address in the LMS.  

=== LMS Setup ===

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, up to an including http vs https.  
* 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.  I've posted links to setup instructions for Blackboard, Moodle and Canvas 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 [https://en-us.help.blackboard.com/Learn/9.1_2014_04/Administrator/070_Server_Management_and_Integrations/System_Integration/LTI here].  Brief instructions and a screenshot follow. 

[[File:blackboard-lti-setup.png|500px]]

# 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 (e.g.$LTIBasicConsumerSecret)
# Enable Send User Data. (Restricting to ssl is safer if you have https enabled.) Then enable all three user fields.  

==== Moodle ====

The insturctions are [https://docs.moodle.org/30/en/External_tool_settings here].  Basic instructions and a screenshot follow

[[File:moodle-lti-setup.png|500px]]

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

==== Canvas ====

The instructions are [https://guides.instructure.com/m/4152/l/57103-how-do-i-manually-configure-an-external-app-for-a-course here].  The basic instructions and a screenshot follow.  

[[File:canvas-lti-setup.png|500px]]

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

= 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 [https://credoreference.zendesk.com/hc/en-us/articles/207503743-Blackboard-LTI-Integration-Adding-a-Web-Link here].  A screenshot and basic instructions follow.

[[File:blackboard-lti-link.png|500px]]

# Go to Conent > Build Content > (Create) Web Link
# 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: '''<nowiki>http://webwork.server.edu/webwork2/CourseName</nowiki>'''
# Check "This link is a Tool Provider"

=== Moodle ===

The documentation is [https://docs.moodle.org/30/en/External_tool_settings here].  A screenshot and basic instructions follow. 

[[File:moodle-lti-link.png|500px]]

# Go to a Course, Turn "Editing" on, and click "Add an activity or resource".
# Choose "External Tool" and click "Add".
# 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:  '''<nowiki>http://webwork.server.edu/webwork2/CourseName</nowiki>'''

=== Canvas ===

The documentation is [https://guides.instructure.com/m/4152/l/501360-how-do-i-add-an-external-app-as-an-assignment-submission-type here].  A screenshot and basic instructions follow. 

[[File:canvas-lti-link.png|500px]]

# Go to your Course, then Assignments, then add an assignment. 
# Select "External Tool" for Submission type. 
# 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: '''<nowiki>http://webwork.server.edu/webwork2/CourseName</nowiki>'''

= Automatic Student Account Management =

The LTIAdvanced module can be set up 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 the log in a WeBWorK  account will be created for them.  The username will be determined by '''$preferred_source_of_username''' 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 the LMS from WeBWorK.  The log into WeBWorK 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 neither a student id nor an initial password.  In particular they will not be able to log into WeBWorK directly.  The '''$external_authentication''' 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. 
* 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. 
* 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 the '''$LTI_modify_user''' local 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'. 

* '''%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_modify_user''' - This is a local 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_modify_user = sub { 
 # The self object from LTIAdvanced.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_modify_set''' - This is a local 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_modify_user_set = sub { 
 # The self object from LTIAdvanced.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_authentication''' 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_authentication''' 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).

= Grade Passback =

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

[[Category:Administrators]]
[[Category:Authentication]]