Introduction

This page is only for testing purposes. Never use this page for accessing Emended except when testing the integration. Never use a non-production instance of Emended for doing your work, or you will lose your materials.

This is a static page explaining the purpose of the various parameters used when performing a LTI launch request from your product to Emended. It also helps you validate your implementation by showing how a valid signature is calculated.

Please note that this page is provided as a static file only for demonstration purposes. Your implementation must always calculate the signature server-side, in order to protect your consumer secret.

The basics

The basics of the LTI integration are as follows:

Make sure of the following:

General parameters

The launch URL is the endpoint receiving the LTI launch request from your product.

For the production environment, this is always https://app.emended.com/lti/launch. You may use other values for testing.

The consumer secret is used for signing and therefore securing your request. The secret must always be handled securely by your server and must never be passed to clients.

You receive the secret either by logging in to your team in Emended or directly from Emended staff.

Launch parameters

All of the following values are mandatory and are passed as launch parameters to Emended.

Your product's unique identifier in Emended.

You receive the key either by logging in to your team in Emended or directly from Emended staff.

A unique identifier for the link that the user follows to Emended. This can be anything.

Must have the value displayed above.

Must have the value displayed above.

Unique identifier for the user in your system. Must remain constant for the same user whenever they access Emended from the same system.

A comma-separated list of user roles. If the user is a teacher and should receive instructor access in your team in Emended, you must include "Instructor". Other roles are ignored.

Unique token for the request. Must never be repeated for two separate requests, but otherwise it can be anything.

UTC timestamp in seconds. Must be fairly recent.

Must have the value displayed above.

Must have the value displayed above.

Must have the value displayed above.

Signature determined based on all of the launch parameters as well as the launch URL and secret. See below for more details.

Optional launch parameters

All of the following are purely optional, and not all of them are currently used by Emended. These parameters may be used to improve the usability of Emended when accessed through your product, but Emended will always continue to function if any of these are missing.

The descriptions below are only for reference; not all of the suggested functionalities are supported.

Can be suggested as the first name for the user when registering.

Can be suggested as the last name for the user when registering.

Can be used when addressing the user during registration.

Can be suggested as the email address for the user when registering.

Can be used to determine whether the page can be closed or returned to the source tool. One of frame, iframe or window.

Can be used to redirect the user back to your product.

Can be used to select a default language when the user arrives to Emended.

Can be suggested as a contact address if the user needs help, for example if there is a problem with the integration.

May be shown to the user to clarify which product they are coming from.

May be displayed to the user to clarify which product and link they are coming from.

Signature

In addition to the launch parameters, you must determine the signature which is used to secure the launch request. The steps to produce the signature are listed below.

First, generate the dynamic parameters: the timestamp and nonce. The timestamp is the number of seconds since the Unix epoch at the time of the request, while the nonce can be anything, as long as it's unique between requests.

Timestamp: 
Nonce:

Next, determine the launch parameters. This includes all of the values listed above, as well as the timestamp and nonce. Optional values that you do not provide can be omitted.

Next, the signature needs to be calculated. Start by forming a string of the launch parameters in pairs of key=value, separated by &. The parameters must be sorted alphabetically, first by key and then by value. All of the values must be URL-encoded.

This string then needs to be URL-encoded.

Next, you append the method type POST, the launch URL (with URL-encoding) and the parameter string, in this order and separated by &, in order to get the signature base string.

You then determine the signing key, which is simply the consumer secret URL-encoded and followed by &.

Finally, pass the signature base string and the signing key to the HMAC-SHA1 algorithm, and output it as a base64 encoded string. This is the OAuth signature.

Add the signature along the other launch parameters and perform a POST request to the launch URL in order to access Emended.