Integration of iSpring Learn with your system

The iSpring Learn system provides various methods and interfaces that makes integration with your system (a website or service) possible.

Prerequisites:

  • Web development skills (PHP, JavaScript, JSON, JWT).
  • A system with admin access to your hosting and the source code.
  • An iSpring Learn account (full or trial).

In this article:

User ID

An email is a unique field for each user in iSpring Learn. Two different users can’t have the same email address, because it’s a unique identifier. In terms of SSO, it’s important that you use the same user email on your website as in the iSpring Learn system.

If you need to change a user email in the iSpring Learn system, you can only do it manually in the admin settings panel and per user individually. Automatic or bulk methods of changing the email are not available.

Manage users

Other than manual user management, iSpring Learn provides two other methods to perform bulk user import or apply external automation with API.

  1. 1

    Import users using a CSV spreadsheet file, if you have a pre-defined list of users. It will do a bulk import of many users or change the existing users’ fields at once.

  2. 2

    Automate user management using iSpring Learn API. You can use REST and SOAP API in your web services to manage users in iSpring Learn remotely. For instance, you can sync user lists between your website’s SQL database and iSpring Learn (where direct SQL access is not allowed).

  3. 3

    If you log in a new user using SSO, this user (email) will be automatically added to the user list on the iSpring Learn side.

Single Sign-On in iSpring Learn

If your own website authenticates users, and you want them at some point to be smoothly redirected to the iSpring Learn portal without entering their details again, you need to set up single sign-on (SSO). This technology automatically authenticates users between two or more independent web services (websites) within a particular browser session, once they are logged into one of these services. It eliminates additional prompts, which reduces password fatigue, creates an uninterrupted user experience, and eventually makes users more satisfied with your services.

Google Account usage is the most common single sign-on example that almost everybody experiences every day. The system prompts you to login just once and then gives you access to all its services: Gmail, YouTube, Google Drive, etc., without asking you to enter your details again.

JWT Technology for SSO

To perform single sign-on, iSpring Learn uses 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.

JWT Technology of SSO to iSpring Learn

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. 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. 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:

    {
      "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;
    emailemail 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. 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. 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. 2

    Click Enable JWT login for this account.
    SSO settings page in iSpring Learn system

  3. 3

    Set the Security key. This value is also the secret part of your token (ZZZ) or a cryptographic key.

  4. 4

    Identity provider URL should contain your website’s page that will send a JWT to login a user.

  5. 5

    Logout URL should contain your website’s page that will send a JWT to logout a user. It is used optionally. The session can be also finished by clicking Logout in the upper right corner of the 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.

  • 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 HTTPS protocol instead of HTTP for better security.

Note: You can optionally use the GET parameter no_jwt to control the JWT login option in your account. For example, it turns the Enable JWT option off: https://yourcompany.ispringlearn.com/login?no_jwt=1

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 qualify 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 of adding the new user automatically can appear 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.

  1. A user (not yet authorized) visits your iSpring Learn portal at https://yourcompany.ispringlearn.com

  2. 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/

  3. Your website authenticates the user using your standard procedure.

  4. 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:

  1. If the user is authorized, the system redirects this user to iSpring Learn.

  2. 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

See also:

Was this article helpful?

Thanks for your feedback!

How can we help you?

EMAIL
MESSAGE

Your request to iSpring has been submitted.

Please check your email for support replies. We reply to every message asap. If you don't hear back from us, check your spam folder and add to your list of approved senders.

Oops! Something went wrong...

Please contact them at .