Difference between revisions of "LTI Authentication (for WeBWorK 2.18 or newer)"
(122 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | Learning Management Systems (LMS) like Blackboard, Moodle, Canvas, and BrightSpace |
+ | Learning Management Systems (LMS) like Blackboard, Moodle, Canvas, and BrightSpace Desire2Learn 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. |
− | This page documents how to setup LTI authentication for WeBWorK 2.18 and beyond. For prior versions of WeBWorK see |
+ | This page documents how to setup LTI authentication for WeBWorK 2.18 and beyond. For prior versions of WeBWorK see [[LTI Authentication (for WeBWorK 2.17 or older)]]. |
− | = LTI Authentication = |
||
+ | = First Time 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. |
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) == |
||
+ | These instructions include how to configure the content selection feature. That feature is only available for WeBWorK 2.19 (which is not yet released at the time of this writing) or newer, and is not available for WeBWorK 2.18. So ignore those portions of the instructions if you are using WeBWorK 2.18. |
||
− | Start by making a copy of the distribution configuration file needed with the following command. |
+ | * Start by making a copy of the distribution configuration file needed with the following command. |
+ | *: <code>cp /opt/webwork/webwork2/conf/authen_LTI.conf.dist /opt/webwork/webwork2/conf/authen_LTI.conf</code> |
||
+ | *: In <code>localOverrides.conf</code> uncomment the line that reads <code>#include("conf/authen_LTI.conf");</code> by removing the <code>#</code> 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 <code>authen_LTI.conf</code> that reads <code>#include('conf/authen_LTI_1_1.conf');</code> by removing the <code>#</code> from the beginning of the line and copy the LTI 1.1 distribution configuration file with |
||
+ | **: <code>cp /opt/webwork/webwork2/conf/authen_LTI_1_1.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_1.conf</code> |
||
+ | ** If you will be using LTI 1.3, then uncomment the line in <code>authen_LTI.conf</code> that reads <code>#include('conf/authen_LTI_1_3.conf');</code> by removing the <code>#</code> from the beginning of the line and copy the LTI 1.3 distribution configuration file with |
||
+ | **: <code>cp /opt/webwork/webwork2/conf/authen_LTI_1_3.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_3.conf</code> |
||
− | <code>cp /opt/webwork/webwork2/conf/authen_LTI.conf.dist /opt/webwork/webwork2/conf/authen_LTI.conf</code> |
||
+ | Note that all WeBWorK LTI configuration variables that do not have a '''$LTI{v1p?}''' prefix are in the <code>authen_LTI.conf</code> file, and are used by both versions of LTI. All variables that have the '''$LTI{v1p1}''' prefix are in the <code>authen_LTI_1_1.conf</code> file, and are only used by LTI 1.1. All variables that have the '''$LTI{v1p3}''' prefix are in the <code>authen_LTI_1_3.conf</code> file, and are only used by LTI 1.3. |
||
− | In <code>conf/localOverrides.conf</code> uncomment the line that reads <code>#include("conf/authen_LTI.conf");</code> by removing the <code>#</code> from the beginning of the line. |
||
+ | The followed are the variables defined in <code>authen_LTI.conf</code>. Some of these are described in more detail later in this document. |
||
− | 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. |
||
+ | * '''$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 <code>logs/webwork2.log</code> file to see the error messages. Make sure to set this back to 0 for production use. |
||
− | If you will be using LTI 1.1, then uncomment the line in <code>conf/authen_LTI.conf</code> that reads <code>#include('conf/authen_LTI_1_1.conf');</code> by removing the <code>#</code> from the beginning of the line and copy the LTI 1.1 distribution configuration file with |
||
+ | * '''$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 <code>logs/webwork2.log</code> file. Make sure that this is also set to 0 for production use. |
||
− | <code>cp /opt/webwork/webwork2/conf/authen_LTI_1_1.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_1.conf</code> |
||
+ | * '''$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. |
||
− | If you will be using LTI 1.3, then uncomment the line in <code>conf/authen_LTI.conf</code> that reads <code>#include('conf/authen_LTI_1_3.conf');</code> by removing the <code>#</code> from the beginning of the line and copy the LTI 1.3 distribution configuration file with |
||
+ | * '''$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. |
||
− | <code>cp /opt/webwork/webwork2/conf/authen_LTI_1_3.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_3.conf</code> |
||
+ | * '''$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. |
||
− | There are some other options in <code>conf/authen_LTI.conf</code> that can be set as well. They are as follows: |
||
+ | * '''$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. |
||
− | * '''$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 <code>logs/webwork2.log</code> file to see the error messages. Make sure to set this back to 0 for production use. |
||
+ | * '''$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. |
||
− | * '''$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 <code>logs/webwork2.log</code> file. Make sure that this is also set to 0 for production use. |
||
+ | * '''$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. |
||
− | * '''$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. |
||
+ | * '''$LTIGradeMode''', '''$LTIGradeOnSubmit''', '''$LTICheckPrior''', and '''$LTIMassUpdateInterval''': These are for grade passback. Details on these will be given later in this document. |
||
− | |||
− | * '''$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. Note that if this is set to 1, then you may also want to set <code>$permissionLevels{change_password} = 'ta'</code> to prevent students from changing passwords (since they can't be used anyway). |
||
* '''@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. |
* '''@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. |
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. |
First the LMS needs to be configured to use LTI 1.3 authentication. Follow the instructions for your LMS below. |
||
− | + | === Moodle LTI 1.3 Configuration === |
|
− | Set the external tool configuration settings as shown in the screen shots below. Make sure to change <nowiki>https://webwork.yourschool.edu</nowiki> 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. |
||
+ | Go to "Site Administration" -> "Plugins" -> "Activity Modules" -> "External Tool" -> "Manage Tools" and click on the link to "configure a tool manually." |
||
+ | |||
+ | Enter a "Tool name" and add a "Tool description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for. |
||
+ | |||
+ | Select "LTI 1.3" for the LTI Version", and enter the following for the fields shown. Change <nowiki>https://webwork.yourschool.edu</nowiki> to the URL for your webwork2 server. |
||
+ | |||
+ | * '''Tool URL''': <nowiki>https://webwork.yourschool.edu/webwork2</nowiki> |
||
+ | * '''Public Keyset''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/keys</nowiki> |
||
+ | * '''Initiate login URL''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/login</nowiki> |
||
+ | * '''Redirection URI(s)''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/launch</nowiki> |
||
+ | * '''Tool configuration usage''': Show as a preconfigured tool when adding an external tool |
||
+ | |||
+ | It is recommended that you set the '''Default launch container''' to "New Window". |
||
+ | |||
+ | 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 setting this up later in this document. Older versions of Moodle allow manual link creation. So you will also need to check '''Supports Deep Linking (Content-Item Message)''' and enter <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/content_selection</nowiki> for the '''Content Selection URL'''. |
||
[[File:MoodleToolSettings.png|500px]] |
[[File:MoodleToolSettings.png|500px]] |
||
+ | |||
+ | Under "Services" make the following selections. |
||
+ | |||
+ | * IMS LTI Assignment and Grade Services: "Use this service for grade sync and column management" (only needed for grade pass back) |
||
+ | * IMS LTI Names and Role Provisioning: "Use this service to retreive members' information as per privacy settings" |
||
+ | * Tool Settings: "Use this service" |
||
[[File:MoodleServices.png|500px]] |
[[File:MoodleServices.png|500px]] |
||
+ | |||
+ | Under "Privacy" make the following selections. |
||
+ | |||
+ | * Share launcher's name with tool: "Always" |
||
+ | * Share launcher's email with tool: "Always" |
||
+ | * Accept grades from the tool: "Always" (only needed for grade pass back) |
||
+ | |||
+ | If both your Moodle instance and your WeBWorK server have SSL (https), then check the "Force SSL" check box for added security. |
||
[[File:MoodlePrivacy.png|500px]] |
[[File:MoodlePrivacy.png|500px]] |
||
Line 63: | Line 85: | ||
[[File:MoodleConfigurationDetails.png|500px]] |
[[File:MoodleConfigurationDetails.png|500px]] |
||
− | 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 <code>conf/authen_LTI_1_3.conf</code> file. The "Access token URL" will also be the value for the '''$LTI{v1p3}{AccessTokenAUD}''' variable. |
||
+ | The following is the mapping of these values to the WeBWorK configuration variables that will need to be set in <code>authen_LTI_1_3.conf</code>. |
||
− | ==== Canvas ==== |
||
+ | * Platform ID: '''$LTI{v1p3}{PlatformID}''' |
||
+ | * Client ID: '''$LTI{v1p3}{ClientID}''' |
||
+ | * Deployment ID: '''$LTI{v1p3}{DeploymentID}''' |
||
+ | * Public keyset URL: '''$LTI{v1p3}{PublicKeysetURL}''' |
||
+ | * Access token URL: '''$LTI{v1p3}{AccessTokenURL}''' and '''$LTI{v1p3}{AccessTokenAUD}''' (only needed for grade pass back) |
||
+ | * Authentication Request URL: '''$LTI{v1p3}{AuthReqURL}''' |
||
− | 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 <nowiki>https://webwork.yourschool.edu</nowiki> to the URL of your server. You can use a "Key Name", "Title", and "Description" that are appropriate for you. |
||
+ | === Canvas LTI 1.3 Configuration === |
||
+ | |||
+ | First, a user that has admin privileges in Canvas must create a developer key. Go to "Developer Keys", click "+ Develop Key", and select "LTI Key". |
||
+ | |||
+ | Choose a "Key Name", "Title", and "Description" that are appropriate for you. The title and description will be visible to instructors that use the tool, and so should appropriately describe what the tool is for. |
||
+ | |||
+ | Now select "Public JWK URL" for the "JWK Method", and enter the following for the fields shown. Change <nowiki>https://webwork.yourschool.edu</nowiki> to the URL of your server. |
||
+ | |||
+ | * '''Target Link URI''': <nowiki>https://webwork.yourschool.edu/webwork2</nowiki> |
||
+ | * '''OpenID Connect Initiation Url''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/login</nowiki> |
||
+ | * '''Redirect URIs''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/launch</nowiki> |
||
+ | * '''Public JWK URL''': <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/keys</nowiki> |
||
[[File:CanvasKeySettings.png|600px]] |
[[File:CanvasKeySettings.png|600px]] |
||
− | Note that some of the |
+ | If you are going to use grade passback, then under "LTI Advantage Services" select everything. Note that some of the services may not be needed, but I am not sure which ones are not so just check them all! |
[[File:CanvasServices.png|500px]] |
[[File:CanvasServices.png|500px]] |
||
− | Under "Additional Settings" |
+ | Under "Additional Settings" set the "Domain" to <nowiki>https://webwork.yourschool.edu</nowiki> and set the "Privacy Level" to "PUBLIC". |
[[File:CanvasAdditionalSettings.png|500px]] |
[[File:CanvasAdditionalSettings.png|500px]] |
||
− | + | In "Placements" add the "Assignment Selection" placement 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. 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 set the "Target Link URI" to <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvantage/content_selection</nowiki>. Choose a "Text". This is what will be shown to users when the placement is presented to users for selection. Set the "Selection Height" and "Selection 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. Reasonable values are 500 and 600, respectively. |
||
+ | |||
+ | You can remove any other placements. WeBWorK does not support any of the others at this time. |
||
[[File:CanvasPlacements.png|500px]] |
[[File:CanvasPlacements.png|500px]] |
||
− | 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 <code> |
+ | 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 <code>authen_LTI_1_3.conf</code> file. |
[[File:CanvasDeveloperKeyDetails.png|500px]] |
[[File:CanvasDeveloperKeyDetails.png|500px]] |
||
− | 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 |
+ | 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 in the "Client ID" field. Then click "Submit". |
[[File:CanvasAddApp.png|500px]] |
[[File:CanvasAddApp.png|500px]] |
||
− | 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 <code> |
+ | 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 <code>authen_LTI_1_3.conf</code> file. |
− | The other variables that will need to be set in the <code> |
+ | The other variables that will need to be set in the <code>authen_LTI_1_3.conf</code> file are as follows: |
* '''$LTI{v1p3}{PlatformID}''': Either '<nowiki>https://canvas.instructure.com</nowiki>' or '<nowiki>https://yourschool.instructure.com</nowiki>' (It is not known at the time of this writing which this will need to be in production.) |
* '''$LTI{v1p3}{PlatformID}''': Either '<nowiki>https://canvas.instructure.com</nowiki>' or '<nowiki>https://yourschool.instructure.com</nowiki>' (It is not known at the time of this writing which this will need to be in production.) |
||
Line 101: | Line 139: | ||
* '''$LTI{v1p3}{AuthReqURL}''': '<nowiki>https://yourschool.instructure.com/api/lti/authorize_redirect</nowiki>' |
* '''$LTI{v1p3}{AuthReqURL}''': '<nowiki>https://yourschool.instructure.com/api/lti/authorize_redirect</nowiki>' |
||
− | + | === Brightspace Desire2Learn LTI 1.3 Configuration === |
|
A post about LTI 1.3 for Brightspace (D2L) appears at https://sukhjitsehra.github.io/webwork-2.18/. |
A post about LTI 1.3 for Brightspace (D2L) appears at https://sukhjitsehra.github.io/webwork-2.18/. |
||
− | === LTI 1.3 WeBWorK Configuration === |
||
+ | This needs to be updated to include the instructions directly here (instead of linking above), as well as instructions on what needs to be added to set up grade pass back and content selection. |
||
+ | |||
+ | == LTI 1.3 WeBWorK Configuration == |
||
Now configure WeBWorK for LTI 1.3 authentication. |
Now configure WeBWorK for LTI 1.3 authentication. |
||
− | Start by making copies of the distribution configuration files needed for this with the following commands. |
||
+ | In the <code>authen_LTI_1_3.conf</code> 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. |
||
− | <code>cp /opt/webwork/webwork2/conf/authen_LTI.conf.dist /opt/webwork/webwork2/conf/authen_LTI.conf</code> |
||
+ | Set <code>$LTIVersion = 'v1p3';</code> in <code>authen_LTI.conf</code>. You may instead set this in the <code>course.conf</code> files of the courses that you want to use LTI 1.3 for, leave <code>$LTIVersion = 'v1p1';</code> in <code>authen_LTI.conf</code> if most of the courses on your server will be using LTI 1.1. |
||
− | <code>cp /opt/webwork/webwork2/conf/authen_LTI_1_3.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_3.conf</code> |
||
− | In <code>conf/localOverrides.conf</code> uncomment the line that reads <code>#include("conf/authen_LTI.conf");</code> by removing the <code>#</code> from the beginning of the line. |
||
+ | 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. |
||
− | In <code>conf/authen_LTI.conf</code> uncomment the line that reads <code>#include('conf/authen_LTI_1_3.conf');</code> by removing the <code>#</code> from the beginning of the line. |
||
+ | * '''$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. |
||
− | In the <code>conf/authen_LTI_1_3.conf</code> file set the LTI 1.3 basic authentication parameters <code>$LTI{v1p3}{PlatformID}</code>, <code>$LTI{v1p3}{ClientID}</code>, <code>$LTI{v1p3}{DeploymentID}</code>, <code>$LTI{v1p3}{PublicKeysetURL}</code>, <code>$LTI{v1p3}{AccessTokenURL}</code>, <code>$LTI{v1p3}{AccessTokenAUD}</code>, <code>$LTI{v1p3}{AuthReqURL}</code> to the values found in the LMS configuration above. |
||
+ | * '''$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 1.1 == |
||
+ | * '''$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 <code>authen_LTI.conf</code> 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 1.1 WeBWorK Configuration === |
||
+ | * '''$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. |
||
− | In <code>conf/authen_LTI_1_1.conf</code> 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. |
||
+ | * '''$LTI{v1p3}{lowercase_username}''': If set to 1, then all usernames (as determined by the options above) will be converted to lowercase. |
||
− | There are some other options that can be set as well. |
||
+ | * '''$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 <code>authen_LTI.conf</code> 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 <code>authen_LTI_1_1.conf</code> 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. |
||
+ | |||
+ | If your WeBWorK server will be serving multiple LMS's all using LTI 1.1 and you want your instructors to be able to utilize content selection, then you will also need to ensure that each LMS uses a different consumer key, and set '''$LTI{v1p1}{ConsumerKey}''' in the <code>course.conf</code> file for each course to be the consumer key for its LMS. |
||
+ | |||
+ | Set <code>$LTIVersion = 'v1p1';</code> in <code>authen_LTI.conf</code> (this is the default setting). You may instead set this in the <code>course.conf</code> files of the courses that you want to use LTI 1.1 for, and set <code>$LTIVersion = 'v1p3';</code> in <code>authen_LTI.conf</code> 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. |
* '''$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. |
||
Line 132: | Line 198: | ||
** 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. |
** 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. |
*** 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 <code> |
+ | ** You can set '''$debug_lti_parameters = 1''' in <code>authen_LTI.conf</code> 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}{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. |
||
Line 139: | Line 205: | ||
* '''$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. |
* '''$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 <code> |
+ | ** You can set '''$debug_lti_parameters = 1''' in <code>authen_LTI.conf</code> 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}''': 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. |
||
Line 145: | Line 211: | ||
* '''$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{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{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 1.1 LMS Configuration == |
||
− | * '''$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. |
||
+ | Now configure the LMS. In general you will need to provide the following things: |
||
− | * '''$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. |
||
+ | * The address of your WeBWorK server. The address here needs to exactly match the address of your webwork server as defined in <code>site.conf</code>, 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". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection. |
||
+ | * The "Tool Provider Secret" or "Shared 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. |
||
− | ==== LMS Setup ==== |
||
+ | The specifics in setting up the LMS vary depending on which LMS you use. Instructions for Moodle, Canvas, BrightSpace Desire2Learn, and Blackboard 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. |
||
− | Next you need to set up your LMS. In general you will need to provide the LMS the following things: |
||
+ | 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. |
||
− | * 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''' |
||
+ | === Moodle LTI 1.1 Configuration === |
||
− | * 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: |
||
+ | Go to "Site administration" > "Plugins" > "Activity modules" > "External Tools" > "Manage Tools" and click the link to "configure a tool manually." |
||
− | * 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 ===== |
||
+ | Enter a "Tool name" and "Tool description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for. |
||
− | 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]] |
||
+ | Then select "LTI 1.0/1.1" for the "LTI Version", and set the following. Change https://webwork.yourschool.edu to the URL of your WeBWorK server. |
||
− | # In the Administrator Panel (under Building Blocks) click LTI Tool Providers and then Register Provider Domain |
||
+ | * '''Tool URL''': <nowiki>https://webwork.yourschool.edu/webwork2</nowiki> |
||
− | # Input the address of the WeBWorK server in Provider Domain |
||
+ | * '''Consumer key''': This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection. |
||
− | # 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) |
||
+ | * '''Shared secret''': This must be the value of '''$LTI{v1p1}{BasicConsumerSecret}'''. |
||
− | # Enable Send User Data. (Restricting to ssl is safer if you have https enabled.) Then enable all three user fields. |
||
+ | * '''Tool configuration usage''': Show in activity chooser and as a preconfigured tool |
||
− | ===== Moodle ===== |
||
+ | It is recommended that you set the '''Default launch container''' to "New window". |
||
− | The instructions are [https://docs.moodle.org/30/en/External_tool_settings here]. Basic instructions and a screenshot follow |
||
+ | 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 setting this up later in this document. Older versions of Moodle allow manual link creation. So for version 4.02 or newer of Moodle you will also need to check '''Supports Deep Linking (Content-Item Message)''' and enter <nowiki>https://webwork.yourschool.edu/webwork2/ltiadvanced/content_selection</nowiki> for the '''Content Selection URL'''. |
||
− | [[File: |
+ | [[File:Moodle-lti1.1-tool-settings.png|500px]] |
− | # Go to Site administration > Plugins > Activity modules > LTI > Manage external tool types and click "Add External Tool Configuration" |
||
+ | Under "Services" make the following selections. |
||
− | # 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 ===== |
||
+ | * IMS LTI Assignment and Grade Services: "Use this service for grade sync and column management" (only needed for grade pass back) |
||
+ | * IMS LTI Names and Role Provisioning: "Use this service to retreive members' information as per privacy settings" |
||
+ | * Tool Settings: "Use this service" |
||
− | 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:MoodleServices.png|500px]] |
||
+ | |||
+ | Under "Privacy" make the following selections. |
||
+ | |||
+ | * Share launcher's name with tool: "Always" |
||
+ | * Share launcher's email with tool: "Always" |
||
+ | * Accept grades from the tool: "Always" (only needed for grade pass back) |
||
+ | |||
+ | If both your Moodle instance and your WeBWorK server have SSL (https), then check the "Force SSL" check box for added security. |
||
+ | |||
+ | [[File:MoodlePrivacy.png|500px]] |
||
+ | |||
+ | === Canvas LTI 1.1 Configuration === |
||
+ | |||
+ | Go to "Settings" and select the "Apps" tab. Then click on "+ App". |
||
+ | |||
+ | Choose "Manual Entry" for the "Configuration Type", and choose a "Name" and "Description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for. |
||
+ | |||
+ | Then set the following. Change <nowiki>https://webwork.yourschool.edu</nowiki> to the URL of your WeBWorK server. |
||
+ | |||
+ | * '''Consumer Key''': This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection. |
||
+ | * '''Shared Secret''': This must be the value of '''$LTI{v1p1}{BasicConsumerSecret}. |
||
+ | * '''Launch URL''': <nowiki>https://webwork.yourschool.edu/webwork2</nowiki> |
||
+ | * '''Domain''': <nowiki>https://webwork.yourschool.edu</nowiki> |
||
+ | * '''Privacy Level''': Public |
||
[[File:canvas-lti-setup.png|500px]] |
[[File:canvas-lti-setup.png|500px]] |
||
− | # Go to Settings > Apps > View App Configurations > Add App |
||
+ | If you would like to allow content selection, then instead select "Paste XML" for the "Configuration Type". Enter the "Consumer Key" and "Shared Secret" as above. Then past the following XML into the "XML Configuration". Make sure to change <nowiki>https://webwork.yourschool.edu</nowiki> to the URL for your WeBWorK server. You can also change the title, description, selection_width, and selection_height if desired. Unfortunately, Canvas only allows selection of a single assignment at once for LTI 1.1. |
||
− | # 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". |
||
− | '''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: [http://webwork.maa.org/moodle/mod/forum/discuss.php?d=4619 the forum post by Tim Payer]. |
||
+ | <?xml version="1.0" encoding="UTF-8"?> |
||
+ | <cartridge_basiclti_link |
||
+ | xmlns="<nowiki>http://www.imsglobal.org/xsd/imslticc_v1p0</nowiki>" |
||
+ | xmlns:blti="<nowiki>http://www.imsglobal.org/xsd/imsbasiclti_v1p0</nowiki>" |
||
+ | xmlns:lticm="<nowiki>http://www.imsglobal.org/xsd/imslticm_v1p0</nowiki>" |
||
+ | xmlns:lticp="<nowiki>http://www.imsglobal.org/xsd/imslticp_v1p0</nowiki>" |
||
+ | xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>" |
||
+ | xsi:schemaLocation="<nowiki>http://www.imsglobal.org/xsd/imslticc_v1p0</nowiki> <nowiki>http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd</nowiki> <nowiki>http://www.imsglobal.org/xsd/imsbasiclti_v1p0</nowiki> <nowiki>http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0p1.xsd</nowiki> <nowiki>http://www.imsglobal.org/xsd/imslticm_v1p0</nowiki> <nowiki>http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd</nowiki> <nowiki>http://www.imsglobal.org/xsd/imslticp_v1p0</nowiki> <nowiki>http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd</nowiki>"> |
||
+ | <blti:title>Available WeBWorK Assignments</blti:title> |
||
+ | <blti:description>Select from available assigments.</blti:description> |
||
+ | <blti:launch_url><nowiki>https://webwork.yourschool.edu/webwork2</nowiki></blti:launch_url> |
||
+ | <blti:extensions platform="canvas.instructure.com"> |
||
+ | <lticm:property name="privacy_level">public</lticm:property> |
||
+ | <lticm:property name="domain"><nowiki>https://webwork.yourschool.edu</nowiki></lticm:property> |
||
+ | <lticm:options name="assignment_selection"> |
||
+ | <lticm:property name="message_type">ContentItemSelectionRequest</lticm:property> |
||
+ | <lticm:property name="url"><nowiki>https://webwork.yourschool.edu/webwork2/ltiadvanced/content_selection</nowiki></lticm:property> |
||
+ | </lticm:options> |
||
+ | <lticm:property name="windowTarget">_blank</lticm:property> |
||
+ | <lticm:property name="selection_width">500</lticm:property> |
||
+ | <lticm:property name="selection_height">600</lticm:property> |
||
+ | </blti:extensions> |
||
+ | </cartridge_basiclti_link> |
||
− | ===== Desire2Learn (D2L) BrightSpace ===== |
||
+ | '''Warning:''' Canvas does not copy the consumer key and consumer secret when course content is copied to a new course. Those values need to be set again manually for the new course. |
||
− | See [[LTI-Advanced_Authentication_for_D2L]] |
||
+ | === BrightSpace Desire2Learn LTI 1.1 Configuration === |
||
− | = Adding Links To WeBWorK = |
||
+ | '''Note''': This is not up to date. Someone using D2L should update it. |
||
− | 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: |
||
+ | This assumes that you will be using the email address stored in D2L (or just the first part of the email address) as the username in WeBWorK. Currently this is the only supported format when linking with D2L. So you will need to set <code>$LTI{v1p1}{preferred_source_of_username} = "lis_person_contact_email_primary";</code> in <code>authen_LTI_1_1.conf</code> in order for these instructions to work. If you prefer to use only the first part of the email address as the username in WeBWorK, then you should also set <code>$LTI{v1p1}{strip_domain_from_email} = 1;</code>. |
||
− | * 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 ==== |
||
+ | # Navigate to the "Manage External Tools" page (as an instructor, this can be found as follows. Go to the Content Browser. Within a content area, click on the "Add Existing Activities" drop-down, and choose "External Learning Tools", then click on "Manage External Tools" at the bottom. |
||
+ | # Click on "Manage Tool Providers" at the top. |
||
+ | # Click on "New Tool Provider". |
||
+ | #: Enter a '''Name''' and '''Description''' that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for. |
||
+ | #: |
||
+ | #: Then set the following. Change <nowiki>https://webwork.yourschool.edu to</nowiki> the URL for your webwork2 server. |
||
+ | #* '''Launch Point''': <nowiki>https://webwork.yourschool.edu/webwork2</nowiki> |
||
+ | #* '''Secret''': This must be the value of $LTI{v1p1}{BasicConsumerSecret}. |
||
+ | #* '''Tool consumer information''': Check the box "Use custom tool consumer information instead of default" |
||
+ | #* '''Key''': This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection. |
||
+ | #* '''Visibility''': Select "Allow users to use this tool provider" |
||
+ | #* '''Security settings''': Check the following: "Send user ID to tool provider", "Send user email to tool provider", "Send system role to tool provider" |
||
+ | #* '''Make tool provider available to''': You can choose which courses or organizational units can use this tool. Note that courses not selected here would still be able to create WeBWorK links, but they would have to be set up manually. |
||
− | 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. |
||
+ | === Blackboard LTI 1.1 Configuration === |
||
− | [[File:blackboard-lti-link.png|500px]] |
||
+ | '''Note''': This is not up to date. Someone using Blackboard should update it. |
||
− | # Go to Conent > Build Content > (Create) Web Link |
||
+ | # In the Administrator Panel (under Building Blocks) click LTI Tool Providers and then Register Provider Domain |
||
− | # 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>''' |
||
+ | # Input the address of the WeBWorK server in Provider Domain |
||
− | # Check "This link is a Tool Provider"* |
||
+ | # 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. |
||
+ | # If you want to use grade pass back, then enable the setting to allow any Tool Provider to post grades to the Grade Center in Building Blocks > LTI Tool Providers > Global Properties. |
||
− | * You may need to enable "LTI" in Customization => Tool Availability if the checkbox for "This link is a Tool Provider" is not shown |
||
+ | [[File:blackboard-lti-setup.png|500px]] |
||
− | ==== Moodle ==== |
||
+ | = Setup Courses To Use Content Selection = |
||
− | The documentation is [https://docs.moodle.org/30/en/External_tool_settings here]. A screenshot and basic instructions follow. |
||
+ | Content selection requests do not identify the WeBWorK course. So WeBWorK needs to know which course to select content from for a given LMS course. If content selection was configured in the LMS above and an instructor attempts to use content selection from the LMS (see Adding Links To WeBWorK below), then the instructor will be shown the LMS context id as in the screen shot below. |
||
− | [[File: |
+ | [[File:LTILMSContextID.png]] |
− | # Go to a Course, Turn "Editing" on, and click "Add an activity or resource". |
||
+ | If the instructor is able to sign in to WeBWorK directly ('''$external_auth''' is set to 0), '''lms_context_id''' is uncommented in the '''@LTIConfigVariables''' in <code>authen_LTI.conf</code>, and '''$permissionLevels{change_config_lms_context_id} = 'professor';''' is set in <code>localOverrides.conf</code>, then the "LTI" tab will be available in the course configuration, and the instructor can enter the shown context id there. Otherwise, a WeBWorK admin user will need to enter the context id for the course on the "Manage LTI Course Map" page in the admin course. |
||
− | # 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 ==== |
||
+ | = Adding Links To WeBWorK = |
||
− | 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. |
||
+ | 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. The process for this varies depending on what LMS you are using. Instructions for Moodle, Canvas, and BrightSpace Desire2Learn, and Blackboard are below. |
||
+ | |||
+ | Note that it is usually best to have WeBWorK open in a new window. There are usually settings you can set when creating a link/assignment in the LMS which will control this. |
||
+ | |||
+ | == Moodle Link Creation == |
||
+ | |||
+ | # Go to a Course, turn on "Edit mode", and click "Add an activity or resource". |
||
+ | # To manually create a link, choose "External Tool" and click "Add". Then pick an activity name and add the URL for a WeBWorK course or assignment. The URL structure is either <nowiki>https://webwork.yourschool.edu/webwork2/coursename</nowiki> or <nowiki>https://webwork.yourschool.edu/webwork2/coursename/assignmentname</nowiki>. Note that this will only work for versions of Moodle prior to 4.2. |
||
+ | # To have a link (or multiple links) created automatically, instead choose the external tool created above named "WeBWorK LTI 1.3" or "WeBWorK LTI 1.1" (or whatever the "Tool name" was set to when the tool was created above). Then click the "Select Content" button on the page that opens next. Select the assignment or assignments that you wish to import, and click "Submit Choices". Note that this is the only permitted method for creating external tool links in version 4.2 or newer of Moodle. |
||
+ | |||
+ | [[File:Moodle-lti-link-creation.png|500px]] |
||
+ | |||
+ | == Canvas Link Creation == |
||
+ | |||
+ | # Go to the "Assignments" page in your course, click "+ Assignment" to create an assignment group (or use an existing assignment group), and then click the "+" button in the top right of the assignment group to add an assignment. |
||
+ | # Select "External Tool" for the "Type" and then click "More Options". |
||
+ | # To manually create a link, input the URL of the WeBWorK course or assignment that you are linking to. The URL structure is either <nowiki>https://webwork.yourschool.edu/webwork2/coursename</nowiki> or <nowiki>https://webwork.yourschool.edu/webwork2/coursename/assignmentname</nowiki>. |
||
+ | # It is recommended that you check "Load This Tool In A New Tab". |
||
[[File:canvas-lti-link.png|500px]] |
[[File:canvas-lti-link.png|500px]] |
||
− | # Go to your Course, then Assignments, then add an assignment. |
||
+ | # To automatically create a link using content selection (if this was configured above) click on "Find" and select the external tool that was created above. Then select the assignment you wish to import and click "Submit Choices". |
||
− | # Select "External Tool" for Submission type. |
||
+ | # If the "Course Assignments Menu" is enabled and configured above (this is only available for LTI 1.3), then multiple assignments can be imported at once. On the Assignments page, click on the vertical dots button that opens the "Assignment Settings" menu (to the right of the "+ Assignment" button at the top), and select "Available WeBWorK Assignments" (or whatever you set the "Text" for this to be). Then select the assignments you wish to import and click "Submit Choices". |
||
− | # 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>''' |
||
− | '''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: [http://webwork.maa.org/moodle/mod/forum/discuss.php?d=4619 the forum post by Tim Payer]. |
||
+ | [[File:canvas-lti-configure-external-tool.png|500px]] |
||
+ | |||
+ | == BrightSpace Desire2Learn Link Creation == |
||
+ | |||
+ | '''Note''': This is not up to date. Someone using D2L should update it. |
||
+ | |||
+ | # Navigate to the content area in your D2L course where you would like the link to reside. |
||
+ | # From the "Add Existing Activities" menu, select "External Learning Tools". |
||
+ | # Click "Manage External Tools" |
||
+ | # Click the New Link button |
||
+ | # Under "Title", fill in whatever text you would like to see for the link in D2L |
||
+ | # For URL, enter the URL to the course or the assignment, typically either <nowiki>https://webwork.yourschool.edu/webwork2/coursename</nowiki> or <nowiki>https://webwork.yourschool.edu/webwork2/coursename/assignmentname</nowiki> |
||
+ | # Check "Allow users to view this link" |
||
+ | # For Key/Secret, check "Sign messages with key/secret with", and select "Tool consumer key secret" |
||
+ | # For Security Settings, select "Use tool provider security settings" |
||
+ | |||
+ | == Blackboard Link Creation == |
||
+ | |||
+ | '''Note''': This is not up to date. Someone using Blackboard should update it. |
||
+ | |||
+ | # Go to Content > Build Content > (Create) Web Link |
||
+ | # Add a Name for your link and the URL of the WeBWorK course or assignment that you are linking to. The URL structure is either <nowiki>https://webwork.yourschool.edu/webwork2/coursename</nowiki> or <nowiki>https://webwork.yourschool.edu/webwork2/coursename/assignmentname</nowiki>. |
||
+ | # 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 |
||
+ | |||
+ | [[File:blackboard-lti-link.png|500px]] |
||
= Automatic Student Account Management = |
= 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 |
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. |
+ | 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 when signing in via LTI authenticaiton 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 <code>$external_auth = 1;</code> prevents ALL users from signing into WeBWorK directly including instructors and TAs. For this reason you may want to set <code>$external_auth = 0;</code> 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 <code>$permissionLevels{change_password} = 'ta'</code> 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. The parameters that control account creation 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 <code>$permissionLevels{change_email} = "ta";</code>. |
||
+ | *** If you use a '''$LTI{v1p?}{LTI_modify_user}''' subroutine then you should turn this feature off. |
||
+ | ** '''$LTIAccountCreationCutoff''': Users with permission levels at or above this value are not automatically created. It is set to 'ta' by default. You will need to manually add users at or above this value 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. There are example subroutines in the <code>authen_LTI_1_1.conf</code> and <code>authen_LTI_1_3.conf</code> files. |
||
+ | ** '''$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. There are example subroutines in the <code>authen_LTI_1_1.conf</code> and <code>authen_LTI_1_3.conf</code> files. |
||
+ | |||
+ | = Grade Pass Back = |
||
+ | |||
+ | WeBWorK can be configured to automatically pass grades back to the LMS. There are several configuration variables in <code>authen_LTI.conf</code> that control grade pass back. |
||
− | * 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. |
||
+ | * '''$LTIGradeMode''': If this variable is not set then grade pass back is disabled. If it is set to "course" then the '''Course Grade Mode''' is used. If it is set to "homework" then the '''Homework Grade Mode''' is used. These grade modes are describe in more detail below. |
||
− | * 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. |
||
+ | * '''$LTIGradeOnSubmit''': If this is enabled then WeBWorK will attempt to update student grades every time they submit an answer to a problem. This keeps the student grades current, but can be a drain on your server. If either the WeBWorK server or the LMS server bogs down it might be a good idea to turn this off. |
||
− | ** 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'. |
||
+ | * '''$LTICheckPrior''': If this is set to 1, then the current LMS grade will be checked before passing back a grade. If the grade has not changed, then the grade will not be updated. This reduces the number of times that records in the LMS are changed, but requires an additional query to the LMS to determine if grades have changed before grades are updated. |
||
− | * '''%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. |
||
+ | * '''$LTIMassUpdateInterval''': Grades for all sets and students can be periodically updated. This interval controls how often that mass update happens (in seconds). It is set to 86400 (24 hours) be default and if it is set to -1 this feature will be disabled. Note that you can also manually trigger grade pass back for a selection of users and sets from the "LTI Grade Update" page in WeBWorK. |
||
− | * '''$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: |
||
+ | General notes on grade passback: |
||
− | $LTI_modify_user = sub { |
||
+ | * In some LMS's instructors do not have grades. In this case an instructor will see the message "Your score was not successfully sent to the LMS". This is usually not a problem. |
||
− | # The self object from LTIAdvanced.pm |
||
+ | * You can set <code>$debug_lti_grade_passback = 1;</code> to turn on extensive debugging messages related to grade pass back. Many of these messages can only be seen in the <code>logs/webwork2.log</code> file particularly if you are using LTI 1.3. It also helps to set <code>$LTIMassUpdateInterval = 60;</code> with this. If you want even more debugging information you can trun on the general debug facility in the <code>webwork2.mojolicious.yml</code> file. |
||
− | my $self = shift; |
||
+ | * A different grade pass back configuration can be used for one course than the site wide default by setting the above configuration variables in that course's <code>course.conf</code> file. |
||
− | # 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: |
||
+ | == Course Grade Mode == |
||
− | $LTI_modify_user_set = sub { |
||
+ | This mode is activated by setting '''$LTIGradeMode''' to "course". In this mode you create a single link/assignment in the LMS which points to WeBWorK. There will be a single column in the LMS gradebook, and WeBWorK will pass back the "cumulative" assignment grade as a percentage which will be shown in this column. Students sign in to WeBWorK via the single link in the LMS. Once in WeBWorK the students navigate WeBWorK and work assignments as they normally would. When students submit an answer, their course grade will be computed and sent to the LMS. |
||
− | # 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 = |
||
+ | Things to note when using this grade mode: |
||
− | 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. |
||
+ | * You should only create one graded link to WeBWorK. If you create more than one, then the LMS gradebook will have multiple columns, and WeBWorK will get confused about which one to send the grade back to. The link URL should have the format <nowiki>https://webwork.yourschool.edu/webwork2/coursename</nowiki> (or select the "Assignments (Course Home)" link when using content selection). |
||
+ | * Student's must log in to WeBWorK via the link created in the LMS at least once in order for this to work. The easiest way to guarantee this is to set up LTI authentication to create student users the first time that they sign in. However, once they have logged in via the LMS once you could allow them to log in directly via username and password. In that case you will need to create passwords for the students manually (or use an alternate remote authentication method). |
||
− | * 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. |
||
+ | == Homework Grade Mode == |
||
− | * 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''' |
||
+ | This mode is activated by setting '''$LTIGradeMode''' to "homework". In this mode you create a link/assignment in the LMS for each problem set in WeBWorK. There will be multiple columns in the LMS gradebook, one for each link/assignment, and the score for each assignment will be passed back and represented in each column. Each link URL should have the format <nowiki>https://webwork.yourschool.edu/webwork2/coursename/assignmentname</nowiki> (or select the individual assignment links listed under "Visible Sets" when using content selection). |
||
− | #$authen{user_module} = { |
||
+ | Things to note when using this grade mode: |
||
− | # "*" => "WeBWorK::Authen::LDAP", |
||
− | #}; |
||
− | In '''authen_LTI.conf''' you should change the definition of '''$authen{user_module}''' to |
||
+ | * Students must click on a link corresponding to an assignment at least once for grade pass back to work. Once in WeBWorK they can navigate like normal (depending on how you have your WeBWorK course configured). However, on the course home page in WeBWorK (the "Assignments" page or "Homework Sets" page depending on the version of WeBWorK) the links to assignments that have not yet been entered from the corresponding link in the LMS will be disabled and will have the message "You must log into this set via your Learning Management System". |
||
+ | * If you set <code>$permissionLevels{navigation_allowed} = 'login_proctor'</code> (this can be set on the "Permissions" tab in the course configuration where it is titled "Allowed to view course home page") then student's will not be able to view the course home page (the "Assignments" page or "Homework Sets" page depending on the version of WeBWorK). This can reduce confusion for students. If you do this, then it is recommended that you also disable direct sign in to WeBWorK by setting <code>$external_auth = 1;</code>. |
||
+ | * Homework due dates and problem totals are not synced between WeBWorK and the LMS. The easiest thing to do is to set all of the homework sets to be open forever in the LMS and let WeBWorK manage access to the homework sets. You can also set the number of points for each set to 100 in the LMS and the score will be a percentage. You can also keep the due dates and number of points synchronized, but you will have to do so by hand. |
||
+ | * Depending on how you weight assignments in the LMS the contributions of an assignment to the total grade in the LMS may be different than the Homework Totals on the Grades page in WeBWorK. You can turn off displaying the Homework Total in WeBWorK using the course configuration "Show Total Homework Grade on Grades Page" setting to reduce confusion. Note also that if you set <code>$permissionLevels{navigation_allowed} = 'login_proctor'</code> then the students will not be able to view the "Grades" page in WeBWorK at all. |
||
− | $authen{user_module} = [ |
||
+ | = Use Different LTI Configurations for Courses = |
||
− | { "*" => "WeBWorK::Authen::LTIAdvanced", }, #preferred authorization method |
||
− | { "*" => "WeBWorK::Authen::LDAP",} #fallback authorization method |
||
− | ]; |
||
− | You should also make sure that '''$external_auth''' is set to zero. |
||
+ | Configure WeBWorK to use LTI as directed above. Then add any of the configuration variables defined in <code>authen_LTI.conf</code>, <code>authen_LTI_1_1.conf</code>, or <code>authen_LTI_1_3.conf</code> to the end of a course's <code>course.conf</code> file to use different values for this course than the site wide settings. |
||
+ | = Combining LTI With Other External Authentication Methods = |
||
− | == Make LTI connections for a single course == |
||
+ | If your LMS uses an LDAP system for authentication you can set WeBWorK to also use LDAP authentication (see [[LDAP Authentication]]). This will allow students to log into WeBWorK using their LDAP/LMS credentials (once their account is created in WeBWorK). To do this you should first comment out the following lines in <code>authen_ldap.conf</code> |
||
− | * 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. |
||
+ | #$authen{user_module} = { |
||
− | * In localOverrides.conf make sure that authen_LTI.conf is enabled and set global settings for the grading mode and debugging: |
||
+ | # "*" => "WeBWorK::Authen::LDAP", |
||
− | 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 ([http://webworkgoehle.blogspot.com/2016/03/webwork-lti-authentication.html]) and the comments in authen_LTI.conf.dist, and LTIAdvanced.pm |
||
− | = Grade Pass-back = |
||
+ | In <code>authen_LTI.conf</code> you should change the definition of '''$authen{user_module}''' to |
||
− | 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]] |
||
+ | $authen{user_module} = [ |
||
+ | { '*' => 'WeBWorK::Authen::LTIAdvantage' }, # first try LTI 1.3 |
||
+ | { '*' => 'WeBWorK::Authen::LTIAdvanced' }, # next try LTI 1.1 |
||
+ | { '*' => 'WeBWorK::Authen::LDAP' } # fallback authorization method |
||
+ | ]; |
||
− | = Gotchas = |
||
+ | You should also make sure that '''$external_auth''' is set to 0. |
||
− | * ''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. |
||
− | ** '''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: [http://webwork.maa.org/moodle/mod/forum/discuss.php?d=4619 the forum post by Tim Payer]. |
||
[[Category:Administrators]] |
[[Category:Administrators]] |
||
[[Category:Authentication]] |
[[Category:Authentication]] |
Latest revision as of 17:52, 11 July 2024
Learning Management Systems (LMS) like Blackboard, Moodle, Canvas, and BrightSpace 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 LTI Authentication (for WeBWorK 2.17 or older).
Contents
First Time 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.
These instructions include how to configure the content selection feature. That feature is only available for WeBWorK 2.19 (which is not yet released at the time of this writing) or newer, and is not available for WeBWorK 2.18. So ignore those portions of the instructions if you are using WeBWorK 2.18.
- 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 withcp /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 withcp /opt/webwork/webwork2/conf/authen_LTI_1_3.conf.dist /opt/webwork/webwork2/conf/authen_LTI_1_3.conf
- If you will be using LTI 1.1, then uncomment the line in
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 LTI 1.3 Configuration
Go to "Site Administration" -> "Plugins" -> "Activity Modules" -> "External Tool" -> "Manage Tools" and click on the link to "configure a tool manually."
Enter a "Tool name" and add a "Tool description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for.
Select "LTI 1.3" for the LTI Version", and enter the following for the fields shown. Change https://webwork.yourschool.edu to the URL for your webwork2 server.
- Tool URL: https://webwork.yourschool.edu/webwork2
- Public Keyset: https://webwork.yourschool.edu/webwork2/ltiadvantage/keys
- Initiate login URL: https://webwork.yourschool.edu/webwork2/ltiadvantage/login
- Redirection URI(s): https://webwork.yourschool.edu/webwork2/ltiadvantage/launch
- Tool configuration usage: Show as a preconfigured tool when adding an external tool
It is recommended that you set the Default launch container to "New Window".
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 setting this up later in this document. Older versions of Moodle allow manual link creation. So you will also need to check Supports Deep Linking (Content-Item Message) and enter https://webwork.yourschool.edu/webwork2/ltiadvantage/content_selection for the Content Selection URL.
Under "Services" make the following selections.
- IMS LTI Assignment and Grade Services: "Use this service for grade sync and column management" (only needed for grade pass back)
- IMS LTI Names and Role Provisioning: "Use this service to retreive members' information as per privacy settings"
- Tool Settings: "Use this service"
Under "Privacy" make the following selections.
- Share launcher's name with tool: "Always"
- Share launcher's email with tool: "Always"
- Accept grades from the tool: "Always" (only needed for grade pass back)
If both your Moodle instance and your WeBWorK server have SSL (https), then check the "Force SSL" check box for added security.
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 following is the mapping of these values to the WeBWorK configuration variables that will need to be set in authen_LTI_1_3.conf
.
- Platform ID: $LTI{v1p3}{PlatformID}
- Client ID: $LTI{v1p3}{ClientID}
- Deployment ID: $LTI{v1p3}{DeploymentID}
- Public keyset URL: $LTI{v1p3}{PublicKeysetURL}
- Access token URL: $LTI{v1p3}{AccessTokenURL} and $LTI{v1p3}{AccessTokenAUD} (only needed for grade pass back)
- Authentication Request URL: $LTI{v1p3}{AuthReqURL}
Canvas LTI 1.3 Configuration
First, a user that has admin privileges in Canvas must create a developer key. Go to "Developer Keys", click "+ Develop Key", and select "LTI Key".
Choose a "Key Name", "Title", and "Description" that are appropriate for you. The title and description will be visible to instructors that use the tool, and so should appropriately describe what the tool is for.
Now select "Public JWK URL" for the "JWK Method", and enter the following for the fields shown. Change https://webwork.yourschool.edu to the URL of your server.
- Target Link URI: https://webwork.yourschool.edu/webwork2
- OpenID Connect Initiation Url: https://webwork.yourschool.edu/webwork2/ltiadvantage/login
- Redirect URIs: https://webwork.yourschool.edu/webwork2/ltiadvantage/launch
- Public JWK URL: https://webwork.yourschool.edu/webwork2/ltiadvantage/keys
If you are going to use grade passback, then under "LTI Advantage Services" select everything. Note that some of the services may not be needed, but I am not sure which ones are not so just check them all!
Under "Additional Settings" set the "Domain" to https://webwork.yourschool.edu and set the "Privacy Level" to "PUBLIC".
In "Placements" add the "Assignment Selection" placement 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. 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 set the "Target Link URI" to https://webwork.yourschool.edu/webwork2/ltiadvantage/content_selection. Choose a "Text". This is what will be shown to users when the placement is presented to users for selection. Set the "Selection Height" and "Selection 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. Reasonable values are 500 and 600, respectively.
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 in the "Client ID" field. 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 Desire2Learn LTI 1.3 Configuration
A post about LTI 1.3 for Brightspace (D2L) appears at https://sukhjitsehra.github.io/webwork-2.18/.
This needs to be updated to include the instructions directly here (instead of linking above), as well as instructions on what needs to be added to set up grade pass back and content selection.
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.
- You can set $debug_lti_parameters = 1 in
- $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.
- You can set $debug_lti_parameters = 1 in
- $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.
If your WeBWorK server will be serving multiple LMS's all using LTI 1.1 and you want your instructors to be able to utilize content selection, then you will also need to ensure that each LMS uses a different consumer key, and set $LTI{v1p1}{ConsumerKey} in the course.conf
file for each course to be the consumer key for its LMS.
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.
- You can set $debug_lti_parameters = 1 in
- $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
Now configure the LMS. In general you will need to provide the following things:
- The address of your WeBWorK server. 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". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection.
- The "Tool Provider Secret" or "Shared 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 Moodle, Canvas, BrightSpace Desire2Learn, and Blackboard 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.
Moodle LTI 1.1 Configuration
Go to "Site administration" > "Plugins" > "Activity modules" > "External Tools" > "Manage Tools" and click the link to "configure a tool manually."
Enter a "Tool name" and "Tool description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for.
Then select "LTI 1.0/1.1" for the "LTI Version", and set the following. Change https://webwork.yourschool.edu to the URL of your WeBWorK server.
- Tool URL: https://webwork.yourschool.edu/webwork2
- Consumer key: This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection.
- Shared secret: This must be the value of $LTI{v1p1}{BasicConsumerSecret}.
- Tool configuration usage: Show in activity chooser and as a preconfigured tool
It is recommended that you set the Default launch container to "New window".
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 setting this up later in this document. Older versions of Moodle allow manual link creation. So for version 4.02 or newer of Moodle you will also need to check Supports Deep Linking (Content-Item Message) and enter https://webwork.yourschool.edu/webwork2/ltiadvanced/content_selection for the Content Selection URL.
Under "Services" make the following selections.
- IMS LTI Assignment and Grade Services: "Use this service for grade sync and column management" (only needed for grade pass back)
- IMS LTI Names and Role Provisioning: "Use this service to retreive members' information as per privacy settings"
- Tool Settings: "Use this service"
Under "Privacy" make the following selections.
- Share launcher's name with tool: "Always"
- Share launcher's email with tool: "Always"
- Accept grades from the tool: "Always" (only needed for grade pass back)
If both your Moodle instance and your WeBWorK server have SSL (https), then check the "Force SSL" check box for added security.
Canvas LTI 1.1 Configuration
Go to "Settings" and select the "Apps" tab. Then click on "+ App".
Choose "Manual Entry" for the "Configuration Type", and choose a "Name" and "Description" that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for.
Then set the following. Change https://webwork.yourschool.edu to the URL of your WeBWorK server.
- Consumer Key: This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection.
- Shared Secret: This must be the value of $LTI{v1p1}{BasicConsumerSecret}.
- Launch URL: https://webwork.yourschool.edu/webwork2
- Domain: https://webwork.yourschool.edu
- Privacy Level: Public
If you would like to allow content selection, then instead select "Paste XML" for the "Configuration Type". Enter the "Consumer Key" and "Shared Secret" as above. Then past the following XML into the "XML Configuration". Make sure to change https://webwork.yourschool.edu to the URL for your WeBWorK server. You can also change the title, description, selection_width, and selection_height if desired. Unfortunately, Canvas only allows selection of a single assignment at once for LTI 1.1.
<?xml version="1.0" encoding="UTF-8"?> <cartridge_basiclti_link xmlns="http://www.imsglobal.org/xsd/imslticc_v1p0" xmlns:blti="http://www.imsglobal.org/xsd/imsbasiclti_v1p0" xmlns:lticm="http://www.imsglobal.org/xsd/imslticm_v1p0" xmlns:lticp="http://www.imsglobal.org/xsd/imslticp_v1p0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.imsglobal.org/xsd/imslticc_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0p1.xsd http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd"> <blti:title>Available WeBWorK Assignments</blti:title> <blti:description>Select from available assigments.</blti:description> <blti:launch_url>https://webwork.yourschool.edu/webwork2</blti:launch_url> <blti:extensions platform="canvas.instructure.com"> <lticm:property name="privacy_level">public</lticm:property> <lticm:property name="domain">https://webwork.yourschool.edu</lticm:property> <lticm:options name="assignment_selection"> <lticm:property name="message_type">ContentItemSelectionRequest</lticm:property> <lticm:property name="url">https://webwork.yourschool.edu/webwork2/ltiadvanced/content_selection</lticm:property> </lticm:options> <lticm:property name="windowTarget">_blank</lticm:property> <lticm:property name="selection_width">500</lticm:property> <lticm:property name="selection_height">600</lticm:property> </blti:extensions> </cartridge_basiclti_link>
Warning: Canvas does not copy the consumer key and consumer secret when course content is copied to a new course. Those values need to be set again manually for the new course.
BrightSpace Desire2Learn LTI 1.1 Configuration
Note: This is not up to date. Someone using D2L should update it.
This assumes that you will be using the email address stored in D2L (or just the first part of the email address) as the username in WeBWorK. Currently this is the only supported format when linking with D2L. So you will need to set $LTI{v1p1}{preferred_source_of_username} = "lis_person_contact_email_primary";
in authen_LTI_1_1.conf
in order for these instructions to work. If you prefer to use only the first part of the email address as the username in WeBWorK, then you should also set $LTI{v1p1}{strip_domain_from_email} = 1;
.
- Navigate to the "Manage External Tools" page (as an instructor, this can be found as follows. Go to the Content Browser. Within a content area, click on the "Add Existing Activities" drop-down, and choose "External Learning Tools", then click on "Manage External Tools" at the bottom.
- Click on "Manage Tool Providers" at the top.
- Click on "New Tool Provider".
- Enter a Name and Description that are appropriate for you. These will be visible to instructors that use the tool, and so should appropriately describe what the tool is for.
- Then set the following. Change https://webwork.yourschool.edu to the URL for your webwork2 server.
- Launch Point: https://webwork.yourschool.edu/webwork2
- Secret: This must be the value of $LTI{v1p1}{BasicConsumerSecret}.
- Tool consumer information: Check the box "Use custom tool consumer information instead of default"
- Key: This can be any word, e.g., "webwork". However, if the WeBWorK server will be serving multiple LMS's with different LTI 1.1 configurations, then this must be different for each LMS in order for instructors in the courses to be able to utilize content selection.
- Visibility: Select "Allow users to use this tool provider"
- Security settings: Check the following: "Send user ID to tool provider", "Send user email to tool provider", "Send system role to tool provider"
- Make tool provider available to: You can choose which courses or organizational units can use this tool. Note that courses not selected here would still be able to create WeBWorK links, but they would have to be set up manually.
Blackboard LTI 1.1 Configuration
Note: This is not up to date. Someone using Blackboard should update it.
- 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.
- If you want to use grade pass back, then enable the setting to allow any Tool Provider to post grades to the Grade Center in Building Blocks > LTI Tool Providers > Global Properties.
Setup Courses To Use Content Selection
Content selection requests do not identify the WeBWorK course. So WeBWorK needs to know which course to select content from for a given LMS course. If content selection was configured in the LMS above and an instructor attempts to use content selection from the LMS (see Adding Links To WeBWorK below), then the instructor will be shown the LMS context id as in the screen shot below.
If the instructor is able to sign in to WeBWorK directly ($external_auth is set to 0), lms_context_id is uncommented in the @LTIConfigVariables in authen_LTI.conf
, and $permissionLevels{change_config_lms_context_id} = 'professor'; is set in localOverrides.conf
, then the "LTI" tab will be available in the course configuration, and the instructor can enter the shown context id there. Otherwise, a WeBWorK admin user will need to enter the context id for the course on the "Manage LTI Course Map" page in the admin course.
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. The process for this varies depending on what LMS you are using. Instructions for Moodle, Canvas, and BrightSpace Desire2Learn, and Blackboard are below.
Note that it is usually best to have WeBWorK open in a new window. There are usually settings you can set when creating a link/assignment in the LMS which will control this.
Moodle Link Creation
- Go to a Course, turn on "Edit mode", and click "Add an activity or resource".
- To manually create a link, choose "External Tool" and click "Add". Then pick an activity name and add the URL for a WeBWorK course or assignment. The URL structure is either https://webwork.yourschool.edu/webwork2/coursename or https://webwork.yourschool.edu/webwork2/coursename/assignmentname. Note that this will only work for versions of Moodle prior to 4.2.
- To have a link (or multiple links) created automatically, instead choose the external tool created above named "WeBWorK LTI 1.3" or "WeBWorK LTI 1.1" (or whatever the "Tool name" was set to when the tool was created above). Then click the "Select Content" button on the page that opens next. Select the assignment or assignments that you wish to import, and click "Submit Choices". Note that this is the only permitted method for creating external tool links in version 4.2 or newer of Moodle.
Canvas Link Creation
- Go to the "Assignments" page in your course, click "+ Assignment" to create an assignment group (or use an existing assignment group), and then click the "+" button in the top right of the assignment group to add an assignment.
- Select "External Tool" for the "Type" and then click "More Options".
- To manually create a link, input the URL of the WeBWorK course or assignment that you are linking to. The URL structure is either https://webwork.yourschool.edu/webwork2/coursename or https://webwork.yourschool.edu/webwork2/coursename/assignmentname.
- It is recommended that you check "Load This Tool In A New Tab".
- To automatically create a link using content selection (if this was configured above) click on "Find" and select the external tool that was created above. Then select the assignment you wish to import and click "Submit Choices".
- If the "Course Assignments Menu" is enabled and configured above (this is only available for LTI 1.3), then multiple assignments can be imported at once. On the Assignments page, click on the vertical dots button that opens the "Assignment Settings" menu (to the right of the "+ Assignment" button at the top), and select "Available WeBWorK Assignments" (or whatever you set the "Text" for this to be). Then select the assignments you wish to import and click "Submit Choices".
BrightSpace Desire2Learn Link Creation
Note: This is not up to date. Someone using D2L should update it.
- Navigate to the content area in your D2L course where you would like the link to reside.
- From the "Add Existing Activities" menu, select "External Learning Tools".
- Click "Manage External Tools"
- Click the New Link button
- Under "Title", fill in whatever text you would like to see for the link in D2L
- For URL, enter the URL to the course or the assignment, typically either https://webwork.yourschool.edu/webwork2/coursename or https://webwork.yourschool.edu/webwork2/coursename/assignmentname
- Check "Allow users to view this link"
- For Key/Secret, check "Sign messages with key/secret with", and select "Tool consumer key secret"
- For Security Settings, select "Use tool provider security settings"
Blackboard Link Creation
Note: This is not up to date. Someone using Blackboard should update it.
- Go to Content > Build Content > (Create) Web Link
- Add a Name for your link and the URL of the WeBWorK course or assignment that you are linking to. The URL structure is either https://webwork.yourschool.edu/webwork2/coursename or https://webwork.yourschool.edu/webwork2/coursename/assignmentname.
- 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
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 when signing in via LTI authenticaiton 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. The parameters that control account creation 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.
- 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
- $LTIAccountCreationCutoff: Users with permission levels at or above this value are not automatically created. It is set to 'ta' by default. You will need to manually add users at or above this value 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. There are example subroutines in the
authen_LTI_1_1.conf
andauthen_LTI_1_3.conf
files. - $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. There are example subroutines in the
authen_LTI_1_1.conf
andauthen_LTI_1_3.conf
files.
- $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.
Grade Pass Back
WeBWorK can be configured to automatically pass grades back to the LMS. There are several configuration variables in authen_LTI.conf
that control grade pass back.
- $LTIGradeMode: If this variable is not set then grade pass back is disabled. If it is set to "course" then the Course Grade Mode is used. If it is set to "homework" then the Homework Grade Mode is used. These grade modes are describe in more detail below.
- $LTIGradeOnSubmit: If this is enabled then WeBWorK will attempt to update student grades every time they submit an answer to a problem. This keeps the student grades current, but can be a drain on your server. If either the WeBWorK server or the LMS server bogs down it might be a good idea to turn this off.
- $LTICheckPrior: If this is set to 1, then the current LMS grade will be checked before passing back a grade. If the grade has not changed, then the grade will not be updated. This reduces the number of times that records in the LMS are changed, but requires an additional query to the LMS to determine if grades have changed before grades are updated.
- $LTIMassUpdateInterval: Grades for all sets and students can be periodically updated. This interval controls how often that mass update happens (in seconds). It is set to 86400 (24 hours) be default and if it is set to -1 this feature will be disabled. Note that you can also manually trigger grade pass back for a selection of users and sets from the "LTI Grade Update" page in WeBWorK.
General notes on grade passback:
- In some LMS's instructors do not have grades. In this case an instructor will see the message "Your score was not successfully sent to the LMS". This is usually not a problem.
- You can set
$debug_lti_grade_passback = 1;
to turn on extensive debugging messages related to grade pass back. Many of these messages can only be seen in thelogs/webwork2.log
file particularly if you are using LTI 1.3. It also helps to set$LTIMassUpdateInterval = 60;
with this. If you want even more debugging information you can trun on the general debug facility in thewebwork2.mojolicious.yml
file. - A different grade pass back configuration can be used for one course than the site wide default by setting the above configuration variables in that course's
course.conf
file.
Course Grade Mode
This mode is activated by setting $LTIGradeMode to "course". In this mode you create a single link/assignment in the LMS which points to WeBWorK. There will be a single column in the LMS gradebook, and WeBWorK will pass back the "cumulative" assignment grade as a percentage which will be shown in this column. Students sign in to WeBWorK via the single link in the LMS. Once in WeBWorK the students navigate WeBWorK and work assignments as they normally would. When students submit an answer, their course grade will be computed and sent to the LMS.
Things to note when using this grade mode:
- You should only create one graded link to WeBWorK. If you create more than one, then the LMS gradebook will have multiple columns, and WeBWorK will get confused about which one to send the grade back to. The link URL should have the format https://webwork.yourschool.edu/webwork2/coursename (or select the "Assignments (Course Home)" link when using content selection).
- Student's must log in to WeBWorK via the link created in the LMS at least once in order for this to work. The easiest way to guarantee this is to set up LTI authentication to create student users the first time that they sign in. However, once they have logged in via the LMS once you could allow them to log in directly via username and password. In that case you will need to create passwords for the students manually (or use an alternate remote authentication method).
Homework Grade Mode
This mode is activated by setting $LTIGradeMode to "homework". In this mode you create a link/assignment in the LMS for each problem set in WeBWorK. There will be multiple columns in the LMS gradebook, one for each link/assignment, and the score for each assignment will be passed back and represented in each column. Each link URL should have the format https://webwork.yourschool.edu/webwork2/coursename/assignmentname (or select the individual assignment links listed under "Visible Sets" when using content selection).
Things to note when using this grade mode:
- Students must click on a link corresponding to an assignment at least once for grade pass back to work. Once in WeBWorK they can navigate like normal (depending on how you have your WeBWorK course configured). However, on the course home page in WeBWorK (the "Assignments" page or "Homework Sets" page depending on the version of WeBWorK) the links to assignments that have not yet been entered from the corresponding link in the LMS will be disabled and will have the message "You must log into this set via your Learning Management System".
- If you set
$permissionLevels{navigation_allowed} = 'login_proctor'
(this can be set on the "Permissions" tab in the course configuration where it is titled "Allowed to view course home page") then student's will not be able to view the course home page (the "Assignments" page or "Homework Sets" page depending on the version of WeBWorK). This can reduce confusion for students. If you do this, then it is recommended that you also disable direct sign in to WeBWorK by setting$external_auth = 1;
. - Homework due dates and problem totals are not synced between WeBWorK and the LMS. The easiest thing to do is to set all of the homework sets to be open forever in the LMS and let WeBWorK manage access to the homework sets. You can also set the number of points for each set to 100 in the LMS and the score will be a percentage. You can also keep the due dates and number of points synchronized, but you will have to do so by hand.
- Depending on how you weight assignments in the LMS the contributions of an assignment to the total grade in the LMS may be different than the Homework Totals on the Grades page in WeBWorK. You can turn off displaying the Homework Total in WeBWorK using the course configuration "Show Total Homework Grade on Grades Page" setting to reduce confusion. Note also that if you set
$permissionLevels{navigation_allowed} = 'login_proctor'
then the students will not be able to view the "Grades" page in WeBWorK at all.
Use Different LTI Configurations for Courses
Configure WeBWorK to use LTI as directed above. Then add any of the configuration variables defined in authen_LTI.conf
, authen_LTI_1_1.conf
, or authen_LTI_1_3.conf
to the end of a course's course.conf
file to use different values for this course than the site wide settings.
Combining LTI With Other External Authentication Methods
If your LMS uses an LDAP system for authentication you can set WeBWorK to also use LDAP authentication (see LDAP Authentication). This will allow students to log into WeBWorK using their LDAP/LMS credentials (once their account is created in WeBWorK). 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::LTIAdvantage' }, # first try LTI 1.3 { '*' => 'WeBWorK::Authen::LTIAdvanced' }, # next try LTI 1.1 { '*' => 'WeBWorK::Authen::LDAP' } # fallback authorization method ];
You should also make sure that $external_auth is set to 0.