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 💪

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)
• iat 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 https://your.domain.com. Domains should not have a trailing slash.

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 > Users > Access
2. Head to Single Sign On and find JWT
3. Click ⋮ More > Connect
4. Add the generated Secret Key to your application

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.

Redirecting Logged Out Users

When a user hasn't visited your site for a while they won't have a cookie set. You'll want to override the default HelpDocs login page with a redirect to your own app. Something like this in Settings > Code > Javascript should work:

<script type="text/javascript">
    (function() {
        // Parse query string parameters
        var qs = function (a) {
          if (a === '') return {};
          var b = {};
          for (var i = 0; i < a.length; i += 1) {
            var p = a[i].split('=', 2);
            if (p.length === 1) {
              b[p[0]] = '';
            } else {
              b[p[0]] = decodeURIComponent(p[1].replace(/\+/g, ' '));
            }
          }
          return b;
        }(window.location.search.substr(1).split('&'));

        if (window.location.pathname.indexOf('/login') === 0 && !qs.bypass) {
            var redirectUri = 'https://your-app.your-domain.com'; // Replace this with your login page URL
            if (typeof qs.forward === 'string') redirectUri += '?hd_url=' + qs.forward;
            return window.location.href = redirectUri;
        }
    })();
</script>

If you're a stickler for user experience, your developers can set up a redirect back to the correct HelpDocs article after login by extracting the hd_url query param.

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 > Users > Access.

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\":\"Taylor\"}", // optionally pass a JSON-encoded string of user data to decode on your docs later
}