feat: support proctoring assessment control (#366)

* feat: support assessment control claims

* test: unit tests

* docs: docstring update

* feat: only enable ACS on start message

Author: zacharis278

lti_consumer/data.py

@@ -5,6 +5,8 @@
 
 from attrs import define, field, validators
 
+from lti_consumer.lti_1p3.constants import LTI_PROCTORING_ASSESSMENT_CONTROL_ACTIONS
+
 
 @define
 class Lti1p3ProctoringLaunchData:
@@ -24,9 +26,19 @@ class Lti1p3ProctoringLaunchData:
         assessment message to after it has completed the proctoring setup and verification. This attribute is required
         if the message_type attribute of the Lti1p3LaunchData instance is "LtiStartProctoring". It is optional and
         unused otherwise.
+    * assessment_control_url (optional): The Platform URL that the Tool will send assessment control messages to.
+    * assessment_control_actions (optional): A list of assessment control actions supported by the platform.
     """
     attempt_number = field()
     start_assessment_url = field(default=None)
+    assessment_control_url = field(default=None)
+    assessment_control_actions = field(
+        default=[],
+        validator=[validators.deep_iterable(
+            member_validator=validators.in_(LTI_PROCTORING_ASSESSMENT_CONTROL_ACTIONS),
+            iterable_validator=validators.instance_of(list),
+        )],
+    )
 
 
 @define

lti_consumer/lti_1p3/constants.py

@@ -85,4 +85,19 @@ class LTI_1P3_CONTEXT_TYPE(Enum):  # pylint: disable=invalid-name
     course_template = 'http://purl.imsglobal.org/vocab/lis/v2/course#CourseTemplate'
 
 
-LTI_PROCTORING_DATA_KEYS = ['attempt_number', 'resource_link_id', 'session_data', 'start_assessment_url']
+LTI_PROCTORING_DATA_KEYS = [
+    'attempt_number',
+    'resource_link_id',
+    'session_data',
+    'start_assessment_url',
+    'assessment_control_url',
+    'assessment_control_actions'
+]
+
+LTI_PROCTORING_ASSESSMENT_CONTROL_ACTIONS = [
+    'pauseRequest',
+    'resumeRequest',
+    'terminateRequest',
+    'update',
+    'flagRequest',
+]

lti_consumer/lti_1p3/consumer.py

@@ -822,6 +822,17 @@ def get_start_proctoring_claims(self):
 
         return proctoring_claims
 
+    def get_assessment_control_claim(self):
+        """
+        Returns LTI Proctoring Services ACS Claim to be injected in the LTI launch message.
+        """
+        return {
+            "https://purl.imsglobal.org/spec/lti-ap/claim/acs": {
+                "assessment_control_url": self.proctoring_data.get("assessment_control_url"),
+                "actions": self.proctoring_data.get("assessment_control_actions"),
+            }
+        }
+
     def get_end_assessment_claims(self):
         """
         Returns claims specific to LTI Proctoring Services LtiEndAssessment LTI launch message,
@@ -849,6 +860,12 @@ def generate_launch_request(
 
         if launch_data.message_type == "LtiStartProctoring":
             proctoring_claims = self.get_start_proctoring_claims()
+
+            # Enable ACS if assessment_control_url is present on the launch data.
+            # Normally we would enable this using a field on the LtiConfiguration model like other
+            # Advantage services, but this isn't actually optional or configurable for Open edX.
+            if self.proctoring_data.get("assessment_control_url"):
+                self.set_extra_claim(self.get_assessment_control_claim())
         elif launch_data.message_type == "LtiEndAssessment":
             proctoring_claims = self.get_end_assessment_claims()
         else:

lti_consumer/lti_1p3/tests/test_consumer.py

@@ -1009,6 +1009,27 @@ def test_get_end_assessment_claims(self):
 
         self.assertEqual(expected_get_end_assessment_claims, actual_get_end_assessment_claims)
 
+    def test_assessment_control_claims(self):
+        """
+        Ensure the correct claims are returned for the assessment control service.
+        """
+        self.lti_consumer.set_proctoring_data(
+            attempt_number="attempt_number",
+            session_data="session_data",
+            start_assessment_url="start_assessment_url",
+            assessment_control_url="assessment_control_url",
+            assessment_control_actions=["flagRequest", "terminateRequest"],
+        )
+        proctoring_acs_claims = self.lti_consumer.get_assessment_control_claim()
+
+        expected_acs_claims = {
+            "https://purl.imsglobal.org/spec/lti-ap/claim/acs": {
+                "assessment_control_url": "assessment_control_url",
+                "actions": ["flagRequest", "terminateRequest"],
+            },
+        }
+        self.assertDictEqual(proctoring_acs_claims, expected_acs_claims)
+
     @ddt.data("LtiStartProctoring", "LtiEndAssessment")
     @patch('lti_consumer.lti_1p3.consumer.get_data_from_cache')
     def test_generate_launch_request(self, message_type, mock_get_data_from_cache):
@@ -1045,6 +1066,36 @@ def test_generate_launch_request(self, message_type, mock_get_data_from_cache):
         for claim in expected_claims.items():
             self.assertIn(claim, decoded_token_claims)
 
+    @patch('lti_consumer.lti_1p3.consumer.get_data_from_cache')
+    def test_enable_assessment_control(self, mock_get_data_from_cache):
+        """
+        Ensure that the correct claims are included in LTI launch messages with an ACS url set.
+        """
+
+        mock_launch_data = self.get_launch_data(message_type="LtiStartProctoring")
+        mock_get_data_from_cache.return_value = mock_launch_data
+        self._setup_proctoring()
+
+        self.lti_consumer.set_proctoring_data(
+            attempt_number="attempt_number",
+            session_data="session_data",
+            start_assessment_url="start_assessment_url",
+            assessment_control_url="assessment_control_url",
+            assessment_control_actions=["flagRequest", "terminateRequest"],
+        )
+
+        token = self.lti_consumer.generate_launch_request(
+            self.preflight_response,
+        )['id_token']
+
+        decoded_token = self.lti_consumer.key_handler.validate_and_decode(token)
+        expected_claims = self.lti_consumer.get_start_proctoring_claims()
+        expected_claims.update(self.lti_consumer.get_assessment_control_claim())
+
+        decoded_token_claims = decoded_token.items()
+        for claim in expected_claims.items():
+            self.assertIn(claim, decoded_token_claims)
+
     @patch('lti_consumer.lti_1p3.consumer.get_data_from_cache')
     def test_generate_launch_request_invalid_message(self, mock_get_data_from_cache):
         """

lti_consumer/plugin/views.py

@@ -275,7 +275,9 @@ def launch_gate_endpoint(request, suffix=None):  # pylint: disable=unused-argume
             lti_consumer.set_proctoring_data(
                 attempt_number=launch_data.proctoring_launch_data.attempt_number,
                 session_data=session_data,
-                start_assessment_url=launch_data.proctoring_launch_data.start_assessment_url
+                start_assessment_url=launch_data.proctoring_launch_data.start_assessment_url,
+                assessment_control_url=launch_data.proctoring_launch_data.assessment_control_url,
+                assessment_control_actions=launch_data.proctoring_launch_data.assessment_control_actions,
             )
         elif launch_data.message_type == 'LtiEndAssessment':
             lti_consumer.set_proctoring_data(