Moodle et LTI 1.3

Cette page documente l'intégration de Kutsum comme outil externe LTI 1.3 depuis Moodle.

Elle couvre :

• le cas de test local avec docker/moodle
• le cas d'une vraie instance Moodle
• les paramètres à recopier côté Kutsum
• les limites connues du flux actuel

Cas local : Moodle Docker

Le dépôt contient un environnement local dans docker/moodle/ pour tester le flux LTI 1.3 avec Kutsum.

Commandes :

cd docker/moodle
sudo docker compose up -d

Moodle est alors disponible sur http://localhost:8080.

Pour le flux multi-tenant local validé actuellement, le runbook retenu est :

cd app
FRONTEND_URL=http://utbm.kutsum.local:3008 npm run dev

cd docker/moodle
./configure-kutsum-tool.sh http://utbm.kutsum.local:3008

Pré-requis côté navigateur / OS :

• http://app.kutsum.local:3008 affiche la homepage standard
• http://utbm.kutsum.local:3008 affiche la homepage tenant UTBM
• http://localhost:3008 reste équivalent au tenant principal app

Comptes de test :

Outil LTI local après retargeting UTBM :

Pourquoi ce split local :

• le navigateur Moodle peut joindre localhost:3007 directement pour /api/v1/lti/*
• le backend Kutsum utilise ensuite FRONTEND_URL pour sa redirection finale
• pour tester le tenant UTBM, FRONTEND_URL doit donc pointer vers http://utbm.kutsum.local:3008

Le script docker/moodle/configure-kutsum-tool.sh modifie la ligne Moodle persistée en base (mdl_lti_types.name = 'Kutsum') sans passer par l'UI.

Déclarer Kutsum dans une vraie instance Moodle

Chemin Moodle habituel :

Administration du site -> Plugins -> Modules d'activité -> Outil externe -> Gérer les outils

Checklist à envoyer à l'admin Moodle :

1. créer un outil LTI 1.3
2. saisir les URLs Kutsum sur le host du tenant, pas sur app.kutsum.org
3. transmettre ensuite à l'équipe Kutsum issuer, clientId, deploymentId

Ce que Kutsum attend en retour :

• issuer: URL canonique Moodle
• clientId: identifiant LTI généré par Moodle
• deploymentId: identifiant de déploiement LTI

Exemple pour :

• Moodle : https://app.utbm.org
• Tenant Kutsum : https://utbm.kutsum.org

Valeurs à saisir dans Moodle :

Points importants :

• clientId et deploymentId ne doivent pas être inventés.
• si Moodle ne les montre pas au moment de la création, la source la plus fiable est la requête envoyée vers /api/v1/lti/login
• Kutsum n'implémente pas aujourd'hui le flux LTI Deep Linking
• toutes les URLs doivent être en https

Configuration côté Kutsum

Le config JSON du provider LTI_13 doit ressembler à ceci :

{
  "issuer": "https://app.utbm.org",
  "clientId": "<CLIENT_ID_MOODLE>",
  "deploymentId": "<DEPLOYMENT_ID_MOODLE>",
  "oidcAuthUrl": "https://app.utbm.org/mod/lti/auth.php",
  "jwksUri": "https://app.utbm.org/mod/lti/certs.php",
  "tokenUrl": "https://app.utbm.org/mod/lti/token.php",
  "authorizationUrl": "https://app.utbm.org/mod/lti/auth.php",
  "redirectUri": "https://utbm.kutsum.org/api/v1/lti/launch"
}

En production, ce provider doit aussi contenir la paire de clés LTI Kutsum :

• ltiKeyId
• ltiPublicJwk
• ltiPrivateKeyEncrypted
• ltiPrivateKeyVersion

Ces champs sont générés à partir de LTI_MASTER_KEY puis stockés dans le provider IdentityProvider actif.

Diagnostic rapide quand Moodle échoue immédiatement

Si Moodle ouvre directement une erreur Unknown LTI issuer or client_id, le backend Kutsum renvoie maintenant aussi les identifiants reçus :

{
  "error": "Unknown LTI issuer or client_id",
  "received": {
    "iss": "https://app.utbm.org",
    "client_id": "...",
    "lti_deployment_id": "..."
  }
}

Cela permet de recopier exactement les valeurs à enregistrer dans le provider LTI Kutsum, sans devoir intercepter la requête réseau au vol.

Redirection LTI post-launch tenant-aware

La redirection post-launch dérive automatiquement l'URL frontend du tenant à partir du sous-domaine de l'organisation LTI (Organization.subdomain) et de la valeur de FRONTEND_URL configurée sur le backend.

Principe : si FRONTEND_URL=https://app.kutsum.org et que le launch provient d'un IdentityProvider rattaché à l'org dont le sous-domaine est utbm, la redirection finale pointe vers https://utbm.kutsum.org, pas vers https://app.kutsum.org.

Pré-requis :

• FRONTEND_URL doit utiliser le format {subdomain}.domaine.tld (avec au moins 3 segments dans le hostname) pour que la dérivation fonctionne.
• En développement local, utiliser FRONTEND_URL=http://app.kutsum.local:3008 dans app/backend/.env (et non http://localhost:3008).
• Chaque tenant doit avoir son propre IdentityProvider avec un clientId distinct dans Moodle.

Pour provisionner le tenant UTBM en local (idempotent) :

cd docker/moodle
bash provision-utbm-tenant.sh

Ce script crée un outil Moodle LTI dédié (clientId=kutsum-lti-utbm-dev), une activité LTI dans le cours de test, et l'IdentityProvider correspondant en DB. le backend avec FRONTEND_URL=http://utbm.kutsum.local:3008.