Launch Service - MNV Gateway

The Launch Service is called when a user requests a tool launch from the Gateway. The Launch Service is secured by HTTPBasic Authentication which requires a username and shared secret to be setup with the Gateway prior to performing a Launch.

The Gateway will provide the Tool Provider user id as setup in the Association Workflow which has already commenced prior to the launch. If the user attempts a launch and here is no user Association found the Association flow will be started and the Launch will be paused until association is complete.

SSO LTI Workflow

The process for launch is as follows:

User clicks link in LMS that points to Gateway (see Tool Consumer(LMS) Integration). The link will contain information about the Tool Provider, Launch Adapter (LTI 1.1, etc) and context about what they're attempting to launch (course, assignment, etc) in the query string parameters.
Gateway receives request and parses URL, looks up the Tool Provider username and shared secret and creates a Launch.

Gateway POSTs a Launch to the Tool Provider's registered Launch service. (see Tool Provider Endpoints)

See SignOn Request

REQUEST:
 - POST /v1/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"
    }

The Tool Provider must then decide where to send the user. This is called the SignOn Response. For instance the user may need to register, pay for the course or it could be a valid launch. Regardless, it is up to the Tool Provider to decide where the user needs to be sent to and provide the appropriate response with an "action", "redirectURI" and an optional "messageData".

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

Gateway redirects user by POSTing a form to the "redirectURI" above. This form also contains an access_token which MUST be used to validate the authenticity of the request. Optionally this request may also contain a "grade_return_token" which can later be used to perform an LTI Grade Return.

REQUEST:
    <form action="http://tool-provider.com/doLaunch?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>

The Tool Provider validates the authenticity of the access_token with the Gateway by calling the /v1/verify_token endpoint with the access_token as a parameter:
```
REQUEST:
 - GET /v1/verify_token?access_token=335aea8b68e0da0e29259ee6631c3e2ce81a2a5a
```

It is important to note that this is SOLELY the responsibility of the Tool Provider as the Gateway has no way to stop a launch with a token that has not been validated as the user's request is being served by the Tool Provider's server.

The Gateway will respond back letting the Tool Provider know if there was an error. If "error" is non-zero the Tool Provider should not proceed with the launch!
```
RESPONSE:
{
    "error": 0,
    "data": null,
    "message": "Successfully verified access token",
    "status": 200
}
```

Once the Tool Provider has validated the authenticity of the Launch the Tool Provider may proceed to launch the application.