Menu
Le JSON Web Token (JWT) est un standard ouvert (RFC 7519) qui définit une manière compacte et autonome de transmettre en toute sécurité des informations entre les parties sous forme d’un objet JSON. Cette information peut être vérifiée et de confiance car elle est signée numériquement. JWT peut être signé en utilisant un secret (avec l’algorithme HMAC) ou une paire de clés publique/privée en utilisant RSA ou ECDSA.
Dans THEIA, nous utilisons JWT pour implémenter une authentification Single Sign-On (SSO) sécurisée via l’algorithme (HS256) et qui permet à partir d’un simple serveur de prendre en charge la création et l’authentification d’utilisateurs en embarquant un certains nombres d’informations diverses.
1. Prérequis et informations diverses
Prérequis :
Serveur et url de redirection permettant de générer et d’embarquer un token JWT
Compte actif sur la plateforme THEIA et disposant d’un droit de configuration du SSO
Variable permettant le mapping : username
Synchronisation et mise à jour des informations : à la connexion, création et mise à jour des informations du compte.
2. Couverture fonctionnelle
Authentification | Mapping des groupes | Mapping du Matricule | Mapping Attributs supplémentaires | Création et mise à jour des comptes | Création et mise à jour des groupes | |
|---|---|---|---|---|---|---|
JWT | ✔ | ✔ | ✔ | 🚫 | ✔ | 🚫 |
3. Configuration dans THEIA
En dehors du paramétrage de l’ADFS, annuaire ou portail faisant office de fournisseur d’identité numérique, vous devez intervenir sur la configuration de votre plateforme THEIA afin d’ouvrir les accès SSO en JWT.
Une interface de configuration dédiée est accessible sur votre plateforme, dans la rubrique « Paramètres » – « Configuration SSO » – « JWT » ou via l’url https://elffe.theia.fr/sso/config/jwt
Pour accéder à cette interface, vous devez disposer d’un compte actif THEIA disposant du droit « Administrer les paramètres SSO«
4. Configuration JWT
La case Créer les utilisateurs à la volée offre la possibilité de créer automatiquement les comptes utilisateurs sur la plateforme lors de la première connexion. Si le compte existe déjà, alors il sera mis à jour avec les informations contenues dans le jeton.
Cela implique par conséquent, l’inscription ou le désinscription des utilisateurs des groupes dans lesquels ils sont inscrits. En effet, l’utilisateur ne sera inscrit que dans les groupes présents dans le jeton. Si aucun groupe n’est renseigné ou s’il n’est pas connu dans la plateforme, alors l’utilisateur ne sera inscrit dans aucun groupe.
Aussi la création automatique des groupes n’est pas permise par ce protocole. La création des comptes devra donc être réalisée manuellement ou au travers de notre api en amont.
JWT permet l’identification des utilisateurs via un échange de jetons (Token). Il s’agit d’un fichier au format Json signé par une longue chaine de caractères à l’aide de l’algorithme ainsi que de la clé secrète disponible dans l’onglet de configuration.
La signature assure l’intégrité des données dans le token et garantit que les données n’ont pas été altérées depuis leur création.
Les informations attendues sont les suivantes :
{
// Parametres obligatoires
"exp": 1704063600, // Timestamp de la date d'expiration du token
"iss": "String", // Alias de votre plateforme
"sub": "string", // Identifiant unique de l'utilisateur par le client. Correspond au matricule sur THEIA.
"preferred_username": "string", // Identifiant unique de l'utilisateur par la plateforme THEIA
"given_name": "string", // Prénom
"family_name": "string", // Nom
"email": "string", // Adresse email
"groups": ["string", "string", "..."], // Liste du ou des groupes dans lesquels l'utilisateur est inscrit
// Parametre optionnel
"extraTime": false, //L'utilisateur bénéficie d un aménagement d'épreuve
}
5. Utilisation du token et redirection
Une fois le token généré, le renvoi vers THEIA se fait à l’aide d’un lien embarquant dans l’URL d’accès le paramètre jwtToken.
Exemple : https://www.elffe.theia.fr/learning/index/jwtToken=dfsfsdf(…)4214314
Au clic utilisateur, la redirection est réalisée et le compte est éventuellement créé et/ou mis à jour en fonction de votre configuration.
L’intégration du token peut être réalisée sur n’importe quelle URL de la plateforme THEIA, vous permettant ainsi des redirections ciblées vers des pans précis de la plateforme : un espace de formation, une activité, un examen spécifique etc.
6. Aide au diagnostic, détection des anomalies
Vous pouvez, si vous le souhaitez, utiliser des outils de génération de Token JWT (jwt.io par exemple) pour valider le paramétrage de la plateforme.
Parmi les erreurs récurrentes :
- Défaut de signature : le jeton JWT doit être signé correctement pour garantir son intégrité. Une signature incorrecte ou absente peut entraîner un échec d’authentification. Vérifiez que le jeton est signé avec la clé secrète appropriée et que l’algorithme de signature correspond à celui configuré sur la plateforme THEIA.
- Expiration du jeton : Les jetons JWT ont généralement une durée de vie limitée. Un jeton expiré entraînera une erreur d’authentification. Assurez-vous que le jeton est utilisé dans sa période de validité et que le serveur générant le jeton et la plateforme THEIA ont des horloges synchronisées.
- Mauvais Format de Jeton: si le format du jeton JWT ne correspond pas à ce que la plateforme THEIA attend (par exemple, champs manquants ou mal nommés), l’authentification échouera. Vérifiez que tous les champs requis sont présents dans le jeton et qu’ils sont correctement nommés et formatés.
- Défaut de correspondance des attributs : les attributs dans le jeton JWT doivent correspondre aux champs attendus par la plateforme THEIA. Une inadéquation peut entraîner des erreurs de synchronisation des comptes. Vérifiez la correspondance entre les attributs du jeton et les champs de la plateforme THEIA. Assurez-vous que les noms d’attributs et les valeurs sont correctement mappés.
- Groupes Non Reconnus ou Absents dans le Jeton: si les groupes spécifiés dans le jeton ne correspondent pas aux groupes sur la plateforme THEIA, cela peut entraîner des erreurs d’assignation de groupe. Vérifiez que les groupes mentionnés dans le jeton existent sur la plateforme THEIA et que leur nommage est cohérent.
- Absence d’utilisateur : Si il n’existe pas de correspondance avec un utilisateur existant ou que vous n’avez pas activer la création de compte à la volée, l’authentification ne pourra pas avoir lieu. Vérifier l’existence de l’utilisateur dans THEIA ou activez l’option de création des comptes à la volée.