Skip to content

Endpoints and Handling Requests

Davo edited this page Dec 15, 2023 · 3 revisions

Open Id Connect Login Request

LTI 1.3 uses a modified version of the OpenId Connect third party initiate login flow. This means that to do an LTI 1.3 launch, you must first receive a login initialization request and return to the platform.

To handle this request, you must first create a new Packback\Lti1p3\LtiOidcLogin object.

Next, get the return url (this must be preconfigured and white-listed on the tool). If a redirect url is not given or the registration does not exist an Packback\Lti1p3\OidcException will be thrown.

Once a valid url is retrieved, we can now redirect the user back to the tool.

$login = LtiOidcLogin::new($database);

try {
    $redirect = $login->getRedirectUrl("https://my.tool/launch");
} catch (Packback\Lti1p3\OidcException $e) {
    // handle the error
}

return redirect($redirect);

The redirect is now done, we can move onto the launch.

LTI Message Launches

Now that we have done the OIDC log the platform will launch back to the tool. To handle this request, first we need to create a new Packback\Lti1p3\LtiMessageLaunch object from the request. This will validate the launch and handle LTI 1.1 migrations if enabled.

$launch = Packback\Lti1p3\LtiMessageLaunch::new($database);
$launch->initialize($request);

Note: The initialize function was introduced in version 5.6. Prior versions should call $launch->validate($request); instead.

Accessing Launch Information

Now we know the launch is valid we can find out more information about the launch.

Check if we have a resource launch or a deep linking launch.

if ($launch->isResourceLaunch()) {
    echo 'Resource Launch!';
} else if ($launch->isDeepLinkLaunch()) {
    echo 'Deep Linking Launch!';
} else {
    echo 'Unknown launch type';
}

Check which services we have access to.

if ($launch->hasAgs()) {
    echo 'Has Assignments and Grades Service';
}
if ($launch->hasNrps()) {
    echo 'Has Names and Roles Service';
}

Accessing Cached Launch Requests

It is likely that you will want to refer back to a launch later during subsequent requests. This is done using the launch id to identify a cached request. The launch id can be found using:

$launch_id = $launch->getLaunchId().

Once you have the launch id, you can link it to your session and pass it along as a query parameter.

Make sure you check the launch id against the user session to prevent someone from making actions on another person's launch.

Retrieving a launch using the launch id can be done using:

$launch = LtiMessageLaunch::fromCache($launch_id, $database);

Once retrieved, you can call any of the methods on the launch object as normal, e.g.

if ($launch->hasAgs()) {
    echo 'Has Assignments and Grades Service';
}

Deep Linking Responses

If you receive a deep linking launch, it is very likely that you are going to want to respond to the deep linking request with resources for the platform.

To create a deep link response you will need to get the deep link for the current launch.

$dl = $launch->getDeepLink();

Now we are going to need to create Packback\Lti1p3\LtiDeepLinkResource to return.

$resource = Packback\Lti1p3\LtiDeepLinkResource::new()
    ->setUrl("https://my.tool/launch")
    ->setCustomParams(['my_param' => $my_param])
    ->setTitle('My Resource');

Everything is set to return the resource to the platform. There are two methods of doing this.

The following method will output the html for an aut-posting form for you.

$dl->outputResponseForm([$resource]);

Alternatively you can just request the signed JWT that will need posting back to the platform by calling.

$dl->getResponseJwt([$resource]);