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 14, SEC].
3.1 LISMembership Service
The following capability is defined for this service:
- ToolProxyBinding.memberships.url – the endpoint URL for accessing the membership container for the current context.
In order for a tool to be able to use the membership service, the tool consumer must have advertised its availability in the profile it offered the tool provider and, for LTI 2, the tool must have declared its intention to use the service in the tool proxy it agrees with the tool consumer. The ToolProxyBinding.memberships.url capability should also have been offered and accepted by the tool consumer and tool provider, respectively.
{
"@context" : [
"http://purl.imsglobal.org/ctx/lti/v2/ToolConsumerProfile",
{
"tcp" : "http://lms.example.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#"
}
],
"@type" : "ToolConsumerProfile",
...
"capability_offered" : [
...
" ToolProxyBinding.memberships.url",
...
],
"service_offered" : [
{
"@type" : "RestService",
"@id" : "tcp:Membership.collection",
"format" : "application/vnd.ims.lis.v2.membershipcontainer+json",
"endpoint" : "https://lms.example.com/context/{context_id}/memberships",
"action" : [
"GET"
]
}
]
...
}
Figure 3.1 Descriptor of Names and Role Provisioning Services advertised in the Tool Consumer Profile
In LTI 1, tool consumers should pass the endpoint as a custom parameter with the name of custom_context_memberships_url.
{
"@context" : [
"http://purl.imsglobal.org/ctx/lti/v2/ToolProxy",
{
"tcp" : "http://lms.example.com/profile/b6ffa601-ce1d-4549-9ccf-145670a964d4#"
}
]
"@type" : "ToolProxy",
...
"security_contract" : {
...
"tool_service" : [
{
"@type" : "RestServiceProfile",
"service" : "tcp:Membership.collection",
"action" : [
"GET"
]
}
],
...
}
...
}
Figure 3.2 Tool Provider declares intention to use Names and Role Provisioning Services
3.2 Membership container media type
The accompanying HTML documentation defines the following media type used by the membership service:
- application/vnd.ims.lis.v2.membershipcontainer+json
{
"@context" : [
"http://purl.imsglobal.org/ctx/lis/v2/MembershipContainer",
{
"liss" : "http://purl.imsglobal.org/vocab/lis/v2/status#",
"lism" : "http://purl.imsglobal.org/vocab/lis/v2/membership#"
}
],
"@type" : "Page",
"@id" : "http://lms.example.com/sections/2923/memberships/?rlid=49566-rkk96",
"nextPage" : "http://lms.example.com/sections/2923/memberships/?rlid=49566-rkk96&p=2",
"differences" : "http://lms.example.com/sections/2923/memberships/?x=1422554502",
"pageOf" : {
"@type" : "LISMembershipContainer",
"membershipSubject" : {
"@type" : "Context",
"contextId" : "2923-abc",
"membership" : [
{
"status" : "liss:Active",
"member" : {
"@type" : "LISPerson",
"sourcedId" : "school.edu:user",
"userId" : "0ae836b9-7fc9-4060-006f-27b2066ac545",
"email" : "user@school.edu",
"familyName" : "Public",
"name" : "Jane Q. Public",
"image" : "http://...",
"givenName" : "Jane"
},
"message" : [
{
"message_type" : "basic-lti-launch-request",
"lis_result_sourcedid" : "83873872987329873264783687634",
"ext" : {
"user_username" : "jpublic"
},
"custom" : {
"country" : "Canada",
"user_mobile" : "123-456-7890"
}
}
],
"role" : [
"lism:Instructor"
]
}
]
}
}
}
Figure 3.3 Example of application/vnd.ims.lis.v2.membershipcontainer+json media type
This default context must always be http://purl.imsglobal.org/ctx/lis/v2/MembershipContainer. When either of the http://purl.imsglobal.org/vocab/lis/v2/status and http://purl.imsglobal.org/vocab/lis/v2/membership contexts are used they must be defined with prefixes of liss and lism, respectively. The member element contains only those properties which are specific to the user independent of any context. It should only contain the properties which would be passed about the user in an LTI message, such as a Basic LTI Launch; any properties about a user which would never be passed to the Tool Provider must be omitted. This service is not a mechanism for obtaining more data about a user; it is solely designed to alter the timing at which a Tool Provider is able to obtain access to a user's data.
When the memberships list is being filtered to reflect those users who can access a specific resource link (see below), a message array should be included for each member containing an element for a basic-lti-launch-request message type. This element must contain any context or resource-link specific message parameters, including any extension (prefixed with ext_) or custom (prefixed with custom_) parameters, which would be included in a launch message from the specified resource link and which contain data specific to the member. The name of the parameter as it would be passed in the message (for example, lis_result_sourcedid) should be used with its corresponding value. For example, any custom parameter whose value uses a $User or $Person substitution variable must be included. Extension and custom parameters should be included within elements named ext and custom, respectively and omit the prefixes to their names.
3.2.1 Membership status
Each membership has a status of either Active or Inactive. If the status is not specified then a status of Active should 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.
3.3 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.lis.v2.membershipcontainer+json and a signature in the Authorization header [LTI, 14 SEC].
3.3.1 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 basic-lti-launch-request message.
3.3.2 Resource Link ID query parameter
The membership list being requested will be specific to a context. This list may be further modified by limiting it to only those members who have access to a specified resource link. In this case the message element for each member will also include any parameters which are specific to that user and resource link; for example, the lis_result_sourcedid parameter which is used to access the gradebook cell for a user in respect of the activity associated with a resource link - see the Basic Outcomes service [LTI, 12]. For example, a query parameter of rlid=49566-rkk96 will filter the memberships to just those which have access to the resource link with ID 49566-rkk96.
3.3.3 Limit query parameter
The Tool Provider may specify a maximum number of members to be returned in the response from the Tool Consumer. The Tool Consumer 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 Tool Consumer does not comprise all of the members a nextPage element will be included to indicate how to request the next set of members. The absence of a nextPage element indicates that no more members are available.
3.3.4 Membership differences
A response by the Names and Role Provisioning Services may include a differences element. When present this will specify a URL which may be used to obtain a report of all the differences between the current memberships and those reported in this response. If a membership has been deleted during the interim period, it will 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 current state of the membership. This option is not intended to provide a history of all the changes which have taken place, merely to report any differences between the current state and the state at the time the URL was supplied. A tool consumer should aim to support the URL at least until it has been used or a subsequent request for a full membership list has been made (or a request using the same value for the role parameter). That is, there is only a requirement for tool consumers to maintain one differences URL for each form of request at any one time; once a new differences URL has been issued for the same set of memberships any previous ones may be discarded.
