1.3.1 Normative Documents

LTI Advantage Conformance Certification Guide [LTI-CERT-13]

The LTI Advantage Conformance Certification Guide describes the procedures for testing Platforms and Tools against the LTI v1.3 and LTI Advantage services using the IMS certification test suite.

Errata

The errata [LTI-CORE-13-ERRATA] details any erratum registered for this version of this specification since its publication.

1.3.2 Informative Documents

LTI Advantage Implementation Guide [LTI-IMPL-13]

The LTI Advantage Implementation Guide provides information to lead you to successful implementation and certification of the LTI Core v1.3 specification and the set of LTI Advantage specifications.

3.1.1 Historical identification of LTI integration parties

Note that, historically, LTI referred to platforms as tool consumers and referred to tools as tool providers. As this does not align with usage of these terms within the OAuth2 and OpenID Connect communities, LTI 1.3 no longer uses these terms and shifts to the terms platform and tool to describe the parties involved in an LTI integration.

3.1.2 LTI Domain Model

This non-normative diagram illustrates the general LTI domain model as defined in this document. Note that in the case of a single tenant model, some one to many relationships will de facto become one to one; for example, a tool will only have one deployment, a platform a single platform instance.

3.1.3 Tool Deployment

A deployment of a tool defines the scope of contexts under which a tool is made available. For example, a tool may be deployed by the instructor into a single course, or the institution may deploy a tool across the whole institution, available to all institution's contexts, present and future.

When a user deploys a tool within their tool platform, the platform MUST generate an immutable deployment_id identifier to identify the integration. A platform MUST generate a unique deployment_id for each tool it integrates with. Every message between the platform and tool MUST include the deployment_id in addition to the client_id.

A platform must always generate a deployment id even if the tool is only deployed once in the platform (see multi-tenant and single-tenant model below).

A tool MUST thus allow multiple deployments on a given platform to share the same client_id and the security contract attached to it.

3.1.3.2 Multi-tenant: tool registered once, deployed multiple times

In this deployment model, the tool is registered once; during registration, the security contract is established, keys are exchanged and a client_id is created by the platform. The tool may then be subsequently deployed once or multiple times, each deployment identified by its own lti deployment_id.

3.1.3.3 Single tenant: tool registered and deployed once

In this deployment model, the registration and deployment are often done at the same time, the tool only being deployed once under the given client_id; Each deployment gets its own security contract, and there is a one to one relation between the client_id and deployment_id.

3.1.4 LTI Links

An LTI Link is a reference to a specific tool stored by a platform which may, for example, lead to a specific resource or content hosted on the tool, depending on the message_type of the LTI Link (see section § 4.3 Message claims for more information on message_type). The LTI Link is presented by the platform that provides access to the content of the tool and may be used as a means of performing LTI launches within the context of the platform.

Typically, an LTI link contains a URL that points to the tool, along with some other metadata used for identification and presentation purposes that are unique to each link. Often LTI Links are presented to a user as an HTML link, but the two concepts should not be confused - an LTI Link is not just a URL, but may contain additional data that must be included in a launch to the tool.

Each LTI Link MUST be associated with a single deployment_id to identify the tool deployment it is linked to. A platform MAY display multiple instances of the same LTI Link within a page.

Each LTI Link connected to a particular resource (as described in section § 3.2 Contexts and resources below) MUST contain a platform unique identifier named resource_link_id. When an LTI Link is associated with a resource, it is referred to as a Resource Link (see section § 5.1 Resource link for more details).

3.1.5 LTI Launch

An LTI Launch refers to the process in which a user interacts with an LTI Link within the platform and is subsequently "launched" into a tool. The data between tool and platform in establishing a launch are defined upon tool integration into the platform. LTI platforms and tools use messages to transfer the user agent from one host to another through an HTML form post redirection containing the message payload. The data of this payload is determined by the message_type as discussed in section § 4.3.1 Message type and schemas of this document.

4.1.1 lti_message_hint login parameter

The new optional parameter lti_message_hint may be used alongside the login_hint to carry information about the actual LTI message that is being launched.

Similarly to the login_hint parameter, lti_message_hint value is opaque to the tool. If present in the login initiation request, the tool MUST include it back in the authentication request unaltered.

