Chapitre 10.5 — Construire un outil LTI 1.3 complet en Next.js

                    ┌───────────────────────────────────┐
                    │   Moodle 5.2 (plateforme)          │
                    │   https://moodle.example.com       │
                    │                                    │
                    │  /mod/lti/auth.php    auth OIDC    │
                    │  /mod/lti/token.php   access token │
                    │  /mod/lti/certs.php   JWKS Moodle  │
                    └────────┬─────────────────▲─────────┘
              lancements     │                 │  appels de service
              (navigateur)   ▼                 │  (serveur → serveur)
┌───────────────────────────────────────────────────────────────────┐
│  QuizLab — https://tool.example.com  (Next.js 15, App Router)      │
│                                                                    │
│  ROUTES API (le protocole)                                         │
│  app/api/lti/login/route.ts      initiation OIDC (GET + POST)      │
│  app/api/lti/launch/route.ts     réception id_token (POST)         │
│  app/api/lti/jwks/route.ts       clé publique de l'outil (GET)     │
│  app/api/lti/deep-link/route.ts  réponse Deep Linking (POST)       │
│  app/api/quiz/submit/route.ts    poste un score via AGS (POST)     │
│                                                                    │
│  PAGES (le produit)                                                │
│  app/lti/app/page.tsx            le quiz (contenu principal)       │
│  app/lti/deep-link/page.tsx      sélection de contenu (enseignant) │
│  app/lti/roster/page.tsx         participants du cours (NRPS)      │
│  app/lti/launch/page.tsx         secours si cookies bloqués        │
│                                                                    │
│  MODULES PARTAGÉS                                                  │
│  lib/lti/config.ts               config de l'outil (env, clés)     │
│  lib/lti/registry.ts             registre des plateformes          │
│  lib/lti/keys.ts                 clé privée RSA (importPKCS8)      │
│  lib/lti/types.ts                claims LTI typés                  │
│  lib/lti/session.ts              state + session (JWT HS256)       │
│  lib/lti/nonce.ts                anti-rejeu des nonces             │
│  lib/lti/roles.ts                helpers de rôles LIS              │
│  lib/lti/ags.ts                  Assignment and Grade Services     │
│  lib/lti/nrps.ts                 Names and Role Provisioning       │
│  lib/quizzes.ts                  contenu factice                   │
│  scripts/generate-keys.ts        génération de la paire RSA        │
└───────────────────────────────────────────────────────────────────┘

npx create-next-app@latest quizlab
# Réponses aux questions :
#   TypeScript ................. Yes
#   ESLint ..................... Yes
#   Tailwind CSS ............... No   (hors sujet ici)
#   src/ directory ............. No
#   App Router ................. Yes
#   Import alias (@/*) ......... Yes
 
cd quizlab
npm install jose
npm install --save-dev tsx

# Option A : ngrok (domaine stable gratuit après création de compte)
ngrok http 3000
# → https://quizlab.eu.ngrok.io  (exemple)
 
# Option B : cloudflared
cloudflared tunnel --url http://localhost:3000
# → https://xxxx-yyyy.trycloudflare.com  (URL aléatoire à chaque lancement)

# .env.local
 
# --- L'outil lui-même ---------------------------------------------
# URL publique de l'outil (le tunnel en dev, le domaine réel en prod)
TOOL_BASE_URL=https://tool.example.com
 
# Secret HMAC pour signer les cookies (state + session).
# Générez-le : openssl rand -base64 48
SESSION_SECRET=remplacez-moi-par-48-octets-aleatoires-en-base64
 
# Paire de clés RSA de l'outil (générée par scripts/generate-keys.ts)
TOOL_PRIVATE_KEY_PATH=./keys/private.pem
TOOL_PUBLIC_JWK_PATH=./keys/public.jwk.json
# En prod, préférez injecter directement le contenu :
# TOOL_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
# TOOL_PUBLIC_JWK={"kty":"RSA","n":"...","e":"AQAB","kid":"...","alg":"RS256","use":"sig"}
 
# --- La plateforme Moodle -----------------------------------------
# L'issuer est l'URL racine du site Moodle, SANS slash final
LTI_ISSUER=https://moodle.example.com
# Fournis par Moodle après enregistrement de l'outil (section 8)
LTI_CLIENT_ID=a1b2c3d4e5f6g7h
LTI_DEPLOYMENT_ID=1
# Endpoints Moodle (fixes, relatifs à l'issuer)
LTI_AUTH_URL=https://moodle.example.com/mod/lti/auth.php
LTI_TOKEN_URL=https://moodle.example.com/mod/lti/token.php
LTI_JWKS_URL=https://moodle.example.com/mod/lti/certs.php

