Using restricted Help Center content with the Web Widget Follow

all plans

You can configure your Web Widget to embed content from a restricted Help Center (one that requires users to sign in for access), or restricted knowledge base content (a public Help Center with certain articles or sections restricted to signed-in users only).

When you configure the Web Widget to include restricted content:

  • Visitors to your website who are logged in can read the restricted Help Center articles via the Web Widget.
  • Visitors who are not logged in, however, see only public articles. If there are no public articles, the Help Center features do not appear in the Web Widget.

This article includes the following topics:

Note: You do not need to have a single sign-on (SSO) connection between your site and your Help Center to take advantage of this feature. However, having SSO will provide a more seamless experience, for those users who want to “View Original Article” from the Web Widget. Please note that even if you already have SSO you will need to configure your Web Widget so that you can benefit from this feature.

For more information on the Web Widget, see Using Web Widget to embed customer service in your website.

For information on restricted Help Centers and knowledge base content, see Restricting your content to logged in users only, and Restricting access to knowledge base content.

Determining your Help Center security settings

The Web Widget allows you to display content from a Help Center with any of the following security configurations:

  • A public Help Center, where all content is available to the public.
  • A restricted Help Center, where users are required to sign-in to view content.
  • A public Help Center with restricted content, where some articles and sections are only available to signed-in users.

To check your Help Center security settings

  1. In the Help Center, select General in the top menu bar, then select Help Center settings.

  2. Scroll down to the Security section. If the Require sign in option is selected, your Help Center is restricted.

    To include content from this Help Center in the Web Widget, follow the steps described in Setting up the Web Widget to show restricted content.

If you do not have a restricted Help Center, you may still need to determine whether a specific section is restricted.

To check security settings on a Help Center section

  1. Navigate to the section in the Help Center that you want to check.
  2. Click Edit section in the top menu bar.
  3. In the section's sidebar on the right, scroll down to the Who can view drop-down menu:

    • Anyone means the section is not restricted.
    • Signed-in users means the section is restricted.
    • Agents and managers means the section is restricted.

    If Signed-in users or Agents and managers is selected, and you want to include content from the section in the Web Widget, follow the steps described in Setting up the Web Widget to show restricted content.

Setting up the Web Widget to show restricted content

If you determine that you have restricted content you want to include in the Web Widget, you need to configure the Web Widget settings, and insert additional snippets into your website's code.

To get started, you need to check your Widget settings, and generate a shared secret.

To check your settings and generate a shared secret

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Customization tab.
  3. Scroll down to Help Center. Make sure the setting is toggled on, and that security is set to Require sign in (as described in Determining your Help Center security settings).
  4. Find the Security Settings section.
  5. Add Whitelisted Domains.

    You can restrict the use of your Web Widget by entering the domains that contain the Web Widget into the Whitelist. For your security, we recommend adding domains to the whitelist. If you have specific reasons why restricting access to particular domains will not work, you may leave this box empty. See Using the whitelist and blacklist to control access to your Zendesk for information on using whitelists.

  6. Check the Allow agents to access restricted Help Center content... box to allow restricted Help Center content to appear when agents and admins access the Web Widget. If you have a restricted Help Center and agent access is not enabled, the Help Center features will not be displayed in the Web Widget for agents and admins. If you have restricted content and agent access is not enabled, agents will only encounter the public content.
  7. Configure Shared Secret:
    • Create a shared secret by clicking the Generate button:

      Because it is a security setting, your shared secret is intended to be generated, copied and pasted into a communication with your engineering team or directly into your codebase in one sitting. It is not to be entered into a browser.

    • Once you create a shared secret, return to the Admin page. The shared secret will be truncated for your security:

      Note: The shared secret is intended to remain secure. As a result, it will only appear in full one time. If you don’t have access to the shared secret and need the full secret to create your token, you can reset the secret by clicking Reset.
    • If you believe that your shared secret has been compromised, after you reset your shared secret you can revoke all tokens. This will invalidate the access of anyone that had authenticated previously and will not allow restricted content to be viewed until a newvalid token has been issued.

Once you have generated the shared secret, use it create a JWT token (Learn more about JWT) that you'll add to your Web Widget snippet.