4.1.2 lti_deployment_id login parameter

The new optional parameter lti_deployment_id that if included, MUST contain the same deployment id that would be passed in the https://purl.imsglobal.org/spec/lti/claim/deployment_id claim for the subsequent LTI message launch.

This parameter may be used by the tool to perform actions that are dependent on a specific deployment. An example of this would be, using the deployment id to identify the region in which a tenant linked to the deployment lives. Subsequently changing the redirect_url the final launch will be directed to.

4.1.3 client_id login parameter

The new optional parameter client_id specifies the client id for the authorization server that should be used to authorize the subsequent LTI message request. This allows for a platform to support multiple registrations from a single issuer, without relying on the initiate_login_uri as a key.

4.3.1 Message type and schemas

A message's https://purl.imsglobal.org/spec/lti/claim/message_type claim declares the general intent of the workflow. Each type of message will have its own value for this claim, indicating to the receiver of the message what kind of message the sender has sent.

Each message type has an associated JSON Schema definition that formally defines all its claims, and further defines which of those claims are optional or are required. An example of defining a message type is shown in the table below.

5.3.1 Message type claim

The required https://purl.imsglobal.org/spec/lti/claim/message_type claim's value contains a string that indicates the type of the sender's LTI message. For conformance with this specification, the claim must have the value LtiResourceLinkRequest.

5.3.2 LTI Version claim

The required https://purl.imsglobal.org/spec/lti/claim/version claim's value contains a string that indicates the version of LTI to which the message conforms. For conformance with this specification, the claim must have the value 1.3.0.

5.3.3 LTI Deployment ID claim

The required https://purl.imsglobal.org/spec/lti/claim/deployment_id claim's value contains a case-sensitive string that identifies the platform-tool integration governing the message. It MUST NOT exceed 255 ASCII characters in length.

The deployment_id is a stable locally unique identifier within the iss (Issuer).

The deployment_id is an essential attribute for tools to associate to an account. See the section § 3.1.3 Tool Deployment for more details.

5.3.4 Target Link URI

The required https://purl.imsglobal.org/spec/lti/claim/target_link_uri MUST be the same value as the target_link_uri passed by the platform in the OIDC third party initiated login request.

The target link URI is the actual endpoint for the LTI resource to display; for example, the url in Deep Linking ltiResourceLink items, or the launch_url in IMS Common Cartridges, or any launch URL defined in the tool configuration.

A Tool should rely on this claim rather than the initial target_link_uri to do the final redirection, since the login initiation request is unsigned.

5.3.5 Resource link claim

The required https://purl.imsglobal.org/spec/lti/claim/resource_link claim composes properties for the resource link from which the launch message occurs, as in the following example:

{
...
"https://purl.imsglobal.org/spec/lti/claim/resource_link": {
...
"id": "200d101f-2c14-434a-a0f3-57c2a42369fd",
...
}
...
}

id (REQUIRED). Opaque identifier for a placement of an LTI resource link within a context that MUST be a stable and locally unique to the deployment_id. This value MUST change if the link is copied or exported from one system or context and imported into another system or context. The value of id MUST NOT exceed 255 ASCII characters in length and is case-sensitive.

description (OPTIONAL). Descriptive phrase for an LTI resource link placement.

title (OPTIONAL). Descriptive title for an LTI resource link placement.

5.3.6 User Identity claims

Since any platform-originating message is an OpenID ID Token, user claims are defined in the OpenId Connect Standard Claims [OpenID-14] (section 5.1). LTI messages usually expect the following claims:

sub (Required): This is the only required user claim (except, see anonymous launch case following). When included, per OIDC specifications, the sub (Subject) MUST be a stable locally unique to the iss (Issuer) identifier for the actual, authenticated End-User that initiated the launch. It MUST NOT exceed 255 ASCII characters in length and is case-sensitive.

given_name: Per OIDC specifications, given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

family_name: Per OIDC specifications, surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

name: Per OIDC specifications, end-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.

email: Per OIDC specifications, end-User's preferred e-mail address.

locale: Per OIDC specifications, end-User's preferred locale as a BCP47 language tag.

Note that a platform may also add any other claims from the OpenID Connect Standard Claims list (for example, gender).

5.3.7 Roles claim

