API Reference

LTI Launch

This page contains details about LTI Launch request.

Whilst LTI® is not primarily designed as a SSO mechanism, some of the data it passes in a launch request are about the user. Moreover, LTI works on the basis of a trust relationship between the systems which is established by means of a key and a secret - much simpler than providing access to a common identity server. In LTI a user is authenticated by a primary system (such as an LMS) and then can be passed to another system (internal or external) by way of a signed launch message. The system receiving this message can verify its authenticity by inspecting the signature and then implicitly trust the data it carries; there is no need for the user to be authenticated a second time or for their identity to be checked against another system. This approach can make LTI a low cost alternative to implementing SSO between systems.

(Source: Learning Tools Interoperability® as a SSO Mechanism)

This section describes the data items that are passed as part of the POST data when a Basic LTI launch is performed. Very few of the fields are technically required however Gooru LTI needs some fields to be present in the request. Some fields in the launch request will be gathered for tracking and others may need highly detailed and precise information to perform high-stakes activities and reliably and securely return high-stakes results from those activities.

Consumer systems should provide as much data as possible in each launch to maximize the chance that the Gooru LTI will have the data it needs to function properly. Consumer systems may have sandboxing features that limit the sending of certain Basic LTI data elements. Gooru LTI is prepared to work with partial information – either because the consumer does not have the information or the consumer has been configured not to share the information with Gooru.

📘

Endpoints

Production : http://ltisso.gooru.org/api/nucleus-lti/v1/launch
QA: https://nucleus-qa.gooru.org/api/nucleus-lti/v1/launch

🚧

Consumer Key / Shared Secret

You need a consumer_key and shared_secret to be able to launch LTI request. Normally, this keys will be the same client_id and client_key provided by Gooru. You can contact [email protected] to obtain one.

Launch Parameters

lti_message_type=basic-lti-launch-request

[Required]
This indicates that this is a Basic LTI Launch Message. This allows a Gooru to accept a number of different LTI message types at the same launch URL.

lti_version=LTI-1p0

[Required]
This indicates which version of the specification is being used for this particular message.

oauth_consumer_key=b289378-f88d-2929-lmsng.school.edu

oauth_signature_method=HMAC-SHA1

oauth_timestamp=1244834250

oauth_nonce=1244834250435893000

oauth_version=1.0

oauth_signature=Xddn2A%2BjzwjgBIVYkvigaKxCdcc%3D

OAuth is a security mechanism designed to protect POST and GET requests. This parameters only applies to protecting launch and other LTI messages that are being serialized and sent using POST. All parameters are required.

resource_link_id=class:<class_id>,unit:<unit_id>,assessment:<assessment_id>

[Required]
This will be used to pass the class/content details from the consumer to Gooru LTI.

Redirect base URLs will be manually configured in Gooru LTI DB based on the role of the user. Consumer need to provide the URL to which Gooru LTI will redirect from Launch request. Redirect URL should accept the content ids (e.g. class id, assessment id etc.) so that they can passed to player. This URL may contain placeholders for various ids what we need to pass to the player.
E.g. https://nucleus-qa.gooru.org/player/$$assessment
Where, $$assessment is placeholder which will be replaced by actual assessment id received.

Gooru LTI will append ‘access_token’ to this URL which can be use to bring up the assessment/collection player for logged in user session.

launch_presentation_return_url=http://nucleus-qa.gooru.org/

[Optional]
This URL is used in case of any issue in launch request.

lis_person_name_given=Jane

lis_person_name_family=Public

lis_person_contact_email_primary=[email protected]

[Optional]

These fields contain information about the user account that is performing this launch. The names of these data items are taken from LIS.

roles=Instructor

[Optional]

A comma-separated list of URN values for roles. If this list is non-empty, it should contain at least one role

user_id=0ae836b9-7fc9-4060-006f-27b2066ac545

[Required]

Uniquely identifies the user. This should not contain any identifying information for the user. Best practice is that this field should be a TC-generated long-term “primary key” to the user record – not the “logical key"

lis_result_sourcedid=83873872987329873264783687634

[Optional]

This field contains an identifier that indicates the LIS Result Identifier (if any) associated with this launch. This field should be present in order to receive the score back to the consumer via Outcomes.

tool_consumer_instance_guid=lmsng.school.edu

[Optional]

This is a unique identifier for the TC. A common practice is to use the DNS of the organization or the DNS of the TC instance. If the organization has multiple TC instances, then the best practice is to prefix the domain name with a locally unique identifier for the TC instance.

tool_consumer_instance_name=SchoolU

[Optional]

This is a user visible field – it should be about the length of a column.

Launch Responses

This section captures the details on various responses that LTI launch request can send.

👍

ON Success

On successful launch request processing, API will return HTTP Response 303 - See Other with proper redirect URL in Location header
Redirect URL will be formed based on the launch_presentation_return_url present in the request by replacing proper parameters in the URL. Gooru LTI will also append access_token URL parameter to the return URL which denotes the logged in user.

❗️

ON Failure

In case of failure to process the launch request, API will return HTTP Response Code 303 - See Other with proper redirect URL in Location header.
Redirect URL will be formed by adding a parameter called lti_errormsg that includes some detail as to the nature of the error. The lti_errormsg value should make sense if displayed to the user. If the tool has displayed a message to the end user and only wants to give the consumer a message to log, use the parameter lti_errorlog instead of lti_errormsg.