Single Sign On with JSON Web Token
Written by Diego Selzlein
Updated at October 21st, 2024, by Nicholas Jarretta
Table of Contents
Single Sign-On with JSON Web Token (JWT) Setting Up JWT SSO JWT Fields Signing Users In Redirection After Sign-In Syncing Role and Groups Warning Signing Users Out JWT Fields Signing Users In Redirection after sign-in Syncing role and groups Signing Users OutHelpjuice supports authenticating users via Single Sign On with JWT. It works like this:
- The user chooses to authenticate through SSO
- Helpjuice redirects the user to your website where they can authenticate with a user/password
- Your website generates a JSON Web Token using the shared key Helpjuice provides and redirects the user with the token back to Helpjuice
- Helpjuice decodes the token and authenticates the user with the email you provided
- If the user is a new one, we will create a new Internal Viewer 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:
| Field | Required? | Description |
| jti | yes | This field contains a unique token ID generated by your website. Helpjuice will use it to prevent replay attacks. |
| iat | yes | This field has to contain the token creation time in milliseconds since Unix epoch. Helpjuice will only accept tokens up to 3 minutes old. |
| yes | The authenticated user's email so Helpjuice can identify the user. | |
| first_name | no | The user's first name. |
| last_name | no | The user's last name |
| group_names | no | A comma-separated string of groups that the user must belong to. If this field isn't specified, we create the user with no groups. Note: The groups must exist in Helpjuice with the exact name you specify here. Otherwise, we just ignore the invalid groups. |
| role_id | no | The role for the user. If this field isn't specified, we create the user as an Internal Viewer. Note: The value for this field must be one of the following: superadmin, admin, collaborator, draft_writer, or viewer. If the value doesn't match any of them, the authentication fails and we show an error message explaining why. |
In order to debug issues with your token, use https://jwt.io. It provides a tool to parse your token and show you if it's using the right layout.
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.
Redirection after sign-in
If the user was trying to access a restricted page when we sent him to your server for login, we also append a query parameter called fallback_url set to the original request URL, like: https://my.website.com/login?service=helpjuice&fallback_url=https://yourdomain.helpjuice.com/article-url.
Your server should send the value of this field back to Helpjuice in the fallback_url query parameter, like: https://helpjuice.com/jwt/YOUR_SUBDOMAIN?jwt=YOUR_ENCODED_TOKEN&fallback_url=https://yourdomain.helpjuice.com/article-url.
If you don't send the fallback_url parameter back to Helpjuice, we wil try to redirect using session cookie values, and, if that isn't possible, we will redirect the user based on the configuration in the User Behavior & Tracking settings page.
Syncing role and groups
The user's role and groups can be specified in the token and we will use these values when auto-provisioning a user. However, we don't sync these values for existing users during login by default. You can enable syncing the role and groups on every login by toggling the respective options in the JWT SSO settings page:
Warning
If the group_names field in the token is present and is set to an empty string, the user is removed from all of his groups in Helpjuice. If you desire to skip modifying the groups and leave them untouched, don't include the group_names field in the token.
Signing Users Out
After signing a user out, Helpjuice will redirect them to the Logout URL you provided (if present).