// scripts/generate-keys.ts
//
// Génère la paire de clés RSA de l'outil :
//   keys/private.pem       — clé privée PKCS#8 (à protéger !)
//   keys/public.jwk.json   — clé publique au format JWK, avec kid/alg/use
//
// Usage : npx tsx scripts/generate-keys.ts
 
import { generateKeyPair, exportJWK, exportPKCS8, calculateJwkThumbprint } from "jose";
import { mkdirSync, writeFileSync, existsSync } from "node:fs";
import path from "node:path";
 
async function main(): Promise<void> {
  const keysDir = path.resolve(process.cwd(), "keys");
  const privatePath = path.join(keysDir, "private.pem");
  const publicPath = path.join(keysDir, "public.jwk.json");
 
  if (existsSync(privatePath)) {
    console.error(`Refus d'écraser ${privatePath} — supprimez-le d'abord si c'est voulu.`);
    process.exit(1);
  }
 
  // extractable: true est indispensable : sans lui, exportPKCS8/exportJWK
  // refuseront d'exporter la clé générée par WebCrypto.
  const { publicKey, privateKey } = await generateKeyPair("RS256", {
    modulusLength: 2048,
    extractable: true,
  });
 
  // Clé publique → JWK
  const jwk = await exportJWK(publicKey);
 
  // kid STABLE et déterministe : l'empreinte RFC 7638 du JWK.
  // Régénérer le kid à chaque démarrage casserait la vérification côté
  // Moodle entre deux déploiements — c'est un anti-pattern classique.
  const kid = await calculateJwkThumbprint(jwk); // SHA-256, base64url
  jwk.kid = kid;
  jwk.alg = "RS256";
  jwk.use = "sig";
 
  // Clé privée → PEM PKCS#8
  const privatePem = await exportPKCS8(privateKey);
 
  mkdirSync(keysDir, { recursive: true });
  writeFileSync(privatePath, privatePem, { mode: 0o600 });
  writeFileSync(publicPath, JSON.stringify(jwk, null, 2) + "\n");
 
  console.log("Clés générées :");
  console.log(`  ${privatePath}`);
  console.log(`  ${publicPath}`);
  console.log(`  kid = ${kid}`);
}
 
main().catch((err) => {
  console.error(err);
  process.exit(1);
});

// package.json (extrait — section "scripts")
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "generate-keys": "tsx scripts/generate-keys.ts",
    "debug:token": "node --env-file=.env.local --import tsx scripts/print-token.ts"
  }
}

# .gitignore (à ajouter)
keys/

npm run generate-keys
# Clés générées :
#   /home/you/quizlab/keys/private.pem
#   /home/you/quizlab/keys/public.jwk.json
#   kid = 4Fzq1Yl0V8mMWQnH_c3kM9dZ0aBqT6cW7yPiJ2eR5xg

// lib/lti/config.ts
//
// Configuration de l'outil QuizLab : URL publique, secret de session,
// paire de clés RSA. Charge tout au premier import et échoue vite si
// une variable d'environnement manque.
 
import { readFileSync } from "node:fs";
import path from "node:path";
 
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Variable d'environnement manquante : ${name}`);
  }
  return value;
}
 
function loadPrivateKeyPem(): string {
  // En prod : la clé directement dans l'env (les \n sont échappés en \\n)
  if (process.env.TOOL_PRIVATE_KEY) {
    return process.env.TOOL_PRIVATE_KEY.replace(/\\n/g, "\n");
  }
  // En dev : un fichier sur disque
  const keyPath = requireEnv("TOOL_PRIVATE_KEY_PATH");
  return readFileSync(path.resolve(process.cwd(), keyPath), "utf8");
}
 
export interface PublicJwk {
  kty: string;
  n: string;
  e: string;
  kid: string;
  alg: string;
  use: string;
}
 
function loadPublicJwk(): PublicJwk {
  const raw = process.env.TOOL_PUBLIC_JWK
    ? process.env.TOOL_PUBLIC_JWK
    : readFileSync(
        path.resolve(process.cwd(), requireEnv("TOOL_PUBLIC_JWK_PATH")),
        "utf8",
      );
  const jwk = JSON.parse(raw) as PublicJwk;
  if (!jwk.kid || !jwk.n) {
    throw new Error("JWK publique invalide : kid ou n manquant.");
  }
  return jwk;
}
 
