Technical guide - SSO JWT

Introduction

Single Sign-On (SSO) is an authentication mechanism that allows users to access several applications with only one set of login credentials.

By enabling SSO for your 360Learning application, you become responsible for the authentication of your users: they get authenticated through your own login portal and do not need an additional set of login/password anymore.

Communication between your authentication system and 360Learning can be handled by several technologies, including JWT (JSON Web Token). It's a fairly recent standard but there are a lot of open-source implementations of this specification.

Process

While using SSO, the process involved is slightly different and requires several browser redirections and message exchanges using JWT.

Standard process

1. An unauthenticated user requests access to your 360Learning space.
2. The user is redirected to the login page of your 360Learning space where he can provide his login and password.
3. 360Learning grants them permission and redirects them to your space.

SSO process

1. An unauthenticated user requests access to your 360Learning space.
2. 360Learning redirects them to your own login URL.
3. The user gets authenticated using your own authentication process.
4. You create a secured JWT token that contains information about the user.
5. You redirect them to our JWT endpoint with the JWT token.
6. 360Learning analyzes the token, grants the user permission, and redirects them to your 360Learning space.

Configuration

Setup

To enable SSO for your 360Learning space, contact your designated account manager: he will guide you through the entire integration process.

What you will get from 360Learning:

• Your company ID
• A shared secret that will be used to generate tokens and secure communication between your system and the 360Learning platform.

What you will have to provide:

• The URL of your login portal, for example, https://mycompany.com/sso. Your portal must comply with the requirements defined in the following sections.
• Test credentials.

JWT Anatomy

Once the user has been authenticated on your side, you must create a token containing the required information about the user.

The token must be appended to the return URL as a query string: https://mycompany.360learning.com/?jwt={token}

The token must contain the following attributes:

• A header
• A payload containing a few fields (more info below)
• A signature

Header

• This JSON must be base64-encoded.
• HS256 (HMAC SHA 256) is the hashing algorithm that is used to generate the signature.

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

Payload

This JSON must be base64-encoded.

Mandatory payload fields:

• An attribute "iat" (issued at).
  • An attribute "jti" (JSON Web Token id).
  • An attribute "email" (the user’s email).

Optional payload fields (if the user’s account does not exist on your 360Learning space, the following information is used to create the account):

• An attribute "firstName".
  • An attribute "lastName".
  • An attribute "phone".
  • An attribute "lang". Possible values: en, fr
  • An attribute "role". Possible values: learner, author, or admin
  • An attribute "job".
  • An attribute "organization".
  • An attribute "custom".

Signature

Hash of the base64-encoded header and the base64-encoded payload using:

• The hashing algorithm defined in the header
• The shared secret provided by 360Learning

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

JWT Resources

References and guides:

• Introduction to JSON Web Tokens

Open-source libraries where you generate JSON Web Tokens:

• For Ruby
• For PHP
• For Node.js

Route parameter

While redirecting the user to the 360Learning endpoint, you can also provide a route parameter in the URL, for example the route of a specific group or a specific program. After the authentication, 360Learning will redirect the user to this page.

• Output: https://mycompany.360learning.com/?company={company\_id}&jwt=\{token}&route={a\_specific\_route}
• The user will be redirected to https://mycompany.360learning.com/{a\_specific\_route}

Example

Node.js sample code, leveraging the node-jsonwebtoken module (tested with 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;