Single Sign On with JSON Web Token

317c44983c8b32bee66e285197ebcd1a

Written by Diego Selzlein

Last published at: February 23rd, 2019

Helpjuice supports authenticating users via Single Sign On with JWT. It works like this:

  1. The user chooses to authenticate through SSO
  2. Helpjuice redirects the user to your website where they can authenticate with user / password
  3. Your website generates a JSON Web Token using the shared key Helpjuice provides and redirects the user with the token back to Helpjuice
  4. Helpjuice decodes the token and authenticate the user with the email you provided
  5. If the user is a new one, we will create a new user account for him


To set it up, go to your account Settings > Single Sign On with JWT


Then fill in the form:


JWT Fields


These are the fields that Helpjuice will use from your JSON Web Token:

FieldRequired?Description
jtiyesThis field contains an unique token ID generated by your website. Helpjuice will use it to prevent replay attacks.
iatyesThis field has to contain the token creation time in milliseconds since Unix epoch. Helpjuice will only accept tokens up to 3 minutes old.
emailyesThe authenticated user's email so Helpjuice can identify the user.
first_namenoThe user's first name.
last_namenoThe user's last name


Signing Users In


When Helpjuice redirects a user to your login page, it will append a parameter to the URL called service and set it to helpjuice, like: https://my.website.com/login?service=helpjuice. This may be useful for you to identify the service and properly configure the authentication token layout.

Upon successful authentication, you need to sign the generated token with the Shared Secret Helpjuice provides you in that Settings page. Then you need to redirect them to https://helpjuice.com/jwt/YOUR_SUBDOMAIN?jwt=YOUR_ENCODED_TOKEN.


Signing Users Out


After signing a user out, Helpjuice will redirect them to the Logout URL you provided (if present).