Restricted Docs

Overview

Sites can be restricted so only visitors you think should get access can see the site. This enables the information on a site to be hidden from everyone unless they are allowed to see it.

The way we do this is to give you control over the authentication flow of visitors to the site. Whenever a visitor wants to access a restricted site, we will ask you if they are allowed to do so.

We currently offer one type of authentication flow: a custom callback authentication flow.

Custom Callback

Authenticating visitors using a custom callback requires you to implement an endpoint on your servers that can retrieve a browser redirect, authenticate the visitor, and redirect back to the site with proof of authentication.

The proof is a signed JSON Web Token (JWT) which holds information about the authenticated user and the signature is the proof that it really is your authentication endpoint that has issued the token.

Configuring a restricted site only requires a sign-in URL, which is the endpoint you have implemented to handle the authentication.

Overall authentication flow

The diagram below shows the overall steps in the authentication flow.

The authentication flow works like this:

1. In a browser, a visitor tries to access the restricted Docs site, which checks if the visitor is already authenticated with a valid token.
2. If the visitor isn’t authenticated, we send a 302 Found redirect back to their browser with the Location header set to the sign-in URL you provide during setup and a returnTo query parameter with a relative path to the page the visitor was trying to access.
3. The browser redirects the visitor to the sign-in URL (your authentication endpoint using a GET request). It is now up to your endpoint to authenticate. We have provided some examples of this here.
4. After the visitor has been authenticated, you will create a signed JSON Web Token and construct a URL that includes these three elements:
   1. The auth callback endpoint on the Docs site
   2. The signed JWT in the token query param
   3. The returnTo query param we included in step 2
5. The browser will redirect the visitor to the constructed URL in step 4 and the Docs site will read and verify the token query param, give the visitor access to your Docs site, and redirect the visitor to the path from the returnTo parameter.

Setting up site restrictions using the Docs API

Once you have an authentication endpoint and you are ready to restrict your Docs site, you can use the Docs API to enable the site restrictions.

Before invoking the Docs API, you need to configure your authentication using an API Key.

There are two endpoints to work with site restrictions:

• Get Site Restrictions
• Update Site Restrictions

To enable site restrictions, call the Update Site Restrictions endpoint like this:

PUT /v1/sites/[SITE_ID]/restricted
Authorization: Basic [AUTHENTICATION]
Content-Type: application/json

{
  "enabled": true,
  "authentication": "CALLBACK",
  "callbackConfiguration": {
    "signInUrl": "[YOUR_AUTHENTICATION_ENDPOINT]"
  }
}

Replace [SITE_ID] with the ID of the site you want to restrict.

The response to the request above will look like this:

HTTP/1.1 200 OK

{
  "enabled": true,
  "authentication": "CALLBACK",
  "callbackConfiguration": {
    "signInUrl": "[YOUR_AUTHENTICATION_ENDPOINT]",
    "sharedSecret": "[SHARED_SECRET]"
  }
}

The [SHARED_SECRET] contains the secret that you should use to sign the JSON Web Token.

Your Docs site is now restricted and visitors must go through your authentication endpoint to access your site.

Removing site restrictions using Docs API

If you want to disable site restrictions on a site, you can do this using the Update Site Restrictions endpoint:

PUT /v1/sites/[SITE_ID]/restricted
Authorization: Basic [AUTHENTICATION]
Content-Type: application/json

{
  "enabled": false
}

The response to the request above will look like this:

HTTP/1.1 200 OK

{
  "enabled": false
}

Your site will now be publicly available for all site visitors.

JSON Web Token

JSON Web Tokens (or JWT) is a standard for sharing proof of claims between two parties. We use them to help you tell us that the authenticated visitor really is who they say they are.

To learn more about JSON Web Tokens, the website jwt.io has a lot of good information as well as links to libraries for all major programming languages. You can also use the online tool to verify your tokens for validity while developing the integration.

We recommend that the following claims be present in the token:

To sign the token, you should use the shared secret provided when you configured the site restriction. We use the HS512 algorithm for generating and verifying signatures.

Implementing the authentication endpoint

You have full control over how you want to authenticate the visitors for your site. When we redirect to you, you determine the URL and invoke it with a GET request. You can show a login screen or directly exchange an existing authentication token to the JWT token required to authenticate on the Docs site. We have some examples flows for reference.

There are two query parameters that we append to the URL you provide:

Redirecting to the auth callback endpoint on the Docs site

When you have authenticated the visitor and created a signed JSON Web Token, you need to redirect the visitor back to the Docs site. The URL should follow this pattern:

https://example1.helpscoutdocs.com/authcallback?token=JWT_TOKEN&returnTo=RETURN_TO

In the URL above, example1.helpscoutdocs.com is your Docs site’s domain. If you aren’t sure of your URL, you can find that under Manage > Docs in your Help Scout account.

Replace JWT_TOKEN with the signed token you just have created and RETURN_TO with the value from the query parameter we sent you.

A note on testing the integration as a Help Scout user

When previewing a restricted Docs site directly from your Help Scout dashboard, please be aware that your Help Scout user authentication will take precedence over the custom callback authentication flow. This means that as a logged-in Help Scout user, you will be able to access the site without going through the custom callback authentication process.

If you wish to test the custom callback authentication flow as a regular visitor would experience it, there are two methods you can employ:

1. Use a Different Browser: Open a separate web browser where you are not logged in to your Help Scout account. This will allow you to navigate to the restricted Docs site as a regular visitor and trigger the authentication flow.
2. Use Incognito or Private Browsing Mode: If you do not want to use a different browser, you can open a new incognito or private browsing window in your current browser. These modes will not share cookies with your regular browser windows, thus effectively allowing you to browse the site without being recognized as a logged-in Help Scout user.

Remember to ensure that the site restrictions are enabled on the Docs site you’re testing by following the provided steps above. And always keep in mind that your Help Scout user authentication will override the custom callback authentication flow if you are testing from a Help Scout logged-in session. By using these testing methods, you can accurately evaluate your visitor’s experience and make any necessary adjustments to your authentication process.