Fix LTI 1.1 Basic Outcomes Service and LTI 2.0 Result Service to Support External User IDs

[michaelroytman]

Description

In #307, we added the ability to send a stable, static user identifier (i.e. external user ID) to fix failed launches with the QwikLabs tool. This is because the QwikLabs tool did not work with the course-anonymized user IDs we used to send (i.e. anonymous user IDs). Inadvertently, this change broke the LTI 1.1 Basic Outcomes Service and the LTI 2.0 Result Service for courses that use the external user ID (i.e. they have the lti_consumer.enable_external_user_id_1p1_launches CourseWaffleFlag enabled). The Basic Outcomes Service and Result Service handle grade pass backs. Because we now have two ways to identify a user in LTI 1.1/2.0, we must update the Basic Outcomes Service and Result Service to support both.

Testing Instructions

Testing these is a little complex. I've tried to be as comprehensive as I can be with the instructions here, but please reach out if you have trouble.

LTI 1.1 Basic Outcomes Service

• Set up devstack.

• Create an LTI 1.1 component in Studio, following the instructions in the README.

• Set up your preferred API testing tool (e.g. Postman) to send a POST request.

  • URL: <BASIC_OUTCOMES_URL>
  • Body: raw
    • Be sure to update the sourcedId XML component appropriately.

  <?xml version="1.0" encoding="UTF-8"?>
  <imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>course-v1%3AedX%2B1717N1%2BY2022N1:localhost%3A18000-1bca781ee09347a6800ad29c346abc07:1bc0b578-6f17-4e32-917a-94dc63edddda</sourcedId>
        </sourcedGUID>
        <result>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
  </imsx_POXEnvelopeRequest>

• The basic_outcomes_url can be retrieved viewing the live LTI component in the LMS, if you’re using the SaLTIre tool, because it displays this value for you. If it does not, you can retrieve it by using the LTI rest endpoints view.

  • Go to https://<LMS_DOMAIN>/courses/<COURSE_ID>/lti_rest_endpoints/, find your component, and select the lti_1_1_result_service_xml_endpoint. Note that you should use http with devstack.

• Open a Python shell and install the oauthlib Python module.

  • Alternatively, you can open a Django shell in the LMS/Studio devstack shells. It is installed there as a necessary dependency of xblock-lti-consumer.

• Open a Python shell and enter the following commands. client_key and client_secret come from your LTI passport string. The ones below come from the SaLTIre testing tool, as described in the xblock-lti-consumer README file.

  >>> from oauthlib import oauth1
  >>> client_key="test"
  >>> client_secret="secret"
  >>> client = oauth1.Client(client_key=client_key, client_secret=client_secret)
  >>> basic_outcomes_url = "http://localhost:18000/courses/course-v1:edX+1717N1+Y2022N1/xblock/block-v1:edX+1717N1+Y2022N1+type@lti_consumer+block@1bca781ee09347a6800ad29c346abc07/handler_noauth/outcome_service_handler"
  >>> xml_body = """<?xml version="1.0" encoding="UTF-8"?>
  <imsx_POXEnvelopeResponse xmlns = "http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
      <imsx_POXHeader>
          <imsx_POXResponseHeaderInfo>
              <imsx_version>V1.0</imsx_version>
              <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
              <imsx_statusInfo>
                  <imsx_codeMajor>failure</imsx_codeMajor>
                  <imsx_severity>status</imsx_severity>
                  <imsx_description>User not found.</imsx_description>
                  <imsx_messageRefIdentifier>
                  </imsx_messageRefIdentifier>
              </imsx_statusInfo>
          </imsx_POXResponseHeaderInfo>
      </imsx_POXHeader>
      <imsx_POXBody></imsx_POXBody>
  </imsx_POXEnvelopeResponse>"""
  >>> uri, headers, body = client.sign(basic_outcomes_url, http_method="POST", body=xml_body, headers={"Content-Type": "text/xml"})

  • If you have issues with the oauth_body_hash not matching, make sure that your xml_body matches the body variable in verify_oauth_body_signature. A breakpoint can be helpful.

• headers should look something like this.

{'Content-Type': 'text/xml', 'Authorization': 'OAuth oauth_nonce="5609288327616222561669665375", oauth_timestamp="1669665375", oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="test", oauth_body_hash="vAVegN28HcixFW7OuHgfx0Ld%2Bdk%3D", oauth_signature="4Or9QJKG66jFHpZU6JeyNHcYdDk%3D"'}

• Take the Authorization header and use it in your preferred API testing tool (e.g. Postman). For example, in Postman, you should have something like the following header mapping.
• Note: If you’re switching between anonymous user IDs and external user IDs, you’ll need to update your XML in Postman and recompute the Authorization header using the instructions above.

LTI 2.0 Result Service

To send a Result Service request in devstack, follow these steps.

• Set up devstack.

• Create an LTI 1.1 component in Studio, following the instructions in the README.

• Set up your preferred API testing tool (e.g. Postman) to send a PUT/GET request.

  • Set the request method to GET or PUT.
  • URL: <RESULT_SERVICE_URL>
  • Body: raw
    • Be sure to update the JSON appropriately.
    • NOTE: Do NOT set the content type to JSON. Leave it as raw, text.

  {
      "@context" : "http://purl.imsglobal.org/ctx/lis/v2/Result",
      "@type" : "Result",
      "resultScore" : 0.83,
      "comment" : "This is exceptional work."
  }

