Sakai Approach for BasicLTI Outcome Extension result_sourcedid
csev
Comments welcome.
/Chuck
Sakai Design for Receiving Grades from External Tool using IMS Basic LTI Extensions
Version: 2 - July 29, 2010
Comments to: Charles Severance
This is a design for an approach to accept grades from an external tool and put those grades in the Sakai grade book. Please review this design for security and feasibility.
Overview of the Structure of IMS Outcomes
When you look at the IMS Basic LTI Launch, there is a field called the lis_result_sourcedid. If the administrator or instructor decides that a particular launch/resource/placement is to send grades to the Sakai grade book, they must create the column in the grade book and indicate which grade book column to accumulate grades for the particular resource.
The lis_result_sourcedid must contain enough information to uniquely identify the placement, course, and particular row and column to store a grade for the user. The value will be different for each tool launch from a different user. When the external tool wants to set a grade for a user, it must present the lis_result_sourcedid for that user/resource combination. This value is completely opaque to the tool - the tool is not supposed to be able to parse or otherwise understand this string - the tool must simply receive the value, store it and then present it when attempting to set a a grade.
This gives the Tool Consumer a wide range of choices as to how it constructs the lis_result_sourcedid. This document describes the particular approach that Sakai will use to create this lis_result_sourcedid.
Another aspect of IMS Outcomes is that results have a "type" in the form of an result_resulttvaluesourcedid - some examples of this may include: decimal, percentage, pass/fail, complete/incomplete. The instructor or administrator will also need to be able to select which of these are acceptable for the returned grades.
Data Model Within Sakai
All of the configuration data such as key, secret, url, and privacy settings, for a Basic LTI tool is stored as properties within the tool placement. This approach is chosen because the data is O(1) and relatively small.
To support this feature, we will add the following new data items in the placements
imslti.assignment=as needed to call gradebookService.setAssignmentScoreString
imslti.gradesecret=random UUID
imslti.gradesecretdate=Date The gradesecret was set
imslti.oldgradesecret=The Immediate prior secret
These will be set as part of the configuration screen of the Basic LTI Portlet in Sakai. These grades will be stored inside the grade service (i.e. they will not be external grades).
Constructing the lis_result_sourcedid
The essential data needed in the lis_result_sourcedid is the placementid and the userid. The key is to make sure that the result_sourcedid cannot be tampered with while the tool in possession of the result_sourcedid. The base string will be as follows:
gradesecret + ':::' + placement-id + ':::' + user-primary-key
A Sha1 signature will be computed from that base string and the result_sourcedid will be:
signature + ':::' + placement-id + ':::' + user-primary-key, gradesecret2
All the other information regarding the gradebook comes from the placement id so there is no need to replicate this information in the result_sourcedid. These is little reason to otherwise encrypt the lis_result_sourcedid as it simply contains information the external tool already knows and with Sakai being open source the method to crate the plaintext will be obviously revealed.
So the only protection needed is to insure the integrity of the placement/userid using a simple message signature. Encrypting the result_sourcedid further would obfuscate the information for no particular purpose.
The lis_result_sourcedid will be sent with Basic LTI launches for which the instructor has configured the tool to receive grades.
Overall Walk Through
This section walks through the entire steps of the process in order.
Instructor places the Basic LTI portlet and configures with the url, secret, and key.
Instructor uses the Basic LTI Portlet config UI to indicate that the tool will be sending grades, and picks the grade book column to store results. This sets the imsti.assignment property in the tool placement and causes the imsti.gradebooksecret property to be set with a random UUID if it is not already set.
Student launches the tool in the consumer The launch includes the lis_result_sourcedid which is the placement id and user id and an integrity signature based on gradebooksecret.
The Tool Provider stores the lis_result_sourcedid for each userid in its tables somewhere, remembering the oauth_consumer_key as well.
Student uses the tool and earns a grade, or perhaps the student uses the tool and the instructor goes into the tool and grades the student work.
Either as a side effect of the student completing the work, or the instructor pressing a "send-grades" button, the tool provider creates a simple-lis-replaceresult message including the lis_result_sourcedid and signing it using OAuth using the oauth_consumer_key which the Tool Consumer used to sign the launch request.
The message is sent to a servlet on the tool consumer.
The servlet parses the lis_result_sourcedid, producing a signature, placement and userid.
The servlet looks up the placement
It then pulls gradesecret from the placement it checks the sourcedid signature
It then looks up the oauth_consumer_key and secret from the placement and checks the OAuth signature of the message.
The servlet verifies that the user is a member of the site
If all of the above tests pass - we use securityAdvisor to set the grade.
The gradebookService.setAssignmentScoreString call implicitly checks to see if the site has a grade book and if the grade book has an appropriately named column. If either fails, the grade book throws an exception.
Comments welcome…
/Chuck