export const toolConfig = {
  /** URL publique de l'outil, sans slash final. */
  baseUrl: requireEnv("TOOL_BASE_URL").replace(/\/$/, ""),
  /** Secret HMAC (cookies state + session). */
  sessionSecret: requireEnv("SESSION_SECRET"),
  /** Clé privée RSA au format PEM PKCS#8. */
  privateKeyPem: loadPrivateKeyPem(),
  /** Clé publique au format JWK (exposée sur /api/lti/jwks). */
  publicJwk: loadPublicJwk(),
} as const;
 
/** Le kid de la clé courante de l'outil. */
export const toolKid: string = toolConfig.publicJwk.kid;
 
/** URL de redirection OIDC de l'outil (le redirect_uri enregistré dans Moodle). */
export const launchUrl = `${toolConfig.baseUrl}/api/lti/launch`;

// lib/lti/keys.ts
//
// Import (et mise en cache) de la clé privée de l'outil pour signer
// avec jose. Le type est inféré depuis importPKCS8 pour rester
// compatible entre les versions de jose (KeyLike en v5, CryptoKey en v6).
 
import { importPKCS8 } from "jose";
import { toolConfig } from "./config";
 
type ToolPrivateKey = Awaited<ReturnType<typeof importPKCS8>>;
 
let cached: Promise<ToolPrivateKey> | undefined;
 
export function getToolPrivateKey(): Promise<ToolPrivateKey> {
  cached ??= importPKCS8(toolConfig.privateKeyPem, "RS256");
  return cached;
}

// lib/lti/registry.ts
//
// Registre des plateformes connues, indexé par (issuer, client_id).
// Aujourd'hui : une Map alimentée par l'environnement.
// Demain : une table `platforms` en base (voir section 13).
 
import { createRemoteJWKSet } from "jose";
 
export interface LtiPlatform {
  /** Nom lisible, pour les logs. */
  name: string;
  /** iss des id_token émis par la plateforme (URL racine du Moodle). */
  issuer: string;
  /** client_id attribué à l'outil par cette plateforme. */
  clientId: string;
  /** deployment_ids autorisés pour ce client_id. */
  deploymentIds: string[];
  /** Endpoint d'autorisation OIDC (mod/lti/auth.php). */
  authUrl: string;
  /** Endpoint de token OAuth2 (mod/lti/token.php). */
  tokenUrl: string;
  /** JWKS de la plateforme (mod/lti/certs.php). */
  jwksUrl: string;
}
 
const platforms = new Map<string, LtiPlatform>();
 
const keyOf = (issuer: string, clientId: string) => `${issuer}�${clientId}`;
 
export function registerPlatform(platform: LtiPlatform): void {
  platforms.set(keyOf(platform.issuer, platform.clientId), platform);
}
 
/**
 * Résout une plateforme. Si client_id est absent (certains LMS ne
 * l'envoient pas à l'initiation), on retombe sur la première entrée
 * qui matche l'issuer — acceptable tant qu'un même issuer n'a qu'une
 * inscription.
 */
export function getPlatform(
  issuer: string,
  clientId?: string,
): LtiPlatform | undefined {
  if (clientId) return platforms.get(keyOf(issuer, clientId));
  for (const platform of platforms.values()) {
    if (platform.issuer === issuer) return platform;
  }
  return undefined;
}
 
// --- JWKS distants, mis en cache par URL --------------------------
// createRemoteJWKSet gère lui-même le cache HTTP des clés (rafraîchi
// automatiquement si un kid inconnu apparaît, avec un cooldown), mais
// il faut réutiliser LA MÊME instance entre les requêtes pour en
// profiter — d'où cette Map au niveau module.
 
type RemoteJwks = ReturnType<typeof createRemoteJWKSet>;
const jwksCache = new Map<string, RemoteJwks>();
 
export function getPlatformJwks(platform: LtiPlatform): RemoteJwks {
  let jwks = jwksCache.get(platform.jwksUrl);
  if (!jwks) {
    jwks = createRemoteJWKSet(new URL(platform.jwksUrl));
    jwksCache.set(platform.jwksUrl, jwks);
  }
  return jwks;
}
 
// --- Amorçage depuis l'environnement ------------------------------
 
if (process.env.LTI_ISSUER) {
  registerPlatform({
    name: "Moodle principal",
    issuer: process.env.LTI_ISSUER,
    clientId: process.env.LTI_CLIENT_ID ?? "",
    deploymentIds: (process.env.LTI_DEPLOYMENT_ID ?? "")
      .split(",")
      .map((s) => s.trim())
      .filter(Boolean),
    authUrl: process.env.LTI_AUTH_URL ?? "",
    tokenUrl: process.env.LTI_TOKEN_URL ?? "",
    jwksUrl: process.env.LTI_JWKS_URL ?? "",
  });
}