To create a JWT token and add the code to the Web Widget snippet

  1. Construct a server-side payload of data for the JWT token. This needs to have the following information:
    • name: Customer's name
    • email: Customer's email
    • iat: Integer value of the current timestamp, in seconds. Some functions in specific languages i.e. JavaScript's Date.now() return milliseconds, so please make sure you convert to seconds.

      Iat for Web Widget authentication permits up to two minutes clock skew. 

    • jti: Unique identifier for this token. Cannot be the same as any other jwt tokens already sent through. A random 64 bit number for example.
  2. Use the code samples below to find a template that fits your language needs.
  3. Set the token you created in the window.zESettings object (replacing the "YOUR_JWT_TOKEN"). Make sure to put this code before the Web Widget snippet:
    window.zESettings = {
     authenticate: { jwt: 'YOUR_JWT_TOKEN' }
    };

    Tokens expire after two hours. You can remove them from local storage sooner by adding the following API call when the user is logging out:

    zE(function() {
     zE.logout();
    });

Code samples

Your token needs to be dynamically generated from the server-side on page load. Find the template below that fits your language needs. Customize the sample as needed, making sure to replace the #{details} with your own information.

If none of these samples match your needs, JWT has a more extensive list of JWT libraries to explore.

Ruby

First, install ruby-jwt.

If you're using Rubygems:

gem install jwt

If you're using Bundler, add the following to your gem file:

gem 'jwt'

Next, generate a token using the shared secret:

require 'jwt'
payload = {
  :name => "#{customerName}",
  :email => "#{customerEmail}",
  :iat => timestamp,
  :jti => "#{uniqueId}"
}
token = JWT.encode payload, "#{yourSecret}"

NodeJS

Install jsonwebtoken:

npm install jsonwebtoken --save-dev

Then, generate a token using the shared secret:

var jwt = require('jsonwebtoken'); 
var payload = {
  name: '#{customerName}',
  email: '#{customerEmail}',
  iat: #{timestamp}, 
  jti: '#{uniqueId}'
};
var token = jwt.sign(payload, '#{yourSecret}');

Python

Install python-jose:

pip install python-jose

Generate a token using the shared secret:

from jose import jwt
var payload = {
  'name': '#{customerName}',
  'email': '#{customerEmail}',
  'iat': #{timestamp}, 
  'jti': '#{uniqueId}'
}
token = jwt.encode(payload, '#{yourSecret}'

PHP

Download PHP-JWT:

composer require firebase/php-jwt

Generate a token using the shared secret:

use \Firebase\JWT\JWT;
$payload = {
  'name' => '#{customerName}' ,
  'email' => '#{customerEmail}',
  'iat' => #{timestamp},
  'jti' => '#{uniqueId}'
};
$token = JWT::encode($payload, '#{yourSecret}');

Elixir

Add `json_web_token_ex` to your `mix.exs` file:

defp deps do
  [{:json_web_token, "~> 0.2"}]
end

Generate a token using the shared secret:

data = %{
  name: "#{customerName}",
  email: "#{customerEmail}",
  iat: "#{timestamp}",
  jti: "#{uniqueId}"
}
options = %{ key: "#{yourSecret}" }
jwt = JsonWebToken.sign data, options
Have more questions? Submit a request

Comments

  • 0

    This is amazing! Extremely helpful!!!

  • 0

    This is very helpful. Thanks!!

    However, we have a couple of questions and it would be great to get some clarity. We have a restricted Help Center (requires sign-in) and have followed all of the above instructions. The help content shows up in the web widget window in our platform.  However, when we click on "view original content" button, it opens a new page and still asks the user to sign-in.

    1. Are we missing something? Wasn't the updated widget with the shared secret snippet supposed to take care of this by authenticating the user from web widget, to see the content online?

    2. Will "Whitelisted Domains" setting help? We tried but it seemed not to.

    (apologies for the novice questions but what we are trying to do is not have a public Help Center but have our platform users access the help center from within the system via web widget)

  • 0

    Hi - any help regarding above comment? Thanks!

  • 0

    Hey Atif, 

    I'm going to move this into a ticket for you since we have to go through some account specific info with you to troubleshoot. I'll see you in the ticket shortly! 

    Edited by Eric Nelson
  • 0

    Hello,

     I have this implemented nicely on our companies platform however I seem to have an issue. I am working on re-authenticating a user on our platform while they stay logged in but your widget seems to not support this? The advice for removing the restricted article access authentication is to call zE.logout() but there is not the relevent zE.login() function to enable access. I am wondering if it is intended to only reset the window.zESettings with a new JWT token to reauthenticate? Note that this is only for a repeat authentication and not the initial one while also not logging out of our platform.

    Thank you.

  • 0

    Michael: I see you have a ticket for this so I'll reach out there for some additional details on what you are seeing. 

Please sign in to leave a comment.

Powered by Zendesk