The required https://purl.imsglobal.org/spec/lti/claim/roles claim's value contains a (possibly empty) array of URI values for roles that the user has within the message's associated context.

If this list is not empty, it MUST contain at least one role from the role vocabularies described in role vocabularies.

If the sender of the message wants to include a role from another vocabulary namespace, by best practice it should use a fully-qualified URI to identify the role. By best practice, systems should not use roles from another role vocabulary, as this may limit interoperability.

5.4.1 Context claim

The optional https://purl.imsglobal.org/spec/lti/claim/context claim composes properties for the context from within which the resource link launch occurs. The following is an example of this claim as if the resource link launch is in the context of a course:

{
...
"https://purl.imsglobal.org/spec/lti/claim/context": {
"id": "c1d887f0-a1a3-4bca-ae25-c375edcc131a",
"label": "CPS 435",
"title":  "CPS 435 Learning Analytics",
"type": ["http://purl.imsglobal.org/vocab/lis/v2/course#CourseOffering"]
}
...
}

id (REQUIRED). Stable identifier that uniquely identifies the context from which the LTI message initiates. The context id MUST be locally unique to the deployment_id. It is recommended to also be locally unique to iss (Issuer). The value of id MUST NOT exceed 255 ASCII characters in length and is case-sensitive.

type (OPTIONAL). An array of URI values for context types. If present, the array MUST include at least one context type from the context type vocabulary described in context type vocabulary. If the sender of the message wants to include a context type from another vocabulary namespace, by best practice it should use a fully-qualified URI. By best practice, systems should not use context types from another role vocabulary, as this may limit interoperability.

label (OPTIONAL). Short descriptive name for the context. This often carries the "course code" for a course offering or course section context.

title (OPTIONAL). Full descriptive name for the context. This often carries the "course title" or "course name" for a course offering context.

5.4.2 Platform instance claim

The optional https://purl.imsglobal.org/spec/lti/claim/tool_platform claim composes properties associated with the platform instance initiating the launch.

A typical usage is to identify the learning institution's online learning platform as in the following example:

"https://purl.imsglobal.org/spec/lti/claim/tool_platform": {
    "guid": "ex/48bbb541-ce55-456e-8b7d-ebc59a38d435",
    "product_family_code": "ExamplePlatformVendor-ZLMS",
    "name": "LMS from Example University"
}

In a multi-tenancy case, a single platform (iss) will host multiple instances, but each LTI message is originating from a single instance identified by its guid.

guid (REQUIRED). A stable locally unique to the iss identifier for an instance of the tool platform. The value of guid is a case-sensitive string that MUST NOT exceed 255 ASCII characters in length. The use of Universally Unique IDentifier (UUID) defined in [RFC4122] is recommended.

contact_email (OPTIONAL). Administrative contact email for the platform instance.

description (OPTIONAL). Descriptive phrase for the platform instance.

name (OPTIONAL). Name for the platform instance.

url (OPTIONAL). Home HTTPS URL endpoint for the platform instance.

product_family_code (OPTIONAL). Vendor product family code for the type of platform.

version (OPTIONAL). Vendor product version for the platform.

5.4.3 Role-scope mentor claims

The optional https://purl.imsglobal.org/spec/lti/claim/role_scope_mentor claim's value contains an array of the user ID values which the current, launching user can access as a mentor (for example, the launching user may be a parent or auditor of a list of other users), as in the following example:

{
...
  "https://purl.imsglobal.org/spec/lti/claim/role_scope_mentor": [
    "fad5fb29-a91c-770-3c110-1e687120efd9",
    "5d7373de-c76c-e2b-01214-69e487e2bd33",
    "d779cfd4-bc7b-019-9bf1a-04bf1915d4d0"
  ]
...
}

Different systems may use this information in different ways, LTI generally expects that the message receiver will provide the mentor with access to tracking and summary information for other users, but not necessarily access to those users' personal data or content submissions.

The sender of the message MUST NOT include a list of user ID values in this property unless they also provide http://purl.imsglobal.org/vocab/lis/v2/membership#Mentor as one of the values passed in the roles claim.

5.4.4 Launch presentation claim

