iSpring Learn SSO with JWT Technology

PRODUCTS: Learn

One of the ways to perform single sign-on in iSpring Learn is to use JSON Web Token (JWT). It is an open standard for passing claims between parties in a web application environment. It is used to encrypt and pass the identity of authenticated users between an identity provider (your corporate website) and a service provider (iSpring Learn). In other words, it provides a fluent and secure login data transfer from your website to iSpring Learn.

To authenticate a user on the iSpring Learn side, a JWT message should contain the user’s email. Password and other user information is not required for SSO.

The JSON Web Token is passed to iSpring Learn as a GET parameter.

A full link with a JSON token looks like this:
https://yourcompany.ispringlearn.com/sso/login/jwt?jwt=XXXXXX.YYYYYY.ZZZ

Parts of JWT

The JWT Token is encoded and consists of 3 parts, divided by dots:

1
XXXXXX is an encoded header

BASE64-encoded, it preserves information about the token type (“JWT”) and encryption algorithm (“HS256”). In the JS object notation it looks like this:
```
{
          "typ": "JWT",
          "alg": "HS256"
        }
        
```
2
YYYYYY is an encoded payload

This is the message body of the token that passes the user ID (email). It is also represented in the BASE64 format. The clean JS notation looks like this:
```
{
  "iat" : 123456789,
  "jti" : f4as6d5f4as6d5fasd6df4,
  "exp" : 123456849,
  "email" : "username@yourcompany.com"
}
```
iat (Issued At) – stores the time when this token was created;
jti (JWT ID) – the token identifier, issued automatically and encoded;
exp – expiration time of this token;
email – email address of a user (or a user ID) that you want to authenticate. The email address of a user should be the same on both resources, your website and iSpring Learn.
3
ZZZ is a signature

This part contains a key to encrypt the entire message (all 3 parts). It looks like this:
```
HMACSHA256(base64UrlEncode(XXXXXX) + "." + base64UrlEncode(YYYYYY), secret)
```
secret – is a cryptographic key that is used by both parties of this process to encode the message.

Setting up SSO parameters

You need to configure your Learn system’s endpoint to receive authentication requests. It simply requires entering the same cryptographic key and entering URLs from which tokens will come. Follow these steps:

1
Login to your iSpring Learn account as an administrator and type the path to the JWT settings: https://yourcompany.ispringlearn.com/settings/sso/jwt
2
Click Enable JWT login for this account.
3
Set the Security key. This value is also the secret part of your token (ZZZ) or a cryptographic key.
4
The Identity provider URL should contain the page on your website that will send a JWT to login a user.
5
The Logout URL should contain the page on your website that will send a JWT to logout a user. It is used optionally. The session can also be finished by clicking Logout in the upper right corner of iSpring Learn.

Fixed fields:

The default Encryption algorithm is set to HS256 (full name is SHA 256). You can’t change the algorithm. See the encryption libraries on the JWT website if you want to learn more.
The Return URL is pre-set as well. It is an endpoint in iSpring Learn where the JWT needs to be transferred as a GET request.

Recommendations:

Use the HTTPS protocol instead of HTTP for better security.

Note: You can optionally use the GET parameter no_sso=1 to access the LMS login form skipping Single Sign-On: https://yourcompany.ispringlearn.com/login?no_sso=1. For example, adding this parameter to a link will allow a user to log in to the system even in case SSO doesn’t work on some reason.

Processing logic

The whole process is shown on the UML time sequence diagram below:
UML time sequence diagram for SSO to iSpring Learn

Right after iSpring Learn receives the JWT, it checks if the secret part of the token (ZZZ) is the same as the one set in the system. After this procedure it can verify that this message came from a trusted sender, and extract the important data by decrypting the message (using the Secure Key).

On the next step, the Learn LMS checks if this email address is registered with the system, and authenticates the user.

Using SSO, you can authenticate both users who are already registered with iSpring Learn and new users who don’t have accounts in the LMS yet.

Even if the email is not on the LMS’s user list, iSpring creates a new user automatically and authenticates him/her. The new user is included in the default organization. The same operation can be done with the help of the REST/SOAP API. However, because SSO is done through a trusted channel, there is no need to add an additional step of adding a user via an API call.

The only obstacle to adding the new user automatically is if your iSpring Learn plan has run out of free user slots.

Authorization example

Another case is when a user gets to iSpring Learn first, without logging in on your website. If a user visits the iSpring portal directly, you can still use SSO to log this user in.

A user (not yet authorized) visits your iSpring Learn portal at https://yourcompany.ispringlearn.com
If your account has the option Enable JWT turned on, the user is redirected to the Identity provider URL on your website: https://www.yourwebsite.com/login-token/
Your website authenticates the user using your standard procedure.
A script on your website sends a JWT to the iSpring Learn endpoint (https://yourcompany.ispringlearn.com/sso/login/jwt) and the user is automatically logged in to Learn.

PHP code examples

Authentication service realization (login)

This service should be placed on your website. It authenticates a user and logs this user in remotely on the iSpring Learn side. In this example, iSpring Learn LMS interacts with the authentication service. Possible cases and outcomes:

If the user is authorized, the system redirects this user to iSpring Learn.
If not authorized, the system processes the user input form. If it is successful, the system redirects this user to iSpring Learn.

A free sample at GitHub: authentication.php →

Logout user request processing

iSpring Learn LMS provides the ability to logout a user from the system as well. This service should be placed on your website. In this example, the script checks an email, performs user logout and shows the respective message.

A free sample at GitHub: logout.php →