• The result_service_url can be retrieved viewing the live LTI component in the LMS, if you’re using the SaLTIre tool, because it displays this value for you. If it does not, you can retrieve it by using the LTI rest endpoints view.

  • Go to https://<LMS_DOMAIN>/courses/<COURSE_ID>/lti_rest_endpoints/, find your component, and select the lti_2_0_result_service_json_endpoint. Note that you should use http with devstack.
  • If you’re making a PUT request, under Headers, set the Content Type header to application/vnd.ims.lis.v2.result+json.

• Open a Python shell and install the oauthlib Python module.

  • Alternatively, you can open a Django shell in the LMS/Studio devstack shells. It is installed there as a necessary dependency of xblock-lti-consumer.

• Open a Python shell and enter the following commands. client_key and client_secret come from your LTI passport string. The ones below come from the SaLTIre testing tool, as described in the xblock-lti-consumer README file.

  >>> from oauthlib import oauth1
  >>> client_key="test"
  >>> client_secret="secret"
  >>> client = oauth1.Client(client_key=client_key, client_secret=client_secret)
  >>> result_service_url = "http://localhost:18000/courses/course-v1:edX+1717N1+Y2022N1/xblock/block-v1:edX+1717N1+Y2022N1+type@lti_consumer+block@1bca781ee09347a6800ad29c346abc07/handler_noauth/result_service_handler/user/1bc0b578-6f17-4e32-917a-94dc63edddda"
  >>> json_body = """{
  >>>     "@context" : "http://purl.imsglobal.org/ctx/lis/v2/Result",
  >>>     "@type" : "Result",
  >>>     "resultScore" : 0.83,
  >>>     "comment": "This is exceptional work."
  >>> }"""
  >>> uri, headers, body = client.sign(result_service_url, http_method="PUT", body=json_body, headers={"Content-Type": "application/vnd.ims.lis.v2.result+json"})

  • If you have issues with the oauth_body_hash not matching, make sure that your xml_body matches the body variable in verify_oauth_body_signature. A breakpoint can be helpful.
    • Note: Be sure the json_body matches exactly what is in Postman, including whitespace characters (e.g. spaces versus tabs).

• headers should look something like this.

{'Content-Type': 'text/xml', 'Authorization': 'OAuth oauth_nonce="5609288327616222561669665375", oauth_timestamp="1669665375", oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="test", oauth_body_hash="vAVegN28HcixFW7OuHgfx0Ld%2Bdk%3D", oauth_signature="4Or9QJKG66jFHpZU6JeyNHcYdDk%3D"'}

• Take the Authorization header and use it in your preferred API testing tool (e.g. Postman). For example, in Postman, you should have something like the following header mapping.

Authorization: OAuth oauth_nonce="5609288327616222561669665375", oauth_timestamp="1669665375", oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="test", oauth_body_hash="vAVegN28HcixFW7OuHgfx0Ld%2Bdk%3D", oauth_signature="4Or9QJKG66jFHpZU6JeyNHcYdDk%3D"

• Note: If you’re switching between anonymous user IDs and external user IDs, you’ll need to update your URL in Postman and recompute the Authorization header using the instructions above.

Manual Testing

I performed the following manual tests.

• Tested LTI 1.1/2.0 component with lti_consumer.enable_external_user_id_1p1_launches flag on, sent Basic Outcomes Service request with external user ID
• Tested LTI 1.1/2.0 component with lti_consumer.enable_external_user_id_1p1_launches flag off, sent Basic Outcomes Service request with anonymous user ID
• Tested LTI 1.1/2.0 component with lti_consumer.enable_external_user_id_1p1_launches flag on, sent Result Service request with external user ID
• Tested LTI 1.1/2.0 component with lti_consumer.enable_external_user_id_1p1_launches flag off, sent Result Service request with anonymous user ID

[michaelroytman]

This adds support for UUID user IDs. Otherwise, it lops off part of the user ID.

[ashultz0]

this must have been maddening to find

[codecov]

Codecov Report

Base: 97.78% // Head: 97.76% // Decreases project coverage by -0.02% ⚠️

Coverage data is based on head (212455f) compared to base (418b1e3).
Patch coverage: 96.15% of modified lines in pull request are covered.

❗ Current head 212455f differs from pull request most recent head 3bbbdd5. Consider uploading reports for the commit 3bbbdd5 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #310      +/-   ##
==========================================
- Coverage   97.78%   97.76%   -0.03%     
==========================================
  Files          72       72              
  Lines        5875     5910      +35     
==========================================
+ Hits         5745     5778      +33     
- Misses        130      132       +2     

Flag	Coverage Δ
unittests	97.76% <96.15%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
lti_consumer/lti_xblock.py	95.27% <77.77%> (-0.39%)	⬇️
lti_consumer/outcomes.py	100.00% <100.00%> (ø)
lti_consumer/tests/unit/test_lti_xblock.py	99.14% <100.00%> (+0.01%)	⬆️
lti_consumer/tests/unit/test_outcomes.py	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[michaelroytman]

I think this is right, based on #249.

[ashultz0]

yeah that looks like the sort of replacement done there: https://github.com/openedx/xblock-lti-consumer/pull/249/files#diff-6e408862179502a0ac809fab914e028b18311a17a3b0874469bd6416bc4a449fL73

[ashultz0]

since the IDs are different formats we could detect that difference, but this seems cleaner

[ashultz0]

this set of ==== shouldn't be in the changelog, I left it in there when I was resolving conflicts

😞

[ashultz0]

nice variable name change here

[ashultz0]

👍 shipit

after shipping please capture those test instructions into a doc ideally in the repo or at least in the wiki, they're very useful