How to Set Up SSO with JSON Web Token (JWT)
Authenticate your users in Helpjuice using JWT for secure Single Sign-On
Written by Diego Selzlein
Updated at September 30th, 2025, by Amanda Helpjuice
Table of Contents
Understanding JWT Authentication Setting Up JWT SSO JWT Fields Signing Users In Redirection After Sign-In Syncing Role and Groups Signing Users Out Best PracticesHelpjuice allows organizations to authenticate users using JSON Web Tokens (JWT). JWT-based SSO provides a lightweight and secure way to integrate your existing authentication system with Helpjuice, enabling seamless access for your users.
In this article, you’ll learn:
- How JWT authentication works with Helpjuice
- How to configure Helpjuice to accept JWTs
- How to test your JWT SSO integration
- Best practices for using JWT-based SSO
Understanding JWT Authentication
JWT (JSON Web Token) is a compact, URL-safe token format that securely transmits information between parties and Helpjuice accepts a signed JWT containing user identity details to authenticate users.
The JWT must include specific claims such as:
- email – user’s email address (required)
- name – full name of the user (optional)
- role – role or permission level in Helpjuice (optional)
Here's how it works:
- The user chooses to authenticate through SSO.
- Helpjuice redirects the user to your website, where they authenticate with their username and password.
- Your website generates a JWT using the shared key provided by Helpjuice and redirects the user back to Helpjuice with the token.
- Helpjuice decodes the token and authenticates the user based on the email provided.
- If it's the user's first time signing in, Helpjuice will create a new Internal Viewer account for them.
Setting Up JWT SSO
To configure JWT SSO, follow these steps:
- Go to Account Settings > SSO (JWT).
- Fill in the required fields as shown below:
JWT Fields
When setting up JWT authentication, Helpjuice uses the following fields from your JSON Web Token:
| Field | Required? | Description |
|---|---|---|
| jti | Yes | A unique token ID generated by your website to prevent replay attacks. |
| iat | Yes | The token creation time in milliseconds since the Unix epoch. Tokens older than 3 minutes are rejected. |
| Yes | The authenticated user's email, which Helpjuice uses to 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 the user belongs to. These groups must exist in Helpjuice. If not provided, no groups are assigned. |
| role_id | No | Specifies the user's role. If not provided, the default role is Internal Viewer. Accepted values are: superadmin, admin, collaborator, draft_writer, and viewer. |
If the role_id or group_names values don't match existing roles or groups, the authentication will fail, and an error message will be shown.
Signing Users In
When Helpjuice redirects a user to your login page, it appends a service=helpjuice parameter to the URL, e.g., https://my.website.com/login?service=helpjuice. After successful authentication, generate the JWT and redirect the user back to Helpjuice using the format:
https://helpjuice.com/jwt/YOUR_SUBDOMAIN?jwt=YOUR_ENCODED_TOKENRedirection After Sign-In
If the user was trying to access a specific page before authentication, Helpjuice appends a fallback_url parameter to the URL, such as:
https://my.website.com/login?service=helpjuice&fallback_url=https://yourdomain.helpjuice.com/article-urlYou should include this fallback_url when redirecting the user back to Helpjuice:
https://helpjuice.com/jwt/YOUR_SUBDOMAIN?jwt=YOUR_ENCODED_TOKEN&fallback_url=https://yourdomain.helpjuice.com/article-urlIf the fallback_url parameter isn't provided, Helpjuice will attempt to use session cookie values or the behavior specified in the User Behavior & Tracking settings.
Syncing Role and Groups
The user's role and groups specified in the JWT are only used during user creation by default. To sync these values on every login, enable the Sync Role and Sync Groups options in the JWT SSO settings:
If the group_names field in the token is present and is set to an empty string, the user will be removed from all of their groups in Helpjuice. To leave groups unchanged, simply omit the group_names field from the token.
Signing Users Out
After signing a user out, Helpjuice will redirect them to the Logout URL you provided (if present).
For further debugging, you can use https://jwt.io to parse and validate your token structure.
Best Practices
- Always test JWT SSO with a small set of users before rolling out organization-wide.
- Use a strong secret or RSA key pair to sign your JWTs.
- Map all required claims accurately to prevent login errors.
- Monitor authentication logs in Helpjuice to detect potential issues.