Setting up Knowledge Base Single Sign On

Once you have configured your site to generate a JWT for your user, head to your knowledge base management screen (https://app.elev.io/kb) and scrolling to the bottom to enable the SSO (single sign on) option, and enter your SSO URL.

SSO is available on Regular and Premium plans.

Enter in the URL for where we should direct the user to on your site to generate the JWT token (see below).

Hit save and you're done. A login link will now appear in your Knowledge Base header, and on pages that are locked down if the user is not logged in.

Generating a JWT for your user

To securely share information about a user logged in to your system, we use JWT (JSON web token).

You will need to create a page on your site that serves to sole purpose of checking if the user is logged in, and returning back to us information about that user by generating a JWT (the URL of the page you create is what you enter in the SSO URL field in the Knowledge Base settings screen).

If the user is not logged in, you should direct them to your login screen, and after successful login return them back to your SSO URL to generate the JWT and return them back to elevio.

The following is pseudocode based on PHP that shows how a JWT can be generated:

$secret = 'ABCD1234';

$token = array(
  "iss" => "https://yoursite.com",
  "iat" => time(),
  "exp" => time() + 60,
  "first_name" => $user->first_name,
  "last_name" => $user->last_name,
  "email" => $user->email,
  "user_hash" => hash_hmac("sha256", $user->email, $secret),
  "groups" => ["pro", "gold"]
);

$jwt = JWT::encode($token, $secret, 'HS256');

$sso_url = $_GET['return_url'] . '?jwt=' . $jwt;

header('Location: ' . $sso_url);

Some things to note:

The $secret is your account secret, which you can get from your main account settings page.

$user is your logged in user object.

The user_hash is generated in the same way you generate it when installing the elevio assistant and identifying a user.

JWT::encode() is using a JWT library, you can find a library for your codebase here: https://jwt.io/
Use HS256 as the signing algorithm.

$_GET['return_url'] when we originally direct the user to you (when they click login), we will send a query parameter for 'return_url' which will tell you where to direct the user back to, so we can check the JWT on return.

$sso_url is generated by taking the 'return_url' and appending jwt as a new query parameter, which is assigned the JWT you just created.