Shared Password Protection

by Jarratt Isted

Whether you're using your HelpDocs internally to train staff, or just because they're not ready for the limelight yet, there's a load of reasons you might want to password protect your HelpDocs.

HelpDocs makes it super simple to add a shared password that visitors will need to enter before they get to your docs.

  1. Log in to HelpDocs at <your-subdomain>.helpdocs.io/app
  2. Go to SettingsGeneral
  3. Under Shared Password enter a password of your choice
  4. Hit Save
You'll need to share this password with your team, so be sure not to use anything sensitive to you

Now when people visit your site they'll need to enter a password before they can read any docs.

Using Team Passwords for Single Sign On

You can also send the team password through as an hd_team query parameter. e.g. your-domain.helpdocs.io/?hd_team=password to automatically log in users

If you're looking to set up docs that only users logged into your app can view, the team password works great. 

Dropping the Cookie

Just load HelpDocs in an iframe on your dashboard when people log in, including the team password in the query string. We have a special URL for you to use, where you can set a duration for users to stay logged in.

The basic URL structure is https://<your-helpdocs>.helpdocs.io/_hd/team_sso?hd_team=<your-team-password>

Here's a snippet to get you started:

<iframe src="https://<your-helpdocs>.helpdocs.io/_hd/team_sso?hd_team=<your-team-password>" width="0" height="0" style="display: none"></iframe>

There's also a few parameters you can customize:

Query ParameterDescriptionDefault Value
hd_team
Required
Your shared team password. If you want to log a user out, set this to an empty string (or just an incorrect password). undefined
duration
Optional
How long (in days) you'd like users with this cookie to be logged in for, without requiring a password.30
response_text
Optional
The text you'd like included in the response from this route. You usually won't need to set this.­čŹ¬
redirect_uri
Optional
Where to redirect the user to after dropping a cookie. If you're using this route in an iframe, there's usually no need to set this.undefined
If you use a custom domain, be sure to swap that in for your HelpDocs subdomain in the above URLs

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 team password login page with a redirect to your own app. Something like this in Settings > Code > Custom Scripts should work:

<script type="text/javascript">
    (function() {
        if (window.location.pathname.indexOf('/team-login') === 0) {
            
            // 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('&'));
            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.


How Did We Do?