1.1 Problem Description: Blocked cookies prevent proper OIDC flow

The OIDC specification, which LTI is built on, relies on browser cookies to validate the user agent starting the authorization workflow is the same one that finishes it. However, since an LTI integration is most often inside an iFrame there can be many issues involved with setting a state cookie for this purpose. This implementation guide explains how to use LTI Client Side postMessages with LTI postMessage Storage to replace the function of cookies in validating the state between stages of an OIDC launch.

1.2 Problem Solution: Store OIDC state & nonce using browser messages

1.3 Diagrams: Cookies vs JS State

TODO: Current sequence diagram (re-use or update the existing ones for consistency) vs Update simple version sequence diagram

1.4 Sequence Diagram

2.1 Platform: Send an OIDC Initiation signal

When the platform initiates an LTI launch and supports this launch flow it will add a query parameter to the OIDC Initiation Request URL called lti_storage_target.

To specify the parent frame rather than a subframe within the parent use _parent.

Will specify that put and get capabilities are available and the target frame is the frame specified by the query parameter

2.2 Tool: Determine whether you can use cookies

How to determine whether you can use cookies:

• Did the browser send you previously set cookies?
  • You can just proceed with the normal OIDC Auth Request redirect via a 301 response
• No cookies sent from browser:
  • Render and HTML page with embedded Javascript to determine next steps
    • Provide the state & nonce values so your Javascript have access
  • (Optional) Can send ajax request to check again if cookies were now set with the response for the HTML page
    • If cookie was set can just redirect with normal OIDC Auth Request

The rendered HTML page should then execute Javascript to listen for a postMessage response and send the state & nonce to the platform.

2.3 Tool: Send message to store state & nonce

The tool should send a JavaScript postMessage to the target frame identified by the lti_storage_target. This message should include lti.put_data as the subject, as well as values for the message_id, key, and value being stored.

The state and nonce values that would have been placed inside cookies will now be stored in the platform window via LTI postMessage Storage.

See the example code both in the LTI Client Side postMessages document and below in the JS Example: Sending a put_data message to platform.

let platformOrigin = new URL('https://platform.example.com/auth_url').origin;

2.4 Platform: Store data and respond

The platform's browser frame that is hosting the tool's iFrame, or the frame listening for these events, must remain consistent throughout this described flow so that when the tool stores a value during the OIDC Initiation step it is still available after the OIDC Auth Response step.

This code example shows how a platform can listen and respond to put_data and get_data messages: JS Example: Listen for events and store data.

The primary considerations for a platform at this point are that the data is stored in a bucket that is specific to the origin of the tool and to respond immediately since a user is waiting for these actions to complete.

2.5 Tool: Wait for response and continue with OIDC flow

The tool will add an event listener to catch the responding message from the platform. The tool should set up an event listener before the put_data message is sent so that the response is not missed. There is an example below in JS example: Listen for put_data response

The necessary validation steps are:

• Check that this is message we're expecting:
  • It should have a data element that is an object
  • The data.subject should be lti.put_data.response. Response subjects are always the original subject with .response appended to it.
• Validate that the message ID in the response data matches the message ID you sent
• Validate that the origin of the response matches the OIDC Authorization URI's origin

2.6 Platform: Continue with OIDC Auth Response back to tool

The platform doesn't have to do anything different for this step of their OIDC login process other than to make sure the outer frame doesn't reload so that the javascript state is preserved between OIDC stages for the tool in the iFrame.

2.7 Tool: Verify state & nonce match

The OIDC verification step is to receive the state cookie from the browser and compare that to the state in the id_token. Since this flow is for when there is now cookie available, you will have to again render an HTML page with javascript that will execute on load to fetch the state & nonce from the platform's browser frame, then compare it to the id_token values via a validation ajax call or redirect.

3.1 JS Example: Sending a put_data message to platform

The tool will send a put_data message like this:

let platformOrigin = new URL(platformOIDCLoginURL).origin;
let frameName = getQueryParam("lti_storage_target");
let parent = window.parent || window.opener;
let targetFrame = frameName === "_parent" ? parent : parent.frames[frameName];

targetFrame.postMessage({
        "subject": "lti.put_data",
        "message_id": messageId,
        "key": "state_<state_id>",
        "value": "<state_id>"
      } , platformOrigin )


targetFrame.postMessage({
        "subject": "lti.put_data",
        "message_id": messageId,
        "key": "nonce_<nonce_value>",
        "value": "<nonce_value>"
      } , platformOrigin )