The optional https://purl.imsglobal.org/spec/lti/claim/launch_presentation claim composes properties that describe aspects of how the message sender expects to host the presentation of the message receiver's user experience (for example, the height and width of the viewport the message sender gives over to the message receiver), as in the following example:

{
...
"https://purl.imsglobal.org/spec/lti/claim/launch_presentation": {
  "document_target": "iframe",
  ...
  "return_url": "https://platform.example.edu/terms/201601/courses/7/sections/1/resources/2"
  }
...
}

document_target (OPTIONAL). The kind of browser window or frame from which the user launched inside the message sender's system. The value for this property MUST be one of: frame, iframe, or window.

height, width (OPTIONAL). Height and width of the window or frame where the content from the message receiver will be displayed to the user.

return_url (OPTIONAL). Fully-qualified HTTPS URL within the message sender's user experience to where the message receiver can redirect the user back. The message receiver can redirect to this URL after the user has finished activity, or if the receiver cannot start because of some technical difficulty.

The message receiver may want to send back a message to the message sender. If the message sender includes a return_url in its launch_presentation, it MUST support these four query parameters that MAY parameterize the redirection to the return URL:

• lti_errormsg, lti_msg. Use these query parameters to carry a user-targeted message for unsuccessful or successful (respectively) activity completion. These are intended for showing to the user.

• lti_errorlog, lti_log. Use these query parameters to carry a log-targeted message for unsuccessful or successful (respectively) activity completion. These are intended for writing to logs.

locale (OPTIONAL). Language, country, and variant as represented using the IETF Best Practices for Tags for Identifying Languages [BCP47].

5.4.5 Learning Information Services LIS claim

The optional https://purl.imsglobal.org/spec/lti/claim/lis claim's value composes properties about available Learning Information Services (LIS), usually originating from the Student Information System, as in the following example:

{
  "https://purl.imsglobal.org/spec/lti/claim/lis": {
    "person_sourcedid": "example.edu:71ee7e42-f6d2-414a-80db-b69ac2defd4",
    "course_offering_sourcedid": "example.edu:SI182-F16",
    "course_section_sourcedid": "example.edu:SI182-001-F16"
  }
}

When the platform instance has access to these values it should, by best practice, provide them in messages sent to tools.

See § D. Using Learning Information Services with LTI) for more detail on this service.

5.4.6 Custom properties and variable substitution

The optional https://purl.imsglobal.org/spec/lti/claim/custom claim acts like a key-value map of defined custom properties that a platform may associate with the resource link that initiated the launch.

Each custom property name appears as a property within the message's top-level custom property. A custom property value must always be of type string. Note that "empty-string" is a valid custom value (""); note also that null is not a valid custom value.

5.4.7 Vendor-specific extension claims

Vendors MAY extend the information model for any message type and inject additional properties into the message's JSON object by adding one or more claims. Vendors MUST use a fully-qualified URL as the claim name for any of their extension claims.

"http://www.ExamplePlatformVendor.com/session": {
  "id": "89023sj890dju080"
}

By best practice, vendors should define custom variables as described in § 5.4.6 Custom properties and variable substitution instead of relying on extension properties.

6.2.1 Deployment ID

A resource server, e.g., platform instance, is uniquely identified by its issuer, client_id, and deployment_id, therefore when requesting an OAuth2 bearer token the client (i.e., tool) SHOULD include the deployment ID as part of the JWT to request a token.

This is an optional claim. In addition to including the client_id, some platforms may require the token to be scoped to a given LTI deployment of that tool, and thus will require the deployment ID to be included in the token request. In the event that a platform refuses to provide a token the platform SHOULD follow the guidance laid out in section 4.1 of the IMS security document

The claim name is https://purl.imsglobal.org/spec/lti/claim/deployment_id

{
    "iss" : "f9660dea-d7ac-4d2c-af4c-97d26bd90d96",
    "sub" : "f9660dea-d7ac-4d2c-af4c-97d26bd90d96",
    "aud" : ["https://www.example.com/lti/auth/token"],
    "iat" : "1485907200",
    "exp" : "1485907500",
    "jti" : "29f90c047a44b2ece73d00a09364d49b",
    "https://purl.imsglobal.org/spec/lti/claim/deployment_id":
      "07940580-b309-415e-a37c-914d387c1150"
}