You've built a training portal. A client says:
"We use Moodle. Can our employees click a link inside a Moodle course and land in your portal — already logged in — without a separate signup?"
That is exactly what LTI 1.3 solves.
How It Works
Step 1 — Student clicks the tool link inside their Moodle course.
Step 2 — Moodle sends a login hint to your server: GET https://yourapi.com/lti/login
Step 3 — Your server redirects back to Moodle's auth endpoint to request a signed token.
Step 4 — Moodle POSTs a signed id_token (JWT) to your server: POST https://yourapi.com/lti
Step 5 — Your server validates the token, finds or creates the user, mints your own app JWT, and redirects to your frontend.
Step 6 — Student lands on your portal — already authenticated, no password entered.
Part 1 — Backend Setup
Install
npm install ltijs ltijs-sequelize
Three URLs to expose
| Moodle calls it |
Your URL |
Purpose |
| Tool URL |
https://yourapi.com/lti |
Receives the signed token |
| Login Initiation URL |
https://yourapi.com/lti/login |
Starts OIDC flow |
| Public Keyset URL |
https://yourapi.com/lti/keys |
Your JWKS public keys |
src/lti/ltijsProvider.js
const lti = require("ltijs").Provider;
const Database = require("ltijs-sequelize");
const ltiLaunchController = require("./lti_launch_controller");
async function setupLTI(app) {
const db = new Database(
process.env.DB_NAME, process.env.DB_USER, process.env.DB_PASSWORD,
{ host: process.env.DB_HOST, dialect: "postgres", logging: false }
);
await lti.setup(
process.env.LTI_ENCRYPTION_KEY,
{ plugin: db },
{
appRoute: "/", // relative to /lti mount → /lti
loginRoute: "/login", // → /lti/login
keysetRoute: "/keys", // → /lti/keys
cookies: {
secure: process.env.NODE_ENV === "production",
sameSite: process.env.NODE_ENV === "production" ? "None" : "Lax",
httpOnly: true,
},
devMode: process.env.NODE_ENV !== "production",
tokenMaxAge: 3600,
}
);
lti.onConnect(async (token, req, res) => {
ltiLaunchController.ltiLaunch(req, res, token);
});
await lti.deploy({ serverless: true });
app.use("/lti", lti.app);
}
module.exports = setupLTI;
src/app.js — mount ltijs FIRST
const setupLTI = require("./lti/ltijsProvider");
(async () => {
await setupLTI(app); // must come before all other routes
app.use(publicRoutes);
app.use(privateRoutes);
app.listen(8000);
})();
Helmet — allow iframe embedding
app.use(helmet({
contentSecurityPolicy: {
directives: {
...helmet.contentSecurityPolicy.getDefaultDirectives(),
"frame-ancestors": ["'self'", "*"], // allow any LMS to embed you
},
},
}));
src/lti/lti_launch_controller.js
const jwt = require("jsonwebtoken");
const User = require("../models/user");
const Client = require("../models/client");
const Role = require("../models/role");
const LtiSession = require("../models/lti_session");
const db = require("../config/database");
const ltiLaunch = async (req, res, token) => {
const frontendUrl = process.env.FRONTEND_URL || "http://localhost:3000";
const transaction = await db.transaction();
try {
// 1. Extract user info from the LTI token
const email = token.userInfo?.email || token.email || "";
const name = token.userInfo?.name || token.name || "LTI User";
const ltiUserId = token.user || token.sub;
const platformId = token.platformId || token.iss;
const ltiClientId = token.clientId || token.aud;
// 2. Match LTI client_id to a client record in your database
// (you store the client_id Moodle gave you when registering the tool)
const client = await Client.findOne({ where: { lti_client_id: ltiClientId } });
if (!client) {
await transaction.rollback();
return res.redirect(`${frontendUrl}/lti-error?errorCode=CLIENT_NOT_FOUND`);
}
// 3. Find existing user by their LTI identity, or auto-create on first launch
let user = await User.findOne({
where: { lti_user_id: ltiUserId, lti_platform_id: platformId },
});
if (!user) {
const role = await Role.findOne({ where: { name: "lti_user" } });
user = await User.create({
name,
email: email || `no-email+${Date.now()}@placeholder.com`,
username: `lti-${email || Date.now()}`,
lti_user_id: ltiUserId,
lti_platform_id: platformId,
role_id: role.id,
active: true,
}, { transaction });
// Link the user to the client they launched from
await user.addClient(client, { transaction });
}
// 4. Record the LTI session (useful for audit and content scoping)
const ltiSession = await LtiSession.create({
user_id: user.id,
platform_id: platformId,
context_id: token["https://purl.imsglobal.org/spec/lti/claim/context"]?.id,
context_title: token["https://purl.imsglobal.org/spec/lti/claim/context"]?.title,
session_started_at: new Date(),
}, { transaction });
await transaction.commit();
// 5. Mint your own app JWT and send the user to the frontend
const appToken = jwt.sign(
{ userId: user.id, lti_session_id: ltiSession.id },
process.env.JWT_SECRET,
{ expiresIn: "1h" }
);
return res.redirect(`\({frontendUrl}?token=\){appToken}`);
} catch (err) {
await transaction.rollback();
console.error("[LTI] Launch error:", err);
return res.redirect(`${frontendUrl}/lti-error?errorCode=INTERNAL`);
}
};
module.exports = { ltiLaunch };
require("dotenv").config();
const lti = require("ltijs").Provider;
const Database = require("ltijs-sequelize");
(async () => {
const db = new Database(
process.env.DB_NAME, process.env.DB_USER, process.env.DB_PASSWORD,
{ host: process.env.DB_HOST, dialect: "postgres", logging: false }
);
await lti.setup(process.env.LTI_ENCRYPTION_KEY, { plugin: db }, {
appRoute: "/lti", loginRoute: "/lti/login", keysetRoute: "/lti/keys",
});
await lti.deploy({ serverless: true });
await lti.registerPlatform({
url: "https://sandbox.moodledemo.net", // issuer — must match exactly, no trailing slash
name: "Moodle Sandbox",
clientId: "PASTE_CLIENT_ID_FROM_MOODLE_HERE",
authenticationEndpoint: "https://sandbox.moodledemo.net/mod/lti/auth.php",
accesstokenEndpoint: "https://sandbox.moodledemo.net/mod/lti/token.php",
authConfig: {
method: "JWK_SET",
key: "https://sandbox.moodledemo.net/mod/lti/certs.php",
},
});
console.log("Platform registered.");
process.exit(0);
})();
Add to package.json:
"register-lti-platform": "node src/lti/registerLTIPlatform.js"
Environment variables
LTI_ENCRYPTION_KEY=any-random-32-char-string
JWT_SECRET=your-existing-jwt-secret
FRONTEND_URL=https://yourportal.com
Part 2 — Moodle Configuration
Go to: Site administration > Plugins > Activity modules > External tool > Manage tools
Then click "configure a tool manually".
| Field |
Value |
| Tool name |
My Training Portal |
| Tool URL |
https://yourapi.com/lti |
| LTI version |
LTI 1.3 |
| Public key type |
Keyset URL |
| Public keyset |
https://yourapi.com/lti/keys |
| Initiate login URL |
https://yourapi.com/lti/login |
| Redirection URI(s) |
https://yourapi.com/lti |
Under Privacy: set both name and email sharing to Always.
Save — Moodle generates a Client ID. Copy it.
Step 2 — Paste Client ID and register
Paste the Client ID from Moodle into registerLTIPlatform.js, then:
npm run register-lti-platform
Step 3 — Add to a course
Course → Turn editing on → Add activity → External Tool → select your tool.
Students clicking it will trigger the full launch.
Part 3 — Token Normalizer
Different LMS platforms (Moodle, Canvas, Blackboard) put claims in slightly different places. Write a normalizer once so your launch controller never needs to care which LMS sent the token:
// src/lti/ltiTokenNormalizer.js
class LTITokenNormalizer {
static normalize(token) {
return {
user: {
id: token.user || token.sub,
name: token.userInfo?.name || token.name || "Unknown",
email: token.userInfo?.email || token.email || "",
},
platform: {
id: token.platformId || token.iss,
clientId: token.clientId || token.aud,
deploymentId: token["https://purl.imsglobal.org/spec/lti/claim/deployment_id"],
},
context: {
id: token["https://purl.imsglobal.org/spec/lti/claim/context"]?.id,
title: token["https://purl.imsglobal.org/spec/lti/claim/context"]?.title,
},
custom: token["https://purl.imsglobal.org/spec/lti/claim/custom"] || {},
};
}
}
module.exports = LTITokenNormalizer;
So you never need to redeploy to connect a new client's LMS:
| Method |
Route |
Action |
| POST |
/admin/lti/platforms |
Register new platform |
| GET |
/admin/lti/platforms |
List all platforms |
| PUT |
/admin/lti/platforms/:id |
Update platform |
| DELETE |
/admin/lti/platforms/:id |
Remove platform |
// POST /admin/lti/platforms
const registerPlatform = async (req, res) => {
const { url, name, clientId, authenticationEndpoint, accesstokenEndpoint, keysetUrl } = req.body;
const platform = await lti.registerPlatform({
url, name, clientId,
authenticationEndpoint,
accesstokenEndpoint,
authConfig: { method: "JWK_SET", key: keysetUrl },
});
return res.json({ success: true, platformId: await platform.platformId() });
};
// GET /admin/lti/platforms
const getAllPlatforms = async (req, res) => {
const platforms = await lti.getAllPlatforms();
const data = await Promise.all(platforms.map(async p => ({
id: await p.platformId(),
url: await p.platformUrl(),
name: await p.platformName(),
clientId: await p.platformClientId(),
})));
return res.json({ success: true, data });
};
Protect these routes with a super-admin guard — only your own team should touch them.
Part 5 — Per-Course Config (Route users to specific content)
Clients want: "When a student launches from the Sales course, open the Sales scenario."
Store a lti_course_configs table:
| column |
meaning |
lti_client_id |
which LMS installation |
deployment_id |
which site instance |
context_id |
which course |
scenario_code |
scenario to open |
group_id |
group to auto-enrol into |
At launch, do a scored lookup — most specific match wins:
const match =
configs.find(c => c.deployment_id === deployId && c.context_id === contextId) ||
configs.find(c => c.deployment_id === deployId && !c.context_id) ||
configs.find(c => c.context_id === contextId && !c.deployment_id);
if (match?.group_id) {
await user.addGroup(match.group_id, { transaction });
}
// store match.scenario_code in the LTI session so the frontend opens it directly
The deployment_id + context_id pair uniquely identifies a course inside a specific Moodle installation. Moodle sends both in every launch token.
Common Gotchas
Cookies blocked
- Use
sameSite: "None" + secure: true in production
- API must be on HTTPS —
sameSite: None requires it
- In dev: use
devMode: true in ltijs (disables the state cookie check)
"Platform not found" error
- The
url you register must match Moodle's iss claim exactly — no trailing slash difference, same protocol
POST /lti never arrives
- Add a log before
app.use("/lti", lti.app) to confirm the POST hits your server
- Usually caused by an iframe blocking the cross-origin form_post redirect from Moodle
No email from Moodle
- Check Moodle tool Privacy settings → Share launcher's email → Always
- If still empty, generate a placeholder:
`no-email+${Date.now()}@placeholder.com`
Pre-Launch Checklist
-
LTI_ENCRYPTION_KEY is 32+ chars and different from JWT_SECRET
- API is on HTTPS
-
cookies.secure = true and sameSite = "None" in production
-
devMode: false in production
- Helmet
frame-ancestors allows the client's Moodle domain
- Platform registered in DB via
npm run register-lti-platform
- Moodle Privacy → Share name + email → Always
- Moodle Redirection URI matches your
/lti URL exactly
-
lti_client_id stored on the client record in your database
