Help / Single sign on

For Single Sign On implementations FlexiQuiz allows authenticated access using JSON Web Tokens (JWTs).

JSON Web Tokens are an open standard that allow you to securely transmit authentication details which can then be used to automatically authenticate and log a user in. Within FlexiQuiz a signed JWT can be passed within a URL, as a parameter, or included in a POST request. FlexiQuiz only allows a token to be used to login a single time and the token must contain an expiry.

A JSON Web Token consists of three sections:

  • Header
  • Payload
  • Signature


Header

For FlexiQuiz the tokens signature must be HMAC SHA256 encoded and so the header section should always be:

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


Payload

The payload must contain either the user's login name or the user_id and also a token expiry date and time, as a Unix timestamp. The user_id can be retrieved from the FlexiQuiz API using Get all users

{
    "user_name": "users login name",
    "exp": "token expiry date and time"
}

or

{
    "user_id": "retrieved from FlexiQuiz API",
    "exp": "token expiry date and time"
}


Signature

The signature is combination of the header and payload that has been signed with a shared secret using the HMAC SHA256 algorithm.


Each section within the token should be Base64 URL encoded and the overall token is should be in the format:

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

A valid completed token will look similar to:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMDZlMzI0NGYtMTM4MS00ZGE0LWFhNzUtOTk2OTgxYjQyZWRiIiwiZXhwIjoxNTYzMTc0NzY4fQ.om6MvC_FLHIpEp8dNBwkY7lcKOXfLKmu2wV2Y_uVAmo

Enabling JSON Web Tokens and creating a shared secret

JWTs are only available on the FlexiQuiz Enterprise plan and must initially be enabled with the single sign-on section of the Settings screen. Once enabled you will also have to create a shared secret:

Single sign on

Tip: For security the Single sign-on screen is only accessible by the user that originally created the account.

Once generated there are options to delete or roll the shared secret. When you select to roll your shared secret then the existing secret will no longer be valid, and a new shared secret will be displayed. Never share your shared secret and if you suspect a shared secret leak then create a new shared secret using the roll shared secret button.


Logging in

Once you have created your JWT and signed the signature, using the shared secret, you can login by passing the JWT to the to the following URL:

https://www.flexiquiz.com/account/auth?cla=t&jwt={your JWT}

or, you can also pass the JWT within a POST request:

URL: https://www.flexiquiz.com/account/auth?cla=t

Data: jwt: {your JWT}

Logging in directly to a quiz

Repondent users can also be logged straight into taking a quiz or for Administrators and Trainers taken directly to editing a quiz. For this just include the quiz_id as a parameter in the authentication request:

https://www.flexiquiz.com/account/auth?cla=t&jwt={your JWT}&quiz_id={your quiz_id}



Back