3.2 JS example: Listen for put_data.response

window.addEventListener('message', function (event) {
    // This isn't a message we're expecting
    if (typeof event.data !== "object"){
        return;
    }

    // Validate it's the response type you expect
    if (event.data.subject !== "lti.put_data.response") {
        return;
    }

    // Validate the message id matches the id you sent
    if (event.data.message_id !== messageId) {
        // this is not the response you're looking for
        return;
    }

    // Validate that the event's origin is the same as the derived platform origin
    if (event.origin !== platformOrigin) {
        return;
    }

    // handle errors
    if (event.data.error){
        // handle errors
        console.log(event.data.error.code)
        console.log(event.data.error.message)
        return;
    }

    // It's the response we expected
    // The state and nonce values were successfully stored, redirect to Platform
    redirect_to_platform(platformOIDCLoginURL);
});

3.3 JS Example: Sending get_data message to platform

The tool will send a get_data message like this:

let platformOrigin = new URL(platformOIDCLoginURL).origin;
let frameName = getQueryParam("lti_storage_target");
let parent = window.parent || window.opener;
let targetFrame = frameName === "_parent" ? parent : parent.frames[frameName];

targetFrame.postMessage({
        "subject": "lti.get_data",
        "message_id": messageId,
        "key": "state_<state_id>",
      } , platformOrigin )


targetFrame.postMessage({
        "subject": "lti.get_data",
        "message_id": messageId,
        "key": "nonce_<nonce_value>",
      } , platformOrigin )

3.4 JS example: Listen for get_data response

window.addEventListener('message', function (event) {
    // This isn't a message we're expecting
    if (typeof event.data !== "object"){
        return;
    }

    // Validate it's the response type you expect
    if (event.data.subject !== "lti.get_data.response") {
        return;
    }

    // Validate the message id matches the id you sent
    if (event.data.message_id !== messageId) {
        // this is not the response you're looking for
        return;
    }

    // Validate that the event's origin is the same as the derived platform origin
    if (event.origin !== platformOrigin) {
        return;
    }

    // handle errors
    if (event.data.error){
        // handle errors
        console.log(event.data.error.code)
        console.log(event.data.error.message)
        return;
    }

    // It's the response we expected
    // The state and nonce values were successfully fetched, validate them
    ajax_with_values_or_redirect_again()
});

3.5 Maintaining state beyond OIDC flow

other uses and considerations

4.1 JS Example: Listen for events and store data

TODO: Working on platform get/put example code:

(function(){

    /**
     * Stored data should be scoped by the origin of the event, preventing access
     * to other origins that may also be embedded in the page
     * Each origin has its own object for the key/value store
     * {
     *     "<event.origin>": {<keys>: <values>}
     * }
     *
     * To avoid accidental data leakage the storage data variable should be scoped
     * so that it is only accessible by the event listener code
     */
    let storageData = {};

    // Declare an event listener for messages to put and get data
    window.addEventListener('message', function (event) {
        // This isn't a message we're expecting
        if (typeof event.data !== "object") {
            return;
        }

        // Check the subject value to determine which call is being made
        switch (event.data.subject) {
            case 'lti.put_data':
                // Do we already have a map for this origin, if not create one
                if (!storageData[event.origin]) {
                    storageData[event.origin] = {};
                }

                // Store the value against the key scoped by origin
                storageData[event.origin][event.data.key] = event.data.value;

                // Respond immediately to the tool event's origin and source with a `put_data` response
                event.source.postMessage({
                    subject: 'lti.put_data.response',
                    message_id: event.data.message_id,
                    key: event.data.key,
                    value: event.data.value
                }, event.origin);
                break;
            case 'lti.get_data':

                // Check whether we have the data
                if (!storageData[event.origin] || !storageData[event.origin][event.data.key]) {
                    // We don't have data for this origin, or this specific key, return error response
                    event.source.postMessage({
                        subject: 'lti.get_data.response',
                        message_id: event.data.message_id,
                        error: {
                            code: 'key_not_found',
                            message: 'There is no value stored for this key'
                        }
                    }, event.origin);
                    break;
                }

                // Respond immediately to the tool event's origin and source with a `get_data` response
                // including the stored value
                event.source.postMessage({
                    subject: 'lti.get_data.response',
                    message_id: event.data.message_id,
                    key: event.data.key,
                    value: storageData[event.origin][event.data.key]
                }, event.origin);

                break;

            default:
                // Ignore subjects we don't know how to handle
        }
    }, false);
})(); // self-executing function