canvas-lti v1.2.1

canvas-lti | A Canvas LTI Integration Tool

This module provides an integration tool for Canvas LTI 1.3, facilitating the creation of Learning Tools Interoperability (LTI) applications with Canvas.

Features

• OIDC initiation and LTI launch handling
• Express middleware setup for easy integration to existing express applications
• JWKS endpoint generation for RSA key signing
• Deep Link Handling
• MySQL features for multiple Canvas LTI integrations (or installations).

Requirements

• MySQL Server 8 (this was tested using 8.4).
• Express (you can use https and pass express to it).

Installation

npm install canvas-lti

Example Setup

const express = require('express');
const lti = require('canvas-lti');
const app = express();

const fs = require('fs');
const https = require('https');

// Server-side SSL certificates
const privateKey = fs.readFileSync('server.key', 'utf8');
const certificate = fs.readFileSync('server.cert', 'utf8');

const credentials = { key: privateKey, cert: certificate };

lti.config({
    installations: [
        {
            name: 'Canvas Installation 1',
            oidcInitiationUrl: 'https://canvas.instructure.com/api/lti/authorize_redirect',
            clientId: '000000000000000000',
            baseURL: 'https://localhost:7033/',
            launchPath: 'launch',
            ltiPath: "/lti",
        },
        {
            name: 'Canvas Installation 2',
            oidcInitiationUrl: 'https://canvas2.instructure.com/api/lti/authorize_redirect',
            clientId: '000000000000000000',
            baseURL: 'https://localhost:7033/',
            launchPath: 'launch',
            ltiPath: "/lti2",
        }
    ],
    sqlEnvPaths: {
        user: 'SQL_USERNAME',
        password: 'SQL_PASSWORD',
        host: 'SQL_HOST',
        database: 'SQL_DATABASE',
        port: 'SQL_PORT',
        table: "SQL_TABLE"
    }
});

lti.expressInstance(app);

lti.on('launch', async (req, res) => {
    res.status(200).send('Your LTI tool has been successfuly launched!');
    // Any other logic you want can be added here.
});

lti.on('assignment', async (req, res) => {
    if (req.deepLinkingRequest) {
        let ltiPath = req.installation.ltiPath;
        ltiPath = ltiPath.replace(/^\/|\/$/g, '');
        const items = [
            {
                "type": "ltiResourceLink",
                "title": "A title",
                "text": "This is a link to an activity that will be graded",
                "url": `https://localhost:7033/${ltiPath}/assignment`,
                "icon": {
                    "url": "https://localhost:7033/image.jpg",
                    "width": 100,
                    "height": 100
                },
                "thumbnail": {
                    "url": "https://localhost:7033/thumb.jpg",
                    "width": 90,
                    "height": 90
                }
            },
        ];
        const html = fs.readFileSync('assignment_selection.html','utf8');
        lti.handleResponse(req, res, items, html);
    } else {
        res.status(200).send('Successfully launched your LTI Assignment!');
    }
});


const server = https.createServer(credentials, app);

server.listen(7033, () => {
    console.log('Server running on port 7033');
});

LTI configuration

The following items are required for this module to work correctly:

• oidcInitiationUrl: This is the URL of your canvas installation with /api/lti/authorize_redirect appended ot the end.
• clientId: This is the client ID of the developer key for this integration within Canvas.
• baseURL: The base url of your application.
• launchPath: The launch path of your application. Do not include the LTI path as it will be added before your launch path.
• ltiPath: The path for all LTI related routes within your LTI application. It can contain leading or trailing "/" or no backslashes.

With canvas-lti, there are a few configuration options at your disposal. It is always required to include sqlEnvPaths as a part of the configuration. These destinations correspond to paths within your .env file for secure access to the MySQL database associated with your application.

Sample .env:

SQL_USERNAME=username
SQL_PASSWORD=password
SQL_HOST=host
SQL_PORT=port
SQL_DATABASE=database
SQL_TABLE=settings

The table is required for canvas-lti to properly save and load LTI configurations. Having a distinct table allows you to continue to use your MySQL database(s) without issue. The table will be auto-generated if it does not already exist.

Adding Canvas Installations:

Including Canvas Installations within the configuration is optional as long as there is one or more installations present in the database. All fields within the installation object are required. When first running your application, you can add installations as so:

