Restricting your HelpDocs with Custom JWT SSO

Our docs are a great thing for your site's SEO and your brand. But sometimes, for whatever reason, you may want to restrict your HelpDocs to just users of your app.

Never fear. If you have a developer on your team, you can generate unique JSON Web Tokens (JWT) for each user on your server, then cookie them to your users' browsers. Only users you've issued a JWT will be able to view your docs, and only while that JWT is valid. 💪

Users you identify with JWT auth are excluded from your HelpDocs user limits, so you can happily use this for all your users

Creating the JWT

We only require your JWT to contain a few standard fields. Here's what we're expecting:

{
"exp": 1531713013,
"iat": 1531540153,
"aud": "https://your-domain.helpdocs.io" // or ["https://your-domain.helpdocs.io", ...]
}

We will reject your JWT if:

  • exp is in the past (i.e. the token has expired)
  • iss is in the future (i.e. the token has time traveled)
  • aud does not equal (if it's a string) or contain (if it's a string array) your HelpDocs subdomain in the format https://your-domain.helpdocs.io or your custom domain in the form your.domain.com

You can manage token expiry yourself by setting exp to a certain number of minutes or days in the future.

Signing the JWT

  1. In your HelpDocs dashboard head to Settings > Access Control (or click here)
  2. Click JWT, then Enable JWT Auth
  3. Add the generated Secret Key to your application
We recommend using your Secret Key as an environment variable, not hardcoding in your application code. That way it'll stay secret, the way it was intended.
NEVER use your secret key in client-side code. Anyone with this key can fool us into thinking they're acting on your behalf.

You can then sign your JWT with this key. We only support the HS256 signing algorithm.

If you lose control of your Secret Key, you can regenerate it at any time in the same place. You can also disable JWT auth completely.

Using the JWT to Identify a User to HelpDocs

Passing the JWT as a Query Parameter

You can send us the JWT on any page of your docs by hardcoding into the URL as the query parameter.

https://your-domain.helpdocs.io?hd_jwt=...

Be aware that this URL is easily shareable, and users could choose to share that link with people you didn't originally intend to access your docs.

Dropping the JWT as a Cookie

It's also possible, and preferable, to cookie the JWT directly to a user's browser. There's a few ways to do this.

  • If you're using a custom domain on your docs, you can set a first-party cookie on .yourdomain.com with name hd_jwt. Use the JWT string as the value. Set the expiry to the same time as the JWT itself.
  • Send the user to https://your-domain.helpdocs.io/login/jwt/token?hd_jwt=...&forward=..., where token is your JWT and forward is the path you'd like us to send the user after dropping the cookie.
  • Include an iframe in your logged in app pages that has a src of https://your-domain.helpdocs.io/login/jwt/token?hd_jwt=...

In options 2 and 3 we'll drop a cookie on that domain that expires at the same time as your JWT. They both work with your custom domain or HelpDocs subdomain.

Using the JWT as an API key

Certain routes in the API work with JWTs. These are:

  • GET /article
  • GET /article/:article_id
  • GET /category
  • GET /category/category_id

These keys will only allow the user to view articles they have access to. They're significantly more limited than regular API keys.

The JWT should be passed as a hd_jwt query parameter to one of the above routes.

Using JWT with Permission Groups

You can add permission groups to your JWTs to enable a user to see certain articles. The identifiers you'll need are available the same place you create and manage the group itself, in Settings > User Management.

Permissioning is available on the Growth plan and above

To assign groups, just add a permission_groups property to your JWT. It should be an array of strings, each string representing a user group. Remember to include the group: prefix.

{
"exp": 1531713013,
"iat": 1531540153,
"aud": "https://your-domain.helpdocs.io" // or ["https://your-domain.helpdocs.io", ...]
"permission_groups": ["group:a9fk3uc7293"], // allocate one or more permission groups (remember the `group:` prefix)
}

Passing User Data in the JWT

If you want to be able to later identify a user in your template or some custom code, you can pass arbitrary parameters to us in the JWT. Just send a JSON-encoded string in the user_data field of the JWT. We'll make this data available to your templates as a readable cookie.

{
"exp": 1531713013,
"iat": 1531540153,
"aud": "https://your-domain.helpdocs.io" // or ["https://your-domain.helpdocs.io", ...]
"user_data": "{\"name\":\"Jake\"}", // optionally pass a JSON-encoded string of user data to decode on your docs later
}
There's an article about decoding that metadata here here


What did you think of this doc?