LTI-Basic Authentication

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.

This is a deprecated mechanism

WARNING This old option for LTI authentication is no longer being maintained.

You probably should look at LTI-Advanced_Authentication and not at this page.

Background

The Learning Tools Interoperability (LTI) protocols provide a means to interface a Learning Tool, e.g., WeBWorK, with a Learning Management System (LMS), e.g., Angel, Blackboard, Canvas, Moodle, and Sakai. The LTI protocols are defined by the IMS Global Learning Consortium (Learning Tools Interoperability home page).

Basic LTI (i.e., LTI 1.0) provides a protocol for authenticating from an LMS to a Learning Tool (LT) and passing information such as names, email addresses, and roles (e.g., Instructor, Learner) from the LMS to the LT. Basic LTI is roughly comparable to the initial Moodle-WeBWorK integration at the University of Rochester. Basic LTI is presently supported by most LMS's (see the table at the bottom of the page [http://www.imsglobal.org/cc/statuschart.cfm IMS Interoperability Conformance Certification Status]).

LTI 1.1 (full LTI) will (eventually) provide additional protocols for returning data from a LT to the LMS.

The WeBWorK group at Indiana University Bloomington began developing an LTI-Basic package for WeBWorK in the summer of 2011. We have used LTI-Basic for authentication from the Sakai LMS to WeBWorK since September, 2011. The perl module WeBWorK::Authen::LTIBasic and instructions for additions and modifications to other WeBWorK modules and configuration files are available from the MAA's WeBWorK SVN site and from www.github.com; see below for details..

If your institution uses an LMS that has support for Basic LTI (i.e., LTI 1.0) and you would like to begin testing how to use it to connect to WeBWorK, then we host a WeBWorK test site to which you may connect. Please skip to the "Instructions for using LTI Basic to connect to the IU Bloomington WebworkLTIBasic site".

Obtaining, Installing, Configuring, and Using the LTI Authentication package

Obtaining the LTI Authentication package

The package is, at this time, not in the trunk distribution, although that may change later this summer (2012). Presently, the package may be obtained either from the SVN [system]/branches/wheeler/webwork2 branch or from the github http://www.github.com/whwheeler/webwork2.

There are nine files in the package:

 webwork2/conf/global.conf.dist
 webwork2/lib/WeBWorK/Authen.pm
 webwork2/lib/WeBWorK/Authen/LTIBasic.pm
 webwork2/lib/WeBWorK/Authen/Basic_TheLastOption.pm
 webwork2/lib/WeBWorK/Authz.pm
 webwork2/lib/WeBWorK/DB.pm
 webwork2/lib/WeBWorK/ContentGenerator/Login.pm
 webwork2/lib/WeBWorK/ContentGenerator/Logout.pm
 webwork2/bin/ww_purge_old_nonces

Installing the LTI Authentication package

First, one must install the Perl module Net::OAuth , which is available from CPAN. Depending on one's installation, one may also have to install several prerequisites of Net::OAuth.

The changes to Authen.pm are significant, but they are backwards compatible. The changes enable Authen

 to use an array of authentication hashes so that Authen
 can try several authentication methods in sequence, e.g.,
 LIT Basic, then an institution's local Central Authentication System, and
 then just password authentication (provided by the Basic_TheLastOption.pm module), and

 to use either session_cookies or the Key database for session management.

(Heretofore, using the Key database was the only method for session management. But that requires obtaining a write lock for the Keys table for every request, which can be problematical under heavy loads.)

The changes to global.conf.dist configure

 the LIT Basic environment,
 the sequence of Authentication modules to be tried, 
 whether to require absolutely an external authentication
 or to permit password authentication,and
 the type of session management.

The LTIBasic.pm module implements the LTI 1.0 authentication protocol. It is compliant with the IMS specification with one exception. The exception arises from the incompatibility between the roles supported by WeBWorK and the roles that may be passed from the local Course Management System. The LTIBasic module does require that the CMS provide at least one of the two parameters

 lis_person_sourcedid (or one of its spelling variants
 lis_person_sourced_id, lis_person_source_id, lis_person_sourceid) and

 lis_person_contact_email_primary

in order to construct the WeBWorK username.

The change to DB.pm is a minor change to enable WeBWorK to write "nonces" to the Key database.