installations: [
    {
        name: 'Canvas Installation 1',
        oidcInitiationUrl: 'https://canvas.instructure.com/api/lti/authorize_redirect',
        clientId: '000000000000000000',
        baseURL: 'https://localhost:7033/',
        launchPath: 'launch',
        ltiPath: "/lti",
    },
    {
        name: 'Canvas Installation 2',
        oidcInitiationUrl: 'https://canvas2.instructure.com/api/lti/authorize_redirect',
        clientId: '000000000000000000',
        baseURL: 'https://localhost:7033/',
        launchPath: 'launch',
        ltiPath: "/lti2",
    }
],

Please Note: LTI paths cannot be the same but they can have additional paths. If it is essential to have /lti in each installations path, you could use /lti/school1 and /lti/school2.

Editing Canvas Installations

To edit an installation in the database, simply add the configuration to the installations array in the configuration with your updated details like so:

installations: [
    {
        name: 'Canvas Installation 2',
        oidcInitiationUrl: 'https://canvas2.instructure.com/api/lti/authorize_redirect',
        clientId: '000000000000000000',
        baseURL: 'https://localhost:7033/',
        launchPath: 'launch',
        ltiPath: "/university", // Changed the LTI Path from /lti2 to /university
    }
],

⚠️ Installations cannot be updated if you are changing the oidcInitiationUrl.

Deleting Canvas Installations (Advanced)

There is no built-in method to delete installations from the MySQL database. To delete installations at this time, do the following:

1. Log into your MySQL shell mysql -u <user> -p
2. Use your database USE <database>;
3. Delete a row: DELETE FROM <table> WHERE name = "Installation Name". If you have installations with multiple names, this will delete all installations with that name. You can modify this query to delete rows with specific URLs: DELETE FROM <table> WHERE odicInitiationUrl = 'https://canvas.instructure.com/api/lti/authorize_redirect';.

JWK endpoint

This module automatically creates a JWK endpoint based on the ltiPath configuration. If it needs to be accessed, it can be found at <ltiPath>/.well-known/jwks.json. This will be activated for every installation and available on their specific URIs.

Canvas-LTI will generate an RSA key pair and save them as "private.key" and "public.key". The public JWK is then created off of the public key. This ensures that deeplinking requests are properly authenticated and handled by Canvas.

LTI Resource Links

In a familiar feel to Express.JS's route handling, the canvas-lti module handles all LTI requests like so:

lti.on('contentItem', async (req, res) => {
    res.status(200).send('Successfully launched your LTI Content Item!');
});

Deep Linking

This module will automatically check for deep linking requests within the lti.on method. To handle logic for deep linking requests, check to see if there is data attributed to the req.deepLinkingRequest object like so:

lti.on('assignment', async (req, res) => {
    if (req.deepLinkingRequest) {
        // Deep Link Request
    } else {
        // LTI Resource Request
    }
});

The 'assignment' is a path, meaning that for any installation, the app is listening for post requests to your.lti.tool/ltiPath/assignment

Handling a Deep Link Request

To handle a deep linking response, use lti.handleResponse(). This function requires the following parameter in this order:

• req (from the lti.on() method)
• res (from the lti.on() method)
• LTI Items (as defined in the content_claims response example here)

This is an example of handling a deep linking request that sends an LTI Resource Link:

lti.on('assignment', async (req, res) => {
    if (req.deepLinkingRequest) {
        let ltiPath = req.installation.ltiPath;
        ltiPath = ltiPath.replace(/^\/|\/$/g, ''); // Removes "/" from the beginning and end of ltiPath.
        const items = [
            {
                "type": "ltiResourceLink",
                "title": "A title",
                "text": "This is a link to an activity that will be graded",
                "url": `https://localhost:7033/${ltiPath}/assignment`, // Dynamically grabs the LTI Path associated with the Canvas instance requesting it.
                "icon": {
                    "url": "https://localhost:7033/image.jpg",
                    "width": 100,
                    "height": 100
                },
                "thumbnail": {
                    "url": "https://localhost:7033/thumb.jpg",
                    "width": 90,
                    "height": 90
                }
            },
        ];
        const html = fs.readFileSync('assignment_selection.html','utf8');
        lti.handleResponse(req, res, items);
    } else {
        res.status(200).send('Successfully launched your LTI Assignment!'); // A non-deep linking request.
    }
});

Grade Passback

Grade passback is currently not supported but will be in a future update. Stay tuned.

Issues

This module is still a work in progress. More detailed guides and issue reporting is in the works. For immediate issues, please email hep21001@byui.edu.

LTI 1.3 Standard

The IMSGlobal LTI 1.3 Standard contains all of the proper information regarding the LTIs. All immediate LTI questions can be answered there.