// app/api/lti/jwks/route.ts
//
// JWKS public de l'outil. Moodle est configuré avec
// "Public key type = Keyset URL" pointant ici (section 8).
 
import { NextResponse } from "next/server";
import { toolConfig } from "@/lib/lti/config";
 
export async function GET(): Promise<NextResponse> {
  return NextResponse.json(
    {
      keys: [toolConfig.publicJwk],
    },
    {
      headers: {
        // Moodle peut mettre cette réponse en cache sans risque :
        // en cas de rotation on publie l'ancienne ET la nouvelle clé
        // pendant la période de transition (section 13).
        "Cache-Control": "public, max-age=3600",
      },
    },
  );
}

curl -s https://tool.example.com/api/lti/jwks | python3 -m json.tool
# {
#     "keys": [
#         {
#             "kty": "RSA",
#             "n": "xGOr-H7A-PWG...",
#             "e": "AQAB",
#             "kid": "4Fzq1Yl0V8mMWQnH_c3kM9dZ0aBqT6cW7yPiJ2eR5xg",
#             "alg": "RS256",
#             "use": "sig"
#         }
#     ]
# }

// lib/lti/session.ts
//
// Jetons internes de l'outil, signés HS256 avec SESSION_SECRET :
//  - state OIDC (cookie qzl_state + paramètre state), durée 5 min
//  - session applicative (cookie qzl_session), durée 2 h
 
import { SignJWT, jwtVerify, type JWTPayload } from "jose";
import { cookies } from "next/headers";
import { randomUUID } from "node:crypto";
import { toolConfig } from "./config";
 
const secret = new TextEncoder().encode(toolConfig.sessionSecret);
 
export const STATE_COOKIE = "qzl_state";
export const SESSION_COOKIE = "qzl_session";
 
// ------------------------------------------------------------------
// 1) Le state OIDC
// ------------------------------------------------------------------
 
export interface LoginState {
  /** Le nonce que l'on s'attend à retrouver dans l'id_token. */
  nonce: string;
  /** Plateforme résolue à l'initiation. */
  issuer: string;
  clientId: string;
  /** Paramètres du login initial, conservés pour le re-lancement
   *  en nouvelle fenêtre si les cookies sont bloqués (section 9). */
  loginHint: string;
  messageHint?: string;
  targetLinkUri?: string;
}
 
export async function createStateToken(state: LoginState): Promise<string> {
  return new SignJWT({ ...state })
    .setProtectedHeader({ alg: "HS256" })
    .setJti(randomUUID()) // rend chaque state unique
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(secret);
}
 
export async function verifyStateToken(token: string): Promise<LoginState> {
  const { payload } = await jwtVerify(token, secret, {
    algorithms: ["HS256"],
  });
  return payload as unknown as LoginState;
}
 
// ------------------------------------------------------------------
// 2) La session applicative
// ------------------------------------------------------------------
 
export interface QuizLabSession {
  /** Identifiant opaque et stable de l'utilisateur chez la plateforme. */
  sub: string;
  name?: string;
  email?: string;
  /** URIs de rôles LIS (voir lib/lti/roles.ts). */
  roles: string[];
  /** De quelle inscription vient ce launch. */
  issuer: string;
  clientId: string;
  deploymentId: string;
  messageType: string;
  /** Contexte (le cours Moodle). */
  contextId?: string;
  contextTitle?: string;
  /** Le placement précis (l'activité) dans le cours. */
  resourceLinkId?: string;
  /** Paramètres custom (ex. quiz_id posé par le Deep Linking). */
  custom?: Record<string, string>;
  /** Endpoints AGS extraits du claim lti-ags/claim/endpoint. */
  ags?: { lineitems?: string; lineitem?: string; scopes: string[] };
  /** Endpoint NRPS extrait du claim lti-nrps/claim/namesroleservice. */
  nrps?: { url: string; versions: string[] };
  /** Présent uniquement pour un launch LtiDeepLinkingRequest. */
  deepLinking?: { returnUrl: string; data?: string };
}
 
export async function createSessionToken(
  session: QuizLabSession,
): Promise<string> {
  return new SignJWT({ ...session } as unknown as JWTPayload)
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime("2h")
    .sign(secret);
}
 
/**
 * Lit et vérifie la session depuis le cookie. Utilisable dans les
 * Server Components et les route handlers (cookies() de next/headers).
 * Retourne null si absente, invalide ou expirée.
 */