The changes to Login.pm enable it to present one of three possible screens:

 (i) present a message that one must use an external authentication system,
 (ii) present the traditional password authentication screen but without
 the "Remember Me" option if session_cookies are used for session management, and
 (iii) present the traditional password authentication screen with the
 "Remember Me" option if the Key database is used for session management
  (heretofore, the only option).

The changes to Logout.pm enable it to present a screen with an appropriate message and, if, password authentication is an option for the site, also present a "Login Again" button that should lead to the password authentication screen of Login.pm

Configuring the LTI authentication package

Configuring the LTI authentication package consists of modifying an installations global.conf file and the course.conf file of each site that will use LTI authentication.

The new LTI parameters have been grouped together at the bottom of the global.conf.dist file.

One should copy all of this section to the end of one's global.conf file. Then one should go through the section and select/set appropriate values for the parameters.

Two of the parameters must be set in each site's course.conf file. These parameters are

 #$LTIBasicToThisSiteURL = "URL to site", e.g.,
 $LTIBasicToThisSiteURL = "https://localserver/webwork2/DemoCourse";

and

 #$LTIBasicConsumerSecret = "Consumer Secret - shared with the Course Management Site", e.g.,
 $LTIBasicConsumerSecret = "webworkLTIB";

These parameters could be set in global.conf for the WeBWorK server as a whole and then overridden in individual course.conf files.

For instructions on configuring the CMS/Learning Management System's LTI tool, please see the example below in the section "Instructions for using LTI Basic to connect to the IU Bloomington WebworkLTIBasic site".

Using the LTI Authentication package

In order for an LMS to use LTI Basic to authenticate to WeBWorK, the LMS must pass the lis_person_sourcedid (or one of its spelling variants mentioned above) and/or the lis_person_contact_email_primary parameters. If only one of them is passed, then its value will be used for a user's WeBWorK username. If both are passed, then which one will be used for the username is determined by the value of the course environment variable $preferred_source_of_username. If that variable is undefined and both parameters are present, then the lis_person_contact_email_primary parameter will be used for the username.

If the CMS/LMS passes both of these parameters so that the WeBWorK administrator/instructor does have the choice as to which one to use for the username, then the decision may be made as follows. The primary concerns are (i) the necessity for the uniqueness of the username across the entire population of possible site users and (ii) compatibility with the institution's practices regarding usernames. If the site will only be used by users from one institution and lis_person_sourcedid passes the institution's usernames, then using lis_person_sourcedid will maximize compatibility with the institution and facilitate returning information to the CMS/LMS. On the other hand, if the site will be used by users from different institutions which assign usernames independently of one another, then lis_person_contact_email_primary should be used as the source of the WeBWorK username. If the lis_person_sourcedid parameter is present, then its value is used as the WeBWorK username. Otherwise, the value of the lis_person_contact_email_primary is used as the username.

In order to identify the WeBWorK "section", the LMS's LTI should be configured to pass an optional "section=xxxx" parameter. Because "section" is not one of the official LTI parameters, the CMS/LMS will pass it in the form "custom_section". BUT in configuring the CMS/LMS LTI tool, one usually just has to specify an optional "section=xxxx" parameter and the LTI tool will insert the "custom_" prefix.

Similarly, if there is to be a recitation value that will be assigned to all of the students in an LMS section site, then that value may be passed to WeBWorK by passing an optional "recitation=xxxx". As with the section parameter, the CMS/LMS LTI tool should insert a "custom_" prefix so that the parameter will actually be passed as "custom_recitation=xxxx".

One should never oneself insert the "custom_" prefix unless the local CMS/LMS administration tells one to do so.

