Desire2Learn Brightspace LTI 1.3 Configuration

Conventions

In this document we will use "https://brightspace.yourschool.edu" for the root URL of the Desire2Learn Brightspace server, and "https://webwork.yourschool.edu" for the WeBWorK server. You should replace these with the appropriate addresses for your installation.

Create a New Tool Registration

• Go to the LTI Advantage Tool Registration page (probably something like https://brightspace.yourschool.edu/d2l/le/ltiadvantage/registrations/home), and click "Register Tool".
• Select Standard, then fill in the following values:
  • Name: WeBWorK (this name is only used to manage LTI tools. It is not shown to instructors.)
  • Domain: https://webwork.yourschool.edu (the root URL of your WeBWorK server)
  • Redirect URLs: https://webwork.yourschool.edu/webwork2/ltiadvantage/launch
  • OpenID Connect Login URL: https://webwork.yourschool.edu/webwork2/ltiadvantage/login
  • Target Link URI: https://webwork.yourschool.edu/webwork2/
  • Keyset URL: https://webwork.yourschool.edu/webwork2/ltiadvantage/keys (needed for deep-linking - e.g. to enable content selection)
  • Extensions:
    • If you intend to enable grade pass back (automatically synchronizing grades from WeBWorK to Brightspace), then check the box for Assignment and Grade Services.
    • If you intend to enable content selection, then check the box for Deep Linking (this may be used for other functionality in the future).
    • Check the box for Names and Role Provisioning Services.
  • Roles: You should not need to check the Send Institution Role box. WeBWorK by default will use the Context Role which is enabled later in the configuration, though it shouldn't cause any issues if this is checked.
• When you click the "Register" button you will be presented with Brightspace Registration Details. Make note of these six values as they will need to be entered into the WeBWorK configuration files in a later step.

Create a New Tool Deployment

• Go to the External Learning Tools page. If you are still on the confirmation page from the previous step you can click on "View Deployments", otherwise the URL is probably something like https://webwork.yourschool.edu/d2l/le/ltiadvantage/deployments/home.
• Click "New Deployment", and fill in the following values:
  • Tool: WeBWorK Select the name you gave the Tool in the previous step
  • Name: WeBWorK This name will be shown to instructors if they manually create a new LTI link in one of their courses
  • Extensions:
    • If you intend to enable grade pass back (automatically synchronizing grades from WeBWorK to Brightspace), then check the box for Assignment and Grade Services.
    • If you intend to enable content selection, then check the box for Deep Linking (this may be used for other functionality in the future).
    • Check the box for Names and Role Provisioning Services.
  • Security Settings:
    
    • If you intend to use Content Selection you will need to select Org Unit Information
    • For User Information make sure that you select all values that you want to be populated in WeBWorK. At the very least you will need to send whatever item you want WeBWorK to use for the student's username. Note that the User ID is the internal ID number that Brightspace uses to identify the user. The Username is the name that the user uses to log in to Brightspace, and Org Defined Id is the identifier of the user set by your institution. In most Brightspace instances Org Defined ID will be the user's student ID number.
    • As of WeBWorK 2.19 Classlist sync is not yet implemented. If this is added in future versions of WeBWorK you will need to select Classlist including users not known to this deployment for it to work.
  • Configuration Settings:
    • Open as External Resource will force all newly created WeBWorK LTI links to open in a new window. Some browsers (including Safari and recent versions of Chrome) block third-party cookies, which can cause problems with opening another application (e.g. WeBWorK) in a frame within a Brightspace page, so you may want to select this.
    • Grades created by LTI will be included in Final Grade: If this is selected, then any time a new grade item is created for a WeBWorK assignment via LTI it will be given a nonzero weight toward the final course grade. It looks like the default weight is 10. If this is not selected then the weight of these newly-created grade items will be 0.
    • Auto Create Grade Items: This should be selected if you plan to enable grade pass back. Note that LTI links created via Content Selection will automatically create an associated grade item independent of this setting.
  • Depending on how your Brightspace instance is configured you may need to make the Deployment available to all courses. Under "Make tool available to:" click "Add Org Units". From the drop-down menu select "Organization". Select which organization(s) (there may be only one) should have access to WeBWorK links, and choose "This org unit and all descendants". If WeBWorK links should only be available to some Brightspace courses then you can select the appropriate Org Units at this stage.
• Click "Create Deployment". You will be provided with a Deployment ID. Make note of this value as it will need to be entered into the WeBWorK configuration files in the next step.

WeBWorK Configuration

On your WeBWorK server navigate to the configuration directory:

 cd /opt/webwork/webwork2/conf

Copy the distribution configuration file:

 cp authen_LTI_1_3.conf.dist authen_LTI_1_3.conf

Edit the new configuration file using your favourite editor (nano authen_LTI_1_3.conf) and make the following changes:

• Comment out the line $LTI{v1p3}{LMS_name} = 'the LMS'; (add # at the beginning), and uncomment the line #$LTI{v1p3}{LMS_name} = 'D2L Brightspace'; (remove # at the beginning). You can also change the name from 'D2L Brightspace' if your students know your Learning Management System by a different name:

 # This is a string that is used to name the LMS for end users, for example in a message telling
 # users to sign in through their LMS.
 #$LTI{v1p3}{LMS_name} = 'the LMS';
 #$LTI{v1p3}{LMS_name} = 'Blackboard';
 #$LTI{v1p3}{LMS_name} = 'Canvas';
 $LTI{v1p3}{LMS_name} = 'D2L Brightspace';
 #$LTI{v1p3}{LMS_name} = 'Moodle';

• Fill in the URL for your Brightspace instance in the $LTI{v1p3}{LMS_url} variable:

 $LTI{v1p3}{LMS_url} = 'https://brightspace.yourschool.edu';

• By default the full email address obtained from Brightspace will be used as the user_id in WeBWorK. If this is the desired username then you can leave the next section of the configuration file as-is.
• If you want to populate student ID numbers from Brightspace into the student_id field in WeBWorK, then set the following variable. If you leave it blank then nothing will be populated into the student_id field in WeBWorK.

 $LTI{v1p3}{preferred_source_of_student_id} = 'http://www.brightspace.com#org_defined_id';

• Scroll down to the LTI 1.3 Basic Authentication Parameters section, and enter the values you noted in the previous steps as follows.
  • $LTI{v1p3}{PlatformID} = ' Issuer ';
  • $LTI{v1p3}{ClientID} = ' Client Id ';
  • $LTI{v1p3}{DeploymentID} = ' Deployment ID ';
  • $LTI{v1p3}{PublicKeysetURL} = ' Brightspace Keyset URL ';
  • $LTI{v1p3}{AccessTokenURL} = ' Brightspace OAuth2 Access Token URL ';
  • $LTI{v1p3}{AccessTokenAUD} = ' Brightspace OAuth2 Audience ';
  • $LTI{v1p3}{AuthReqURL} = ' OpenID Connect Authentication Endpoint ';

Note: the next step will overwrite any existing LTI configuration in WeBWorK.

Copy the distribution LTI configuration file:

 cp authen_LTI.conf.dist authen_LTI.conf

Edit the new configuration file using your favourite editor (nano authen_LTI.conf) and make the following changes:

• If you are only using LTI 1.3 with WeBWorK you can disable the LTI 1.1 authentication module:

 $authen{user_module} = [
       { '*' => 'WeBWorK::Authen::LTIAdvantage' },          # first try LTI 1.3
       #{ '*' => 'WeBWorK::Authen::LTIAdvanced' },           # next try LTI 1.1
       { '*' => 'WeBWorK::Authen::Basic_TheLastOption' }    # fallback authorization method                                                         
 ];

• Uncomment the inclusion of the LTI 1.3 configuration:

 include('conf/authen_LTI_1_3.conf');

• Set $LTIVersion to 'v1p3':

 $LTIVersion = 'v1p3';

Adding a link to your course

Manually Creating Links to WeBWorK

As of WeBWork 2.19 Content Selection can be enabled, which automates the process of creating links to individual courses or assignments in WeBWorK. It is recommended to enable Content Selection and use that to create links rather than manually create them as described here.

Note: depending on how your Brightspace instance is configured there may be more than one way for an instructor to create an External Learning Tool link.

If you have already created a link to the course/assignment

If you want to link to the same WeBWorK item from more than one place in your Brightspace course you should re-use the same link rather than creating a new one each time. Creating a second link to an item that is already linked will cause problems with synchronizing grades between WeBWorK and Brightspace.

• From within any Content module in your Desire2Learn Brightspace course, click "Add Existing Activities -> External Learning Tools" (if you want to add a link within the text of a page, then click on the link icon, and select "External Learning Tools").
• Choose the appropriate link from the list.

Creating a link to an item that is not already linked

• From within any Content module in your Desire2Learn Brightspace course, click "Add Existing Activities -> External Learning Tools" (if you want to add a link within the text of a page, then click on the link icon, and select "External Learning Tools").
• Scroll to the end of the list and click "Create New LTI Link"

• Enter a Title. This will be the default text displayed when you embed the link anywhere in your Brightspace course. You should make this title distinguishable from links to any other WeBWorK items (you can customize the text each time you deploy the link).
• For the LTI URL enter the path to either the course (e.g. https://webwork.yourschool.edu/webwork2/yourcourse) or the assignment (e.g. https://webwork.yourschool.edu/webwork2/yourcourse/yourassignment). When you move the cursor outside of this text box Brightspace should automatically select the "WeBWorK" tool deployment.
• Click "Create and Insert". You should now have a link that will automatically log you in to your WeBWorK course.

Setting Up Content Selection

Content selection provides an instructor with a list of items in their WeBWorK course that can be linked from Brightspace. Once configured this means that instructors do not need to know the proper URL and settings to create a new link. See LTI_Authentication_(for_WeBWorK_2.18_or_newer)#Setup_Courses_To_Use_Content_Selection for information about configuration on the WeBWorK side.

To enable WeBWorK Content Selection in Brightspace:

• From the External Learning Tools management page (probably https://brightspace.yourschool.edu/d2l/le/ltiadvantage/deployments/home) click on the WeBWorK deployment (in the first column). Scroll to the bottom of the page at click "View Links", then click "New Link". Enter the following settings.
  • Name: WeBWorK Assignment (This is the name that will appear in the "Add Existing Activities" drop-down menu for instructors.)
  • URL: https://webwork.yourschool.edu/webwork2/ltiadvantage/content_selection
  • Type: Deep Linking Quicklink. The Width and Height refer to the size of the frame that is opened when an instructor uses Content Selection.
  • Click "Save and Close"

To check that Content Selection is available visit a Brightspace course and navigate to any content area. In the "Add Existing Activities" drop-down menu there should now be an entry labelled "WeBWorK Assignment".

When you click on "WeBWorK Assignment" you will probably get the error message

No WeBWorK course was found associated to this LMS course. If this is an error, please contact the WeBWorK system administrator.

See LTI Authentication (for WeBWorK 2.18 or newer)#Setup Courses To Use Content Selection for instructions on how to associate a WeBWorK course with a Brightspace course.

Next Steps

These instructions do not cover WeBWorK configuration that is the same for all Learning Management Systems. That can be found at LTI Authentication (for WeBWorK 2.18 or newer). In particular you should look at

• Automatic Student Account Management
• Grade Pass Back.