Tool Provider Endpoints

As a Tool Provider you will be required to implement the following endpoints to take advantage of the services the Gateway provides. The route of each endpoint is determined by the Tool Provider, therefore the examples below are only for illustration. The methods are valid. The routes must be registered with the Gateway during the Out of Band Registration process.

Values prefixed with "tc_" come directly from the Tool Consumer (most likely an LMS) and you should avoid using them if at all possible to avoid LMS specific integration.

Below is a breakdown of the routes required per Gateway service.

Single Sign On (SSO)

Associate User

The user will be redirected to this endpoint when the Gateway detects that the user is unknown to the Gateway. The Gateway will submit a form via POST which contains the assoc_token, tc_user_id and tc_role. All of the query string parameters from the initial request will also be appended for use.

REQUEST:
 - POST /associate_user
 - BODY:
    <form action="http://tool-provider.com/associate_user?courseId=123&instructor=555" method="post" enctype="application/x-www-form-urlencoded" >
        <input type="hidden" name="assoc_token" value="Association53f797b7cac745.32424769" />
        <input type="hidden" name="tp_user_id" value=""/>
        <input type="hidden" name="tc_user_id" value="ea918c08a3874091a2644e72109ea898"/>
        <input type="hidden" name="tc_role" value="urn:lti:role:ims/lis/Learner"/>
        <input type="hidden" name="tc_first_name" value="Joe"/>
        <input type="hidden" name="tc_last_name" value="Smith"/>
        <input type="hidden" name="tc_email" value="joe.smith@university.edu"/>
    </form>

RESPONSE:
// as this is a redirect, there is no response to be sent to the Gateway.

See the Association Service for more information about the User Association flow.

Launch

This endpoint is used by the Gateway to get the redirect URL back from the Tool Provider. The Gateway will POST to this endpoint using HTTPBasic Authentication. It is up to the Tool Provider to determine where the user should be directed too and return a response to the Gateway. For instance if the user's subscription is expired the Tool Provider Could send the user to a Pay page. Or if the user is valid and up do date the Tool Provider should redirect to the requested activity. The important thing to note is that the Tool Provider is responsible for where the user should be sent and to provide an appropriate response with an "action", "redirectURI" and an optional "messageData".

See SignOn Response for more detail.

The URL parameters will be specified in the LMS and will be propagated through from the Gateway. Any URL parameters are "owned" by the Tool Provider. In the following example ?courseId=123&authType=basic are the parameters entered on the LMS side and propagated through the Gateway.

REQUEST:
 - POST /launch?courseId=123&instructor=555
 - HEADER:
        Content-Type: application/json
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=
 - BODY:
    {
        "tp_user_id": "5",
        "tc_user_id": "ea918c08a3874091a2644e72109ea898",
        "tc_role": "urn:lti:role:ims/lis/Learner",
        "tc_first_name": "Joe",
        "tc_last_name": "Smith",
        "tc_email": "joe.smith@university.edu"
    }

RESPONSE:
- BODY:
    {
        "action" = "LAUNCH",
        "redirectURI" = "http://tool-provider.com/launchCourse?tpSpecificParameter=SomeVal"
        "messageData" = "Some Data Needed By The Tool Provider"
    }

Authentication

This endpoint is used by the Gateway to call into the Tool Provider in order to authenticate a user. The Gateway will POST to this endpoint using HTTPBasic Authentication, including username and password information for authenticating with the Tool Provider. The Tool Provider will return a JSON object indicating success or failure, as well as the Tool Provider user ID value.

REQUEST:
 - POST /authenticate
 - HEADER:
        Content-Type: application/json
        Authorization: Basic WW91SGF2ZVRvb011Y2hGcmVlVGltZTpTdG9wUmV2ZXJzZUVuZ2luZWVyaW5nT3VyRG9jdW1lbnRhdGlvbiA6LSk=
- BODY:
    {
        "username": "IAmUser",
        "password": "53cr3t5tuff",
    }

RESPONSE:
 - HEADER:
        Content-Type: application/json
 - BODY:
    {
        "success": "true",
        "tool_provider_user_id": "BlauBlauBlau"
    }

Launch Redirect

"LaunchRedirect" is not an endpoint that is registered with the Gateway, rather is is the "redirectURI" from the Launch above. This is here to outline how the Gateway will call the redirectURI as part of the Launch. It should be noted that the "doLaunch" URL that is specified below will be returned as part of the Launch and is 100% controlled by the Tool Provider; such that a different redirectURI could be passed for every request if needed.

The Tool Provider must use the access_token to verify that the launch is valid and not coming from outside of the Gateway.

REQUEST:
 - POST /LaunchRedirect
 - BODY:
    <form action="http://tool-provider.com/LaunchRedirect?tpSpecificParameter=SomeVal" method="post" enctype="application/x-www-form-urlencoded" >
        <input type="hidden" name="access_token" value="335aea8b68e0da0e29259ee6631c3e2ce81a2a5a" />
        <input type="hidden" name="message_data" value="Some Data Needed By The Tool Provider"/>
        <input type="hidden" name="tp_user_id" value="5"/>
        <input type="hidden" name="tc_user_id" value="ea918c08a3874091a2644e72109ea898"/>
        <input type="hidden" name="tc_role" value="urn:lti:role:ims/lis/Learner"/>
        <input type="hidden" name="tc_first_name" value="Joe"/>
        <input type="hidden" name="tc_last_name" value="Smith"/>
        <input type="hidden" name="tc_email" value="joe.smith@university.edu"/>
    </form>

RESPONSE:
// as this is a redirect, there is no response to be sent to the Gateway.