In addition, an optional subroutine for analyzing the "context_id" and setting WeBWorK parameters may be declared for the installation as a whole (in global.conf) or for an individual site (in the site's course.conf file). Two examples of such subroutines may be found in the comments in global.conf.dist.

According to the IMS LTI 1.0 specifications, when a user authenticates via LTI from a Learning Management System (LMS) (e.g., Sakai, Moodle, and Blackboard) to a Learning Tool (LT) (e.g., WeBWorK), the Learning Tool is supposed to accept as valid all of the information that the Learning Management System passes to it. This includes demographic data, e.g., name, email address; custom information, e.g., section; and, most importantly, role information, e.g., student, guest, TA, librarian, teacher, administrator. If the user has not previously registered with the Learning Tool, then the Tool is supposed to accept the authentication from the Learning Management System as authorization to register the user with the Learning Tool with the role passed from the Learning Management System to the Learning Tool.

But this can cause significant problems if the roles passed by the Learning Management System are coarser than the roles used by the Learning Tool. For example, the default implementation of LTI in the Sakai LMS passes only two roles, "Learner" and "Instructor" regardless of the roles that the Sakai LMS uses internally. Accordingly, the Sakai roles of visitor, guest, and student are all collapsed in the LTI to just the role of Learner. The Sakai roles of TA, Librarian, Assistant, Teacher, and (System) Administrator are all collapsed to the single role of Instructor. This is obviously unsatisfactory for WeBWorK. For instance, at Indiana University, perhaps 100-200 of the staff of the University's Information Technology Service across the eight campuses throughout the state have Administrator privileges in the University's Sakai LMS, some of whom may be students who help staff Help Desks. If the LTI specification were followed strictly, then all of these staff members would have Instructor (= WeBWorK-professor) privileges in all of the WeBWorK sites. This is untenable.

Accordingly, the LTIBasic module proceeds as follows:

 If a previously unknown
 user authenticates via LTI and the WeBWorK role/permission level that
 corresponds to the role(s) that the LMS passes is less than or equal
 to the WeBWorK "ta" level, then that person is assigned that corresponding permission level
 in WeBWorK, and the information transmitted with the authentication,
 e.g., first name, last name, id, email address, etc., is used
 to set the corresponding data fields in WeBWorK.

 If a previously unknown user authenticates via LTI and the WeBWorK role/permission
 level that corresponds to the role(s) that the LMS passes is greater
 than the WeBWorK "ta" level, then the authentication is rejected with
 an error message to the effect that the user has not previously been
 approved to have that permission level.

 If a known user authenticates
 via LTI, then the accompanying demographic information, e.g., first name, last name,
 id, email address (but not username of course) is compared to the existing
 WeBWorK data, and if there are any discrepancies, then the new data
 replaces the old data.  If the existing WeBWorK permission level is greater
 than that of a student, then it is not change.  If the WeBWorK permission
 level is greater than that of a student and the existing section is not "Admin",
 then it is changed to "Admin".

(The mapping of LMS roles to WeBworK roles/permission levels is specified for an installation in the global.conf file and may be further modified in a site's course.conf file.)

Consequently, it is imperative that users who are to have WeBWorK roles higher than that of students, e.g., proctors, TA's, instructors, etc., be installed by the existing WeBWorK facilities rather than relying on the roles passed by the LMS. Ideally, this should happen before the individual first authenticates via LTI. But if a privileged user, e.g., a TA, does happen to authenticate via LTI before having been added via WeBWorK facilities, then the WeBWorK facilities for modifying users should be used to fix the user's permission, section, and other data.

In addition, when a new user first authenticates to WeBWorK via LTI, the LTIBasic module, in addition to adding the user, will (attempt to) assign versions of all existing sets (both visible and invisible, both homework and tests/quizzes) to the new user. Furthermore, if the course environment variable

 $adjustDueDatesForLateAdds = "1";

then LTIBasic will compute the number of assigned problems in all of the closed sets, i.e., those whose due dates have passed, will divide that total by the value of the configuration variable

 $reasonableProblemsPerDayMakeup = 15;

and extend all of the expired due dates by that number of days.

In practice, this is usually OK. But if any of the expired assignments were tests or quizzes, then this automatic extension may be unsatisfactory. The instructor should monitor the dates that are assigned to students who add the course after the first quiz or test.

Notes

The LTI parameter "consumer_key" is a required LTI parameter but it is not as directly involved in the LTI OAuth authentication as the name "key" would suggest and as is the consumer_secret. The purpose of the "consumer_key" is to transmit to the Learning Tool a parameter that can be used to retrieve information, perhaps from a database using the consumer_key as the database_key, that may be relevant to the authentication process, e.g., retrieving the consumer_secret from a database.

For instance, if one were hosting a WeBWork site that supported users from several institutions, then one might assign each institution a unique consumer_key and consumer_secret and then use the consumer_key transmitted by the LMS (i) to retrieve that consumer_secret that is part of the OAuth authentication from that institution and (ii) to customize the appearance of the WeBWorK screen.

The LTI parameter oauth_nonce in combination with the oauth_timestamp is used by the OAuth authentication protocol as a defense against man-in-the-middle attacks. Each nonce that is received must be stored temporarily in the Key database in order to implement this man-in-the-middle defense. Because each LTIBasic login uses a unique nonce, the number of nonces in the Key database can grow quickly. A program ww_purge_old_nonces is provided in the webwork2/bin directory to purge these nonces. This program should be run daily via a cron job.

---

Instructions for using LTI Basic to connect to the IU Bloomington WebworkLTIBasic site

Configure the LMS's LTI Basic tool with the following parameters:

 Domain/URL:  https://estudy11.iu.edu:8082/~estudy11/webwork2/WebworkLTIBasic

 Consumer key:  webwork

 Shared Secret:  WeBWorKLTIB

Also, the LTI Basic tool must send a username and/or an email address, in the form:

 lis_person_sourcedid=username
 lis_person_contact_email_primary=username@school.edu

(lis_person_sourcedid and lis_person_contact_email_primary are part of the LTI specification, so it should be possible fo the LTI Basic interface to send them, but some instances of LTI Basic interfaces (e.g., Canvas) require some tweaking.)

The WebworkLTIBasic site is configured to use the lis_person_contact_email_primary parameter, if it is present, as the WeBWorK username, in order to guarantee that usernames are unique. If the lis_person_contact_email_primary parameter is undefined, then the module will use the value of the lis_person_sourcedid parameter as the WeBWorK username. (As mentioned above, WeBWorK will accept several variations on spelling of the lis_person_sourcedid parameter.)

In order to be added to the WebworkLTIBasic site, the role transmitted by the LMS should be that of a student or a Learner. For details, please see the discussion of roles above.

On the first occasion on which a user authenticates to a WeBWorK site using LTIBasic, the WeBWorK::Authen::LTIBasic module will create the user record for the user and assign the user versions of all of the existing WeBWorK problem sets. For purposes of security, the user will be assigned a permission value of 0, regardless of the user's LMS role. This permission can subsequently be increased using the standard WeBWorK tools.

If one can use the LMS's LTI Basic tool in a debug mode that will show the parameters it is sending, then one can compare them to the following parameters that Sakai/Oncourse sends:

---

 BasicLTI Endpoint
 https://estudy11.iu.edu:8082/~estudy11/webwork2/WebworkLTIBasic

 BasicLTI Parameters:
 user_id=wheeler
 lis_person_name_full=William H. Wheeler
 context_id=a75a6608-3698-4b62-803d-063040fce113
 context_title=Math Tools Pages
 oauth_signature=cDU1GfReli3QDeprOJwWv23ukq0=
 oauth_nonce=468921706075144
 lti_message_type=basic-lti-launch-request
 resource_link_description=Linking to WeBWorK@IU
 resource_link_id=109f9125-c711-4151-8601-4567518aed82
 ext_sakai_serverid=esoncprd11
 roles=Instructor
 oauth_signature_method=HMAC-SHA1
 oauth_callback=about:blank
 lis_person_name_family=Wheeler
 lis_person_contact_email_primary=wheeler@indiana.edu
 context_label=Math Tools Pages
 basiclti_submit=Press to continue to external tool.
 lis_person_sourcedid=wheeler
 launch_presentation_locale=en_US
 ext_sakai_server=https://resources.oncourse.iu.edu
 ext_sakai_session=5757ec78346099f129bb771043d0d1d5134b16de4692e8a05332f7c7e79be50c24039d7b92e774cb
 oauth_timestamp=1331327382
 lis_person_name_given=William H.
 lti_version=LTI-1p0
 oauth_version=1.0
 oauth_consumer_key=webwork
 resource_link_title=WeBWorK LTI

Alternatively, in order to find out what parameters one's LTI Basic tool is sending, one may change the URL to

 https://estudy14.iu.edu:8082/~estudy14/oauthTest2.pl

One should get back a message that Oauth verification either succeeded or failed and then a list of the parameters that LTI Basic tool sent.

If the Oauth verification succeeded but one cannot connect to the WebworkLTIBasic site, then one should check whether the LTI Basic tool is sending the lis_person_sourcedid parameter and/or the lis_person_contact_email_primary parameter. One can also check what role is being transmitted.

Note: Use Firefox 3.5 or later for the WebworkLTIBasic site

We use MathML for mathematics provided that the browser is Firefox 3.5 or later. (We use a custom LaTeX to MathML converter.)

Internet Explorer will fail on our WeBWorK problems, because we use a mime type of XHTML + XML + SVG for WeBWorK problems.

With Safari and Chrome, the default WeBWorK display mode is "formatted text". (We'll be changing that this summer.)

---