HelpSite Support Center

Contact Us
  1. Support
  2. General
  3. Private site authentication with JWT for SSO

Private site authentication with JWT for SSO

One of the options for private knowledge base authentication is SSO (Single Sign On) via JWT (JSON Web Token), if you have a web application where users already login via other means.

Unlike our "Shared Password / Secret Link" option, this JWT authentication method requires a bit of coding on your site, however it provides better security since each user is authenticated with a unique individual token that can also expire as quickly as you'd like.

Users that you invite from the Team page will have access to your knowledge base if they login to their HelpSite account directly. You'll still need to use the Invite by Email method for Admins and Content Editors. However you can authenticate Read-Only users using this JWT method without first inviting those users in HelpSite or requiring them to create a password.

Please get in touch if you have any questions or issues using JWT authentication with HelpSite!

Enabling JWT authentication for your site

To get started with requiring JSON Web Tokens for authenticating your users, go to Customize > Privacy. Choose the "Requires a JWT" option and click "Save".

After clicking Save, scroll down and you'll be presented with the Secret Key (used in the code on your server, explained below) and an optional Login URL field. 

If you provide a Login URL, HelpSite will redirect users there if they visit your knowledge base with a missing, invalid, or expired JWT.

Here's a sample (but the key shown here won't work for you).


Generate a JWT

Use jwt.io to learn about JSON Web Tokens, to help debug your implementation, and to find a library for your server-side programming language that you can use to generate the JWT.

Here are the fields that your JWT must have:

{
  "iat": 1516239022,
  "exp": 9999999999,
  "aud": ["yoursubdomain"]
}

Payload fields:

Other important notes:

Using a JWT

There are a couple options for how to pass the JWT to HelpSite to authenticate your users.

Pass via query string

You can pass the token via a jwt query string parameter, for example by linking users to your help site's URL.

If you're using a Custom Domain, that would look like:

https://help.yourcompany.com/?jwt=YOUR_JWT_HERE

Or if you're just using a subdomain, that would look like:

https://yoursubdomain.helpsite.com/?jwt=YOUR_JWT_HERE

Notes:

Set JWT in a cookie yourself

Alternatively, if you use a Custom Domain, you can set the JWT as the value of a cookie on your own domain and HelpSite can read it automatically without it needing to be passed via query string.

The cookie should have these characteristics:

Resetting a JWT Secret

If you ever need to reset your JWT Secret (which will immediately cause existing JWT tokens to become invalid) then:

  1. Go to Customizations > Privacy, change the setting to "Visible to invited users only" (or any other setting besides JWT), and save the form. This will invalidate the existing JWT secret key. 
  2. Then, choose the JWT option and save the form yet again. This will cause a new secret key to be generated and displayed.

Login URL

For knowledge base sites configured to use JWT authentication, you can provide us a Login URL that your users will be redirected to if they visit your knowledge base with a missing, invalid, or expired JWT. This helps provide a seamless experience for your users.

When HelpSite redirects users to your Login URL, we will append a query string parameter called jwt_error that will indicate the reason for the redirect. Values include:

Additionally, we'll include query string parameters expected_aud and from_url to help provide more context on what the user was attempting to access, and provide you the opportunity to redirect the user back to the same URL after authenticating.

If you have any trouble with JWT authentication on HelpSite, please get in touch!