The Launch

One capability that LTI enables is SSO (Single Sign-on). This means that users who are signed into the consumer, can follow a link to the provider, and be authenticated automatically, without having to provide an additional set of credentials.

This is accomplished via the LTI Launch, in which the consumer builds a request containing the user's information (name, role, etc), and gives it to the user. The user then sends the request to the provider, where the provider reads the name and role and provides an interface for for it's capabilities.

Signing

Since the launch request comes from the user's client, the provider cannot trust that the information in the request is valid by itself. For example: When the consumer builds a request and sends it to a student. The student can change their role to "instructor," which could cause the the tool the give that student elevated rights.

Consumers can sign a list of parameters using an instance of LtiOauthSigner:

import net.paulgray.lti.launch.LtiSigner

// ...

LtiSigner signer = new LtiOauthSigner();
Map<String, String> parameters = new HashMap<>();
...

Map<String, String> signedParameters = signer.sign(parameters.entrySet(), key, secret, url, "POST");

These parameters can be returned to the client and inserted into an auto-submittted form. Here's an example using JSP:

<form action="${launchUrl}" method="POST">
  <c:forEach items="${parameters}" var="param">
    <input type="hidden" name="${param.key}" value="${param.value}" />
  </c:forEach>
  <input type="submit">Launch Tool</input>
</form>

Signature Verification

In order for the provider to verify that the user's request contains valid information, and that it wasn't changed by the user, the provider and consumer must agree on a key and secret beforehand that the consumer will sign launch requests with. When the consumer builds the request, they take the secret that is only known by it and the provider and uses it to compute a signature for the information in the request. The compiled request now contains the user's information and the signature based on that information.

When the user sends the request to the provider, the provider takes the information in the request, and the secret that it arranged before hand with the consumer, and applies the same process to compute the signatures. If the signature computed by the provider matches the one included in the request, then the provider can trust that they information came from the consumer. If the user had tampered with the information in the request, then the signature computed by the provider would not match the one in the request, and the provider would know not to trust it. The user also cannot recompute a new signature for their modified information because they don't know the secret.

As a provider, I can verify a set of parameters using an instance of LtiOauthVerifier:

LtiVerifier verifier = new LtiOauthVerifier();
Map<String, String> parameters = request.getParameters();

// retrieve the stored secret for the key in the request:
String key = parameters.get("oauth_consumer_key");
String secret = keyService.fetchSecretForKey(key);

LtiVerificationRequest = verifier.verifyParameters(parameters.entrySet(), url, "POST", secret);

Launch Parameters

The LTI launch includes information about the user and the context of where the user came from (i.e. did the user click on the link from within a course? or from within their profile page, etc). This allows the tool to provide functionality pertaining to that information. For example, a tool could provide a chat system for every course, matching users that come from the same course together.

The full list of LTI parameters in the standard is (note: some consumers may provide additional parameters based on custom functionality):

Extracting/Validating Information from a launch

Often it's useful to extract values from an LTI message into a more meaningful representation.

You can use LtiMessageExtractorImpl to make this easier:

HttpServlet request = ...;
LtiMessageExtractorImpl extractor = new LtiMessageExtractorImpl();

LtiErrorable<LtiMessage> message = extractor.extractLtiMessage(request.getParameters());

message.collapse(
  message -> {
    //success
    BasicLtiLaunchRequestMessage launch = (BasicLtiLaunchRequestMessage) message;
    User user = launch.user();

    return "ltiSuccess.jsp";
  },
  errors -> {
    // error
    return "ltiError.jsp";
  }
);