Guide technique SSO JWT

Introduction

L’authentification unique (en anglais : « Single Sign-On », ou SSO) est un mécanisme d’authentification qui permet aux utilisateurs de se connecter à plusieurs applications avec le même identifiant et mot de passe.

En activant le SSO sur 360Learning, vous êtes responsable de l’authentification de vos utilisateurs : ils se connectent à travers votre propre portail de connexion, et n’utilisent pas le système de 360Learning.

La communication entre votre système d’authentification et 360Learning peut être géré par plusieurs protocoles ou standards, notamment JWT (JSON Web Token). Il s’agit d’une norme relativement récente, mais utilisée dans de nombreuses implémentations open-source.

Processus

L’utilisation d’un SSO nécessite plusieurs échanges entre le navigateur et le système d’authentification, avec JWT.

Processus sans SSO

1. Un utilisateur non-authentifié demande un accès à votre espace 360Learning.
2. L’utilisateur est redirigé vers la page de connexion 360Learning, sur laquelle il peut rentrer son identifiant et mot de passe.
3. Si l’identifiant et le mot de passe sont corrects, 360Learning autorise l’accès, et redirige l’utilisateur vers la plateforme.

Processus avec SSO

1. Un utilisateur non-authentifié demande un accès à votre espace 360Learning.
2. 360Learning redirige l’utilisateur vers votre page de connexion.
3. L’utilisateur se connecte en utilisant l’identifiant et mot de passe pour votre système.
4. Vous créez un jeton JWT sécurisé, contenant l’information de l’utilisateur.
5. Vous redirigez l’utilisateur vers notre page de récupération du jeton JWT.
6. 360Learning analyse le jeton, et autorise éventuellement l’utilisateur à accéder à la plateforme.

Configuration

Mise en place

Pour activer le SSO sur votre plateforme 360Learning, contactez votre Account Manager, qui vous guidera dans la mise en place.

Éléments qui seront fournis par 360Learning :

• Votre identifiant unique de plateforme (souvent appelé « company ID »).
• Une chaîne de caractères, appelée « Secret », qui sera utilisée pour générer les jetons d’authentifications JWT.

Éléments que vous devrez générer de votre côté :

• L’URL du portail de connexion à votre système d’authentification (par exemple : https://mycompany.com/sso). Votre portail doit remplir les conditions définies dans les sections suivantes.
• Un jeu d’identifiants + mot de passe de test.

Anatomie d’un jeton JWT

Une fois l’utilisateur authentifié de votre côté, vous devez créer un jeton contenant certaines informations sur l’utilisateur.

Le jeton doit être ajouté à la fin de l’URL de la plateforme 360Learning, comme ceci : https://mycompany.360learning.com/?jwt={token}.

Le jeton doit contenir les attributs suivants :

• un header ;
• un contenu (payload) contenant plusieurs champs (détaillés ci-dessus) ;
• une signature.

Le header

• Le jeton doit être au format JSON encodé en base64.
• La signature doit être générée avec l’algorithme de hash HS256 (HMAC SHA256).

{ 
	"typ":"JWT", 
	"alg":"HS256" 
}

Le contenu (payload)

Le jeton doit être au format JSON encodé en base64.

Attributs obligatoires :

• iat (« issued at ») ;
  • jti (« JSON Web Token ID ») ;
  • email (« adresse email de l’utilisateur »).

Attributs optionnels (si le compte n’existe pas sur la plateforme 360Learning, les informations sont utilisées pour créer le compte) :

• un attribut « firstName » ;
  • un attribut « lastName » ;
  • un attribut « phone » ;
  • un attribut « lang » (valeurs possibles : en ou fr) ;
  • un attribut « role » (valeurs possibles : learner, author ou admin) ;
  • un attribut « job » ;
  • un attribut « organization » ;
  • un attribut « custom ».

La signature

Hash du header et du contenu, en utilisant :

• l’algorithme de hash défini dans le header ;
• la chaîne de caractères Secret fournie par 360Learning.

HMACSHA256(
	base64UrlEncode(header) + "." +
	base64UrlEncode(payload),
	secret)

Ressources JWT

Guide de référence :

• Introduction to JSON Web Tokens (en anglais)

Bibliothèques open-source pour générer des JSON Web Tokens :

• Pour Ruby
• Pour PHP
• Pour Node.js

Paramètre de route

Lors de la redirection d’un utilisateur vers la page de récupération du jeton JWT (le endpoint de 3360Learning), vous pouvez également indiquer d’autres paramètres dans l’URL. Par exemple, l’URL d’un groupe ou d’un parcours spécifique. Une fois l’authentification réussie, l’utilisateur sera alors redirigé vers cette URL.

• Par exemple, avec l’URL suivante : https://mycompany.360learning.com/?company={company\_id}&jwt=\{token}&route={a\_specific\_route}
• L’utilisateur sera redirigé vers cette destination : https://mycompany.360learning.com/{a\_specific\_route}

Exemple

Voici un exemple de code en node.js, qui utilise le module node-jsonwebtoken (testé sur la version 7.3.0).

var router = require("express").Router();
var jwt = require("jsonwebtoken");

router.get("/", function (req, res, next) {

	// Verify in the database that the login / password is correct, or 
	equivalent
	// Get the user data from the database (email, firstName, lastName, 
	phone, role)

	var cid = "4e54273d5d17859d464cb9bc", // Get the 360Learning company id 
	from a config file, or equivalent
	key = "oB9eNDdAp2mXpw996gdunxe1"; // Get the secret key from a config 
	file, or equivalent

	var token = jwt.sign({
		email: "test.user@360learning.com", // Mandatory
		firstName: "Test", // Optional, only used if the account does 
		not exists on 360Learning yet
		lastName: "Name", // Idem
		phone: "0123456789", // Idem
		lang: "en", // Idem, possible values: [ en, fr ], default: en
		role: "trainee" // Idem, possible values: [ admin, user, trainee 
		], default: trainee
	}, key, { expiresIn: 60 });

	res.redirect("https://app.360learning.com/?company=" + cid + "&jwt=" + 
	token + "&route=" +
	encodeURIComponent(req.query.route));

});

exports.router = router;