From d2d105ef0eef54be3027cb3ab9855eef845d4491 Mon Sep 17 00:00:00 2001
From: Giovanni Cimolin da Silva <giovannicimolin@gmail.com>
Date: Wed, 3 Mar 2021 19:12:19 -0300
Subject: [PATCH] [BD-24][TNL-7919] LTI Advantage Names and Roles provisioning
service implementation direction (#142)
* Add wip ADR about NRPS
* Nit
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Address nits
* Write a bit more
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Update docs/decisions/0004-lti-advantage-nrps.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* Nits
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
---
docs/decisions/0004-lti-advantage-nrps.rst | 115 +++++++++++++++++++++
1 file changed, 115 insertions(+)
create mode 100644 docs/decisions/0004-lti-advantage-nrps.rst
diff --git a/docs/decisions/0004-lti-advantage-nrps.rst b/docs/decisions/0004-lti-advantage-nrps.rst
new file mode 100644
index 0000000..65d4e80
--- /dev/null
+++ b/docs/decisions/0004-lti-advantage-nrps.rst
@@ -0,0 +1,115 @@
+LTI Advantage NRPS (Names and Roles provisioning services)
+----------------------------------------------------------
+
+Status
+======
+
+Accepted
+
+Context
+=======
+
+One of the LTI Advantage services is the `Names and Roles Provisioning Services (NRPS)`_, which allows LTI tools
+to retrieve a user list associated with the learning context and internally provision resources for them.
+
+From the LTI-NRPS Specification:
+
+ The Names and Role Provisioning Services is based on IMS Learning Information Services (LIS) [LIS-20]
+ and W3C Organization Ontology [W3C-ORG]. It is concerned with providing access to data about users’ roles
+ within organizations, a course being an example of an organization. So a very common purpose for this service
+ is to provide a roster (list of enrolments) for a course.
+
+An LTI-NRPS services implementation consists of two services which provide user data in the following format:
+
+.. code-block:: json
+ {
+ "id" : "https://lms.example.com/sections/2923/memberships",
+ "context": {
+ "id": "2923-abc",
+ "label": "CPS 435",
+ "title": "CPS 435 Learning Analytics",
+ },
+ "members" : [
+ {
+ "status" : "Active",
+ "name": "Jane Q. Public",
+ "picture" : "https://platform.example.edu/jane.jpg",
+ "given_name" : "Jane",
+ "family_name" : "Doe",
+ "middle_name" : "Marie",
+ "email": "jane@platform.example.edu",
+ "user_id" : "0ae836b9-7fc9-4060-006f-27b2066ac545",
+ "lis_person_sourcedid": "59254-6782-12ab",
+ "roles": [
+ "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor"
+ ]
+ }
+ ]
+ }
+
+Where the only required fields for each member are :code:`user_id` and :code:`roles`, to avoid unintended PII transmission to a third party.
+But since one of the purposes of this API is to enable tools access to user PII, the implementation should provide a flag to enable the consumer
+to pass additional PII parameters such as name, email, and a profile picture url.
+
+The main issue with enabling this API (`even with pagination as defined in the spec`_) is that it would allow external third-party tools to scrape enrollments for all
+students in a given course. Given the scale of some courses in edX.org, even if the API is made more performant with cursor pagination,
+we're still left with an API pattern that would be actively encouraging clients out there to make hundreds of thousands of successive requests in order
+to crawl enrollment data.
+
+.. _Names and Roles Provisioning Services (NRPS): http://www.imsglobal.org/spec/lti-nrps/v2p0
+.. _even with pagination as defined in the spec: http://www.imsglobal.org/spec/lti-nrps/v2p0#limit-query-parameter
+
+Decision
+========
+
+Implement the LTI NRPS for courses up to a predefined (and configurable) number of active enrollments.
+Above that number, the service endpoint will return HTTP status 403 (Forbidden).
+
+This is the simplest implementation that allows us to provide the LTI NRPS service and mitigate the concerns mentioned above.
+The NRPS services availability and behavior will be controlled by the following toggles:
+
+.. list-table::
+ :widths: auto
+ :header-rows: 1
+
+ * - Toggle name
+ - Type
+ - Behavior
+ * - LTI_NRPS_ENABLED
+ - Feature flag
+ - Enables and disables LTI NRPS globally in the Open edX instance. Is disabled by default.
+ * - LTI_NRPS_ACTIVE_ENROLLMENT_LIMIT
+ - Django setting
+ - Controls the allowed number of active enrollments when the API is enabled.
+ Defaults to 1000 active enrollments at first.
+ * - LTI_NRPS_TRANSMIT_PII
+ - CourseWaffleFlag
+ - Allows the tool to access student and instructor PII (username, email, full name, profile picture).
+ Defaults to False.
+
+
+Consequences
+============
+
+* Small courses will be able to use LTI NRPS endpoints on their tools, up to a limited amount of users.
+* Big MOOCs (with millions of users) won't allow scraping of enrollment data on edX and potentially cause stability issues.
+
+
+Discarded solutions
+===================
+
+Don't implement NRPS
+~~~~~~~~~~~~~~~~~~~~
+This would not enable course creators to use LTI advantage tools that make use of this functionality.
+
+Implement NRPS gated by course
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+While this would work, it adds a maintenance burden of keeping and updating a whitelist.
+Also, long running MOOCs can grow to sizes that could potentially affect instance stability when
+using the API.
+
+Implement NRPS limiting the context of the data retrieved
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Complex to implement given the benefit. To get consistency on the LTI tool side, the implementation
+would need to create user groups and effectively isolate them in the tool (potentially using a different resourceLink),
+which doesn't work for a few LTI integrations (forums, course wide leaderboard, instructor grading inside the tool and others).
--
GitLab