export async function readSession(): Promise<QuizLabSession | null> {
  const store = await cookies(); // Next 15 : cookies() est asynchrone
  const token = store.get(SESSION_COOKIE)?.value;
  if (!token) return null;
  try {
    const { payload } = await jwtVerify(token, secret, {
      algorithms: ["HS256"],
    });
    return payload as unknown as QuizLabSession;
  } catch {
    return null; // expirée ou falsifiée → comme si elle n'existait pas
  }
}

// app/api/lti/login/route.ts
//
// Initiation OIDC (third-party initiated login).
// Moodle nous prévient qu'un launch arrive ; on répond par une
// redirection 303 vers son endpoint d'autorisation, avec NOTRE state
// et NOTRE nonce, et on pose le cookie de corrélation.
 
import { NextRequest, NextResponse } from "next/server";
import { randomUUID } from "node:crypto";
import { toolConfig, launchUrl } from "@/lib/lti/config";
import { getPlatform } from "@/lib/lti/registry";
import { createStateToken, STATE_COOKIE } from "@/lib/lti/session";
 
export async function GET(req: NextRequest): Promise<NextResponse> {
  return handleLogin(req.nextUrl.searchParams);
}
 
export async function POST(req: NextRequest): Promise<NextResponse> {
  const form = await req.formData();
  const params = new URLSearchParams();
  form.forEach((value, key) => {
    if (typeof value === "string") params.set(key, value);
  });
  return handleLogin(params);
}
 
async function handleLogin(params: URLSearchParams): Promise<NextResponse> {
  // --- 1. Lire les paramètres de l'initiation ---------------------
  const iss = params.get("iss");
  const loginHint = params.get("login_hint");
  const targetLinkUri = params.get("target_link_uri") ?? undefined;
  const messageHint = params.get("lti_message_hint") ?? undefined;
  const clientId = params.get("client_id") ?? undefined;
  const deploymentId = params.get("lti_deployment_id") ?? undefined;
 
  if (!iss || !loginHint) {
    return NextResponse.json(
      { error: "invalid_request", error_description: "iss et login_hint sont requis." },
      { status: 400 },
    );
  }
 
  // --- 2. Résoudre la plateforme dans le registre -----------------
  const platform = getPlatform(iss, clientId);
  if (!platform) {
    return NextResponse.json(
      { error: "unknown_platform", error_description: `Plateforme non enregistrée : ${iss}` },
      { status: 400 },
    );
  }
  // Vérification opportuniste : si Moodle annonce un deployment_id,
  // il doit être connu (la vérification ferme aura lieu au launch).
  if (deploymentId && !platform.deploymentIds.includes(deploymentId)) {
    return NextResponse.json(
      { error: "invalid_deployment", error_description: `deployment_id inconnu : ${deploymentId}` },
      { status: 400 },
    );
  }
 
  // --- 3. Générer nonce + state -----------------------------------
  const nonce = randomUUID();
  const state = await createStateToken({
    nonce,
    issuer: platform.issuer,
    clientId: platform.clientId,
    loginHint,
    messageHint,
    targetLinkUri,
  });
 
  // --- 4. Construire l'URL d'autorisation Moodle ------------------
  const authUrl = new URL(platform.authUrl);
  authUrl.searchParams.set("scope", "openid");            // imposé par OIDC
  authUrl.searchParams.set("response_type", "id_token");  // flow implicite : l'id_token arrive directement
  authUrl.searchParams.set("response_mode", "form_post"); // ... par POST de formulaire, pas dans un fragment #
  authUrl.searchParams.set("prompt", "none");             // ne JAMAIS afficher de page de login Moodle
  authUrl.searchParams.set("client_id", platform.clientId);
  authUrl.searchParams.set("redirect_uri", launchUrl);    // doit être EXACTEMENT l'URI enregistrée dans Moodle
  authUrl.searchParams.set("login_hint", loginHint);      // opaque : on le renvoie tel quel
  authUrl.searchParams.set("state", state);
  authUrl.searchParams.set("nonce", nonce);
  if (messageHint) {
    // Opaque aussi : Moodle y encode l'activité/le type de message visés
    authUrl.searchParams.set("lti_message_hint", messageHint);
  }
 
  // --- 5. Rediriger + poser le cookie de corrélation --------------
  const res = NextResponse.redirect(authUrl, 303);
  res.cookies.set(STATE_COOKIE, state, {
    httpOnly: true,      // inaccessible à document.cookie
    secure: true,        // HTTPS uniquement (requis avec SameSite=None)
    sameSite: "none",    // le POST du launch viendra d'un autre site (Moodle)
    partitioned: true,   // cookie CHIPS — voir section 9
    path: "/api/lti",    // inutile ailleurs
    maxAge: 300,         // 5 minutes : le temps d'un aller-retour, pas plus
  });
  return res;
}