LTI postMessage Storage
Spec Version 0.1
Document Version: | 4 |
Date Issued: | October 17th, 2022 |
Status: | This document is for review and comment by 1EdTech Contributing Members. |
This version: | https://www.imsglobal.org/spec/lti-pm-s/v0p1 |
Latest version: | https://www.imsglobal.org/spec/lti-pm-s/v0p1 |
Errata: | https://www.imsglobal.org/spec/lti-pm-s/v0p1#revision-history |
IPR and Distribution Notice
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .
The following participating organizations have made explicit license commitments to this specification:
Org name | Date election made | Necessary claims | Type |
---|---|---|---|
D2L Corporation | July 21, 2022 | No | RF RAND (Required & Optional Elements) |
Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/speclicense.html.
Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.
The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .
© 2022 1EdTech™ Consortium, Inc. All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
Abstract
This specification defines browser messages between an LTI Tool and an LTI Platform that allow an LTI Tool to store temporary values inside the window frame of an LTI Platform. There are many potential applications for this pattern, the current primary purpose is to enable a workaround for situations where an LTI Tool us unable to set a cookie with an iFrame.
This specification defines a new postMessage type for the LTI Client Side postMessages specification.
1. LTI postMessage Storage
Use a window.postMessage to allow the opener to stand-in as a key-value store. This way the type of data could be stored in the platform’s scope without needing access to the cookie. This could be built as an extension to the lti_messaging semantics already present in several platforms.
This would provide a more general purpose solution to the tool storage problem outside of OIDC. Allowing tool developers to store temporary bits of state in the platform’s storage so it can persist for the duration of the frame request.
1.1 Security
Tools should be cautious to not use this mechanism to store sensitive information that may be valuable outside of the delivery of the tool's activity as values may be exposed to malicious actors for example through Cross-Site scripting vulnerability on either the host learning platform or the tool itself.
1.1.1 Discovering and Validating request and response origins
1.1.1.1 Tools
The tool MUST use the OIDC Authorization URI origin when sending lti.put_data
or lti.get_data
messages.
The tool MUST validate that the response comes from the OIDC Authorization URI origin.
1.1.1.2 Platforms
The platform should accept messages from any origin, but when storing or retrieving a value, the key MUST be scoped to the origin from which the post-message was sent. If there are multiple LTI launches occurring within the same page, it is expected that tools that share the same origin will share the same key store.
2. Message Definitions
2.1 Field Definitions
Field | Usage |
---|---|
subject | The action to be performed. |
message_id | A unique message id for each request, this id will be sent back in the response message. |
key | The data key. |
value | The data value. Can be omitted or empty when clearing a key. |
error | An error message from the platform when a request can not be fulfilled. |
2.2 put_data
2.2.1 Request (Tool)
Message definition for 'put_data'
{
"subject": "lti.put_data",
"message_id": "...",
"key": "...",
"value": "..."
}
2.2.2 Response (Platform)
Message definition for 'put_data.response'
{
"subject": "lti.put_data.response",
"message_id": "...",
"key": "...",
"value": "..."
}
OR
Message definition for 'put_data.response' with error
{
"subject": "lti.put_data.response",
"message_id": "...",
"error": {
"code": "bad_request",
"message": "The put_data request is missing the 'key' field."
}
}
2.3 get_data
2.3.1 Request (Tool)
Message definition for 'get_data'
{
"subject": "lti.get_data",
"message_id": "...",
"key": "..."
}
2.3.2 Response (Platform)
Message definition for 'get_data.response'
{
"subject": "lti.get_data.response",
"message_id": "...",
"key": "...",
"value": "..."
}
2.3.2.1 Error response (Platform)
Message definition for 'get_data.response' with key not found error
{
"subject": "lti.get_data.response",
"message_id": "...",
"error": {
"code": "key_not_found",
"message": "..."
}
}
2.4 Example Usage
The tool pushes a variable into the platforms storage
{
"subject": "lti.put_data",
"message_id": "1",
"key": "keyName",
"value": "keyValue"
}
The platform pushes a response message back to the tool, this is an acknowledgement that the platform both supports and understands the storage request.
{
"subject": "lti.put_data.response",
"message_id": "1",
"key": "keyName",
"value": "keyValue"
}
The tool pushes a recall request to the platform
{
"subject": "lti.get_data",
"message_id": "2",
"key": "keyName"
}
The platform pushes the response for the recall request back into the tool.
{
"subject": "lti.get_data.response",
"message_id": "2",
"key": "keyName",
"value": "keyValue"
}
The tool pushes a clear request to the platform
{
"subject": "lti.put_data",
"message_id": "3",
"key": "keyName"
}
The platform acknowledges the request
{
"subject": "lti.put_data.response",
"message_id": "3",
"key": "keyName"
}
3. Data restrictions and requirements
3.1 Web message origin
The web message MUST specify a targetOrigin.
Details on securing postMessage can be found in the LTI Client Side postMessages Specification [LTI-CS-POSTMSG-10]
3.2 Storage Limits
Practical platform implementations have limits on the number and size of entries that they can store. Platforms MUST provide each of the following minimum capabilities:
- At least 4096 bytes per tool (as measured by the sum of the length of the item's key and value).
- At least 500 keys per tool.
Tools SHOULD use as few and as small key-value pairs as possible to avoid reaching these implementation limits.
3.2.1 Storage Exhaustion Error
If the tool consumes more than an allowable allocation the platform MUST respond to the store request with an error code of 'storage_exhaustion'. It is left to a platform implementation detail of how much storage is allowable since different platforms might be using different storage mechanisms to hold the data.
Message definition for 'put_data.response' with storage exhaustion error
{
"subject": "lti.put_data.response",
"message_id": "...",
"error": {
"code": "storage_exhaustion",
"message": "..."
}
}
4. Implementation Considerations
4.1 Time to Live
It is the expectation of this document that the lifespan of the key-value data only lives as long as the platform dictates. At a minimum the data should exist for the as long as the tool frame/window exists. The platform may choose to extend the life of the data to cover multiple launches.
4.2 Storage Encryption
Depending on the implementation the platform chooses to use, if the platform uses a mechanism like local storage, the platform is encouraged to store the values encrypted at rest within the local storage to protect against XSS attacks against the platform. The encryption can be invisible to the tool and the values should only be decrypted only in flight for delivery to the tools endpoint.
A. Revision History
Document Version No. | Release Date | Comments |
---|---|---|
3 | July 21, 2022 | First release of LTI Platform Storage Base Doc. |
4 | October 17th, 2022 | Completion of initial IP review to make documents publicly available. |
B. References
B.1 Informative references
- [LTI-CS-POSTMSG-10]
- LTI Client Side postMessages. IMS Global Learning Consortium. URL: #nolinkyet
C. List of Contributors
The following individuals contributed to the development of this document:
Name | Organization |
---|---|
Peter Franza | 42 Lines Inc. |
Eric Preston | Blackboard, Inc. |
Claude Vervoort | Cengage |
Martin Lenord | Turnitin |
Maggie Sazio | D2L Corporation |
Viktor Haag | D2L Corporation |
Xander Moffatt | Instructure |
Bracken Mosbacker | 1EdTech |
Joshua McGhee | 1EdTech |
Charles Severance | University of Michigan |
Mary Gwozdz | Unicon, Inc. |
Justin Ball | Atomic Jolt |