Overview

The Names and Role Provisioning Services is based on IMS Learning Information Services (LIS) Learning Information Services Version 2.0 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.

Terminology

Organization

An organization is a collection of people organized into a group for a common purpose or specific reason. Organizations can be part of a hierarchical structure.

Role

The type of involvement a person has within an organization. In the case of a course, the typical roles are Instructor, Teaching Assistant and Learner.

Membership

A relationship between a person and an organization which involves at least one role. A person cannot be a member of an organization without being assigned a role.

Tool Platform and Tool

This version of the specification uses the LTI 1.3 terminology of Tool Platform and Tool, which respectively refer to Tool Consumer and Tool Provider used in the previous LTI specifications.

Context Membership

Membership container media type

The accompanying HTML documentation defines the following media type used by the membership service:

• 'application/vnd.ims.lti-nrps.v2.membershipcontainer+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 M. Doe",
      "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",
      "lti11_legacy_user_id": "668321221-2879",
      "roles": [
        "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor"
      ]
    }
  ]
}

Sharing of personal data

Which member data is actually passed to the Tool relies on the agreement between the Platform and the Tool. At a minimum, the member must contain:

• user_id: as communicated in the LtiResourceLinkRequest under sub
• roles: an array of roles with values as defined in LTI Core Version 1.3

A context parameter must be present that must contain:

• id: id of the context

Any other member attributes will need an explicit consent from the Platform to be shared with the Tool. The Platform may delegate that consent to the actual member, therefore a Tool should never rely on additional member attributes to be present.

Membership status

Each membership has a status of either Active or Inactive. If the status is not specified then a status of Active must be assumed.

When reporting differences a membership (see below) may have a status of Deleted which means that the membership no longer exists. A normal request for a memberships list will only return current memberships and hence none will have a status of Deleted.

Using the service

The only action defined for this service is an HTTP GET request. This should be sent to the endpoint provided and include an 'Accept' header with a value of 'application/vnd.ims.lti-nrps.v2.membershipcontainer+json'. The request must be properly secured as per the LTI Security Framework used by the LTI integration.

Role query parameter

By default all the current memberships will be returned by a request to this service. However, this may be limited to only those memberships with a specified role by passing its URI in a query parameter named 'role'. For example, a query parameter of 'role=http%3A%2%2Fpurl.imsglobal.org%2Fvocab%2Flis%2Fv2%2Fmembership%23Learner' will filter the memberships to just those which have a Learner role. Since this is a context-level role, the parameter could be simplified to 'role=Learner', following the same rule which applies to the 'roles' parameter in a 'LtiResourceLinkRequest' message.

Limit query parameter

The Tool may specify a maximum number of members to be returned in the response from the Platform. The Platform may use this as a guide to the number it returns but may include more or less than the value provided. If the response from a Platform does not comprise all of the members a rel="next" header link will be included to indicate how to request the next set of members. The absence of a rel="next" header link indicates that no more members are available. See [[!RFC8288]].

Link: <https://lms.example.com/sections/2923/memberships?p=2>; rel="next"

Membership differences

A response by the Names and Role Provisioning Services may include a rel="differences" header link. When present, this URL should be complete and opaque; users of this URL should not need to decorate it further (nor should further decoration be necessarily supported). When present this will specify a differences URL which the service user may use to obtain a report of all the differences in the membership between the time the differences URL was created and the time the URL is used (the current time). If a membership has been deleted during this interim period, it may be included in the response with a status of Deleted. All other entries in the response represent memberships which have been added or changed; for the latter the entry will be the state of the membership at the current time. This option is not intended to provide a history of all the changes which have taken place, merely to report any differences between the state of a membership at the current time and the state of the entire roster at the time the differences URL was created and provided in the initial service response. For example, a platform might provide this differences URL, encoding the earliest time to begin considering roster differences to report (there is no requirement for platforms to use this pattern, however). See [[!RFC8288]].

Link: <https://lms.example.com/sections/2923/memberships?since=1422554502>; rel="differences"

Resource Link Membership Service

Optionally, a platform may offer a Resource Link level membership service. The endpoint is the same as the context membership service. The tool needs to append an additional query parameter rlid with a value of the Resource Link id as communicated in LtiResourceLinkRequest https://purl.imsglobal.org/spec/lti/claim/resource_link claim.

Filtering per role, using limit and differences as defined above also apply to Resource Link membership service.

• 'application/vnd.ims.lti-nrps.v2.membershipcontainer+json'

{
  "id" : "https://lms.example.com/sections/2923/memberships?rlid=49566-rkk96",
  "context": {
    "id": "2923-abc",
    "label": "CPS 435",
    "title": "CPS 435 Learning Analytics"
  },
  "members" : [
    {
      "status" : "Active",
      "name": "Jane M. Doe",
      "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": [
        "Instructor",
        "Mentor"
      ],
      "message" : [
        {
          "https://purl.imsglobal.org/spec/lti/claim/message_type" : "LtiResourceLinkRequest",
          "https://purl.imsglobal.org/spec/lti-bo/claim/basicoutcome" : {
            "lis_result_sourcedid": "example.edu:71ee7e42-f6d2-414a-80db-b69ac2defd4",
            "lis_outcome_service_url": "https://www.example.com/2344"
          },
          "https://purl.imsglobal.org/spec/lti/claim/custom": {
            "country" : "Canada",
            "user_mobile" : "123-456-7890"
          }
        }
      ]
    }
  ]
}

Access restriction

A platform must deny access to this request if the Resource Link is not owned by the Tool making the request or the resource link is not present in the Context.

Message section

When queried in the context of a Resource Link, an additional message section is added per member. This element must contain any context or resource link specific message parameters, including any extension or custom parameters, which would be included in the message from the specified Resource Link and which contain data specific to the member.

The parameters must be included using the LTI 1.3 claims format defined in LTI Core Version 1.3.

Membership filtered

A platform may return a subset of the context memberships, reflecting which members can actually access the Resource Link.

Basic Outcome

The ability to query Resource Link membership has usually been used to discover the lis_result_sourcedid ahead of the learner actually launching the resource. If the Tool integration still relies on Basic Outcome, the platform should include in the message section the Basic Oucome claim https://purl.imsglobal.org/spec/lti-bo/claim/basicoutcome as defined in [[LTI-BO-10]].

Substitution parameters

Any substitution parameters pertaining to member information should be resolved. For example, any custom parameter whose value uses a '$User' or '$Person' substitution variable should be included and resolved if supported by the platform.

Binding with LTI Core

LTI 1.3 integration

Claim for inclusion in LTI messages

The claim to include Names and Role Provisioning Service parameter in LTI 1.3 messages is: https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice.

It contains 2 properties: context_memberships_url (service url) and service_version. The service URL is always fully resolved, and matches the context of the launch. The service_versions specifies the versions of the service that are supported on that end point.

"https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice": {
    "context_memberships_url": "https://www.myuniv.example.com/2344/memberships",
    "service_versions": ["2.0"]
}

Scope and Service security

All service requests should be secured by including a properly scoped access token in the Authorization header as per the IMS Global Security Framework IMS Security Framework Version 1.0.

The scope to request to access this service is:

LTI 1.1 integration

A platform may offer this version of the service to LTI 1.1 tools.

The service endpoint is passed using the custom parameter: custom_context_memberships_v2_url.

All service requests should be secured by signing them using the lti_oauth_body_hash_ws_security Web Services Security Profile as described in the Security document [[LTI-SEC-14]].

Use LTI 1.3 message type name and claims

When accessing membership for a given resource link id, the message type used in the message section must be LtiResourceLinkRequest, not basic-lti-launch-request even if this version of the service is used under a 1.1 integration.

The message section must use the LTI 1.3 claims format.