You can configure your Web Widget (Classic) 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 articles that are restricted to specific users).
When you configure Web Widget (Classic) to include restricted content:
- Visitors to your website who are logged in can read the restricted help center articles via Web Widget (Classic). Note that the customer site in which the widget is embedded is responsible for authentication of a users email.
- 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 Web Widget (Classic).
This article includes the following topics:
For more information on Web Widget (Classic), see Using Web Widget (Classic) 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 (Classic) allows you to display content from a help center with any of the following security configurations. You may need to enable or disable the Require sign in option in your help center security settings, in Guide, based on your type of help center.
Type of help center | Enable "Require sign in"? |
---|---|
A public help center, where all content is available to the public. | Don't enable Require sign in. |
A restricted help center, where users must be registered and signed in to view any content. | Enable Require sign in. |
A public help center with restricted content, where some articles are only available to specific users, and others are available to all help center visitors. | Don't enable Require sign in. Everyone can see the unrestricted articles in your help center without logging in. However, only signed-in users with the correct permissions can see the restricted articles. |
To check your help center security settings
- In Guide, click the Settings icon (
) in the sidebar.
- In the Security section, enable or disable the Require sign in option, if
needed, based on your type of help center.
- If you have a restricted help center or a public help center with restricted content, proceed to Setting up Web Widget (Classic) to show restricted content.
Setting up Web Widget (Classic) to show restricted content
If you have a restricted help center or a public help center with restricted content that means you have restricted articles (see Determining your help center security settings). If you want restricted articles to appear in Web Widget (Classic), you need to configure your Web Widget (Classic) settings and add additional snippets to your website's code.
If you have a public help center, this task doesn't apply to you.
To get started, you need to check your Web Widget (Classic) settings and generate a shared secret.
To check your settings and generate a shared secret
- In Admin Center, click
Channels in the sidebar, then select Classic > Web Widget.
- Click the Basics tab.
- Make sure that the Help Center checkbox is selected.
If you haven't already, go to your Guide settings and enable or disable the Require sign in option, based on your type of help center (see Determining your help center security settings).
- Click the Security tab.
- In the Allowlist box, enter the subdomains that contain Web
Widget (Classic). This allows restricted help center content to display in the widget
for authenticated users.
For your security, we recommend adding subdomains to the allowlist. If you have specific reasons why restricting access to particular subdomains will not work, you may leave this box empty. Use spaces to separate subdomains.
- Select Allow agents to access restricted help center content
to allow restricted help center content to appear when agents and admins access Web
Widget (Classic).
If you have a restricted help center and agent access is not enabled, the help center features will not display in Web Widget (Classic) for agents and admins. If you have restricted articles and agent access is not enabled, agents will only encounter the public content.
- 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.
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 existing tokens. This will invalidate the access of anyone that had authenticated previously and will not allow restricted content to be viewed until a new valid token has been issued.
- Create a shared secret by clicking the Generate button:
Once you have generated the shared secret, use it to create a JWT token (Learn more about JWT) that you'll add to your Web Widget (Classic) snippet.
To create a JWT token and add the code to Web Widget (Classic) snippet
- 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.
- Specify HS256 as the JWT algorithm in the header of your JWT
payload:
{ "typ":"JWT", "alg":"HS256" }
HS256 stands for HMAC SHA 256, a 256-bit encryption algorithm designed by the U.S. National Security Agency.
Note: Zendesk does not support the RS256 and ES256 JWT algorithms. - Use the code samples below to find a template that fits your language needs.
- Add a function which fetches your JWT from your server, and makes a callback with the
JWT value. Replace "YOUR_JWT_TOKEN" with the token you created. Make sure to put this
code before the Web Widget (Classic) snippet:
<script type="text/javascript"> window.zESettings = { webWidget: { authenticate: { jwtFn: function(callback) { callback('YOUR_JWT_TOKEN'); } } } }; </script>
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:
<script type="text/javascript"> zE(function() { zE.logout(); }); </script>
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
32 comments
Robert Dahlborg
Hi. Trying to understand how to use jwt tokens with the web widget. Do I need one jwt for each integration(support,guide,chat) signed with 3 different keys?
Robert
0
Miranda Burford
Hi @...,
>Hi. Trying to understand how to use jwt tokens with the web widget. Do I need one jwt for each >integration(support,guide,chat) signed with 3 different keys?
Yes, that's correct. You'll need one JWT for each integration with 3 different keys. We're hoping to simplify this in the future.
- Miranda.
0
Robert Dahlborg
Hi Miranda,
Thank you for the answer. May I suggest that you implement support for JWT signing using the HS256 algorithm which is an asymmetric algorithm? This would be super easy for you to implement and the same token can be used across all your api's. It would also eliminate the need to create a purpose built service for zendesk tokens, i.e. one could use an external identity provider without having to exchange jwt tokens.
Regards
Robert
1
Arno (EMEA Partner)
User segments are not discussed in this article, and does someone know or even has experience about this: if customer user is authenticated with SSO, does widget then automatically limit/allow the KB content according to the user segments of the user in question?
0
Anna Roussanova
Hi Sovellin, yes, if the user is authenticated into the widget as described in this article, they will see the articles appropriate to their user segment.
0
Miranda Burford
Hi @...,
Thanks for your feedback on this. Much appreciated! I've passed this suggestion onto the team to consider in the future.
- Miranda.
0
Kornelia Szabo
Hi Tech Support,
I would be also very interested in this: https://support.zendesk.com/hc/en-us/articles/222874768/comments/360000717727
Namely how to do the setup for the allow list so local development is also possible?
2
Noe Landaverde
Hi,
I've been trying to make this work to no avail. My subdomain and even localhost are already whitelisted, made my subdomain run locally by adding it to my machine's hosts file but still the content is not loading. This is also true when running my app on localhost. Do I really have to deploy this code to be able to test it?
1
Miranda Burford
HI @...,
In order to test this in your development environment, you should be able to specify
localhost
or127.0.0.1
as a valid domain in the allow list. Please give that a try (should also work with Help Center articles) and let us know how you go.Thanks,
- Miranda.
0
Gabriele Biella
Hi,
I created the jwt token as described but I get this error:
{
"success": false,
"error": "failed to validate claims"
}
an example of JWT content is:
{
"name": "myemail@email.com",
"email": "myemail@email.com",
"iat": 1635258312,
"external_id": "9763877",
"exp": 1635258612
}
0
Miranda Burford
Hi Gabriele Biella,
I'll create a ticket so we can collect some more information from you and continue the conversation in there.
- Miranda.
0
Sanju Sathiyamoorthy
Seen below is my code used to try and implement the authentication for the widget. The console is being logged to so I know the function is being called, the jwt is valid and I am not getting any errors - but still I am not getting authenticated. The widget is the support widget in which zendesk articles can be searched for. Is this the correct set up?
Could you provide a working js example of the code showing how the callback function is used?
1
Tipene Hughes
Hi Sanju,
A couple things I’d suggest trying here:
1. Fetch the JWT within the context of the zESettings object e.g:
2. Double check that the Allowlist contains the domains that contain the Web Widget.
Let me know how this goes, and feel free to reach out with any questions.
Tipene
0
Chandra Iyer
hi
I managed to get to the first step of the webchat getting authenticated using
1) the function
The user is authenticated and I can verify this 1) 200 Token Response from the api --> https://id.zopim.com/authenticated/web/jwt 2) by seeing that the name and email are not editable in the chat box and 3) seeing messages come through the Live Chat.
My problems:
a) Help Center Setting does not require user sign in but user needs to be authenticated to view Restricted content.
b) The Zendesk token from my above does not still give access to the Restricted help center content.
Is there another step?
1) Do we need to call the code block on this page separately using the secret from https://{mydomian}.zendesk.com/admin/channels/classic/widget/ Security settings ?
1a) Do we need to separately also call the Help Center reauthenticate function separately as referenced here --> https://developer.zendesk.com/api-reference/widget/settings/#authenticate ?
2) If we use this Help center content code block what happens to my existing code block for chat authentication ? Can both of them co exist?
Sorry. I am finding the multitude of secrets and code blocks difficult to navigate.
Any help would be appreciated !
Regards
0
Susan Reed
We are having a real difficult time trying to get the search field in the Zendesk Help button to generate content from our restricted Help Center articles as well. We have completed the steps outlined in this article with no improvement. We have outreached to Zendesk support and their guidance has also provided no results.
Our Help Center articles are only available for our registered clients and thus restricted. We've been told by Zendesk support that the Search will render if we remove the content restriction but this goes against our company policy.
We really need to speak with a specialist who can help analysis and help resolve this issue for us which we've been working on without success for months. Thank you for your help!
0
Everett Cavazos
I noticed the instructions indicate:
"Construct a server-side payload of data for the JWT token. This needs to have the following information:
"
Is this the customer's name and email? We have 100s of customers with 1000s of employees that are going to be accessing our help desk. Do we have to do this for each one?
0
Bobby Koch
We are having the same issue that Susan Reed is having while trying to integrate into Pendo. Can someone from Zendesk say if there is an issue, or Susan, did you ever figure out what was going wrong?
0
Susan Reed
Bobby Koch We have not yet solved this issue despite many emails and calls with Zendesk support. However we are currently developing the most promising solution presented by a senior Zendesk support person and we will post a comment in about a month with our results.
0
Drew Roy
Bobby Koch Susan Reed -- We're unable to get the Zendesk Help Center (with restricited content) to render within the Pendo module. Is this the same issue that you all are experiencing?
0
Bobby Koch
We can get the unrestricted content to show, but not the restricted content Drew Roy
1
Drew Roy
Thanks Bobby Koch -- I'll follow along this thread to see if anyone can get it resolved. In the interim, I'm going to reach out to my Pendo rep to see if they have any customers who have found success with this implementation. I'll report back if I have any good news.
0
Bobby Koch
Awesome thanks Drew Roy! Same here, although, our Pendo rep just keeps pointing us to this article. I assume you are hitting the same issue that we are?
0
Drew Roy
Bobby Koch -- Yes. All of our content is restricted though -- so for us, it's completely failing :(. Whenever we select the Knowledge Base in the Pendo Resource Center. The Resource Center completely disappears. To fix it, we need to go in and remove the KB module in the Resource Center in Pendo and re-add (then re-push). Right now we are just in a staging environment -- but that's obviously not an acceptable outcome in Prod.
0
Susan Reed
Bobby Koch Drew Roy For the record, we are not trying to integrate with Pendo. We are only trying to get the Zendesk Help widget search engine to render results for our restricted content in the Zendesk Knowledge Base, which should not be this difficult considering it's the same platform. Only one unrestricted article does render results in the search tool. We are trying to implement the steps in the following article next to see if that works, after months of effort:
https://support.zendesk.com/hc/en-us/articles/4408838925082-Enabling-authenticated-visitors-in-Web-Widget-Classic-
0
Drew Roy
Susan Reed -- thanks for the clarifier. The Pendo Resource Center integration leverages the Zendesk Web Widget (Classic). So, while the use-cases are different, I think the issue is nearly the same.
Cc: Bobby Koch
0
Michael Unnone
Reading through this feature and had a question.
Does SSO have to be implemented for a web widget user to view restricted content ? The note in the article says you don't have to have SSO implemented to use this feature. Would the user be manually required to log into Zendesk to view the article from the web widget ?
0
Jupete Manitas
Hi Michael, thanks for writing in!
The SSO is optional depending on your setup and you can use this feature without SSO. Users are required to sign in to view restricted content depending on the Help Center security settings as mentioned above. If require sign in is enabled then they need to sign in. If the Help center is public with restricted content, the widget will only display the public articles while restricted are not. Users need to manually sign in to view them. Thank you!
0
Susan Reed
Jupete Manitas we have been trying to months, following advice from this article as well as Zendesk support, to get SSO to allow our users to view restricted content in our Help Center via Search in the Help widget, without avail. This article gives the impression that SSO is the bridge which will enable the restricted content to render Search results in the Help widget. Are you saying this will never work? That even those users who are signed into our platform and through SSO they are also signed into our Help Center, the Search tool in the Help widget still will not render search results for restricted content? Why would that be?
0
Jupete Manitas
Hi Susan, good day! Sorry to hear about that trouble. The SSO is just another authentication in accessing your help center or site but restricting users to access content via the web widget will also need a separate configuration as described above. To have a restricted help center or a public help center with restricted articles that will show in your web widget. We hope this clarifies!
0
Matt Yorkgitis
Hi, is there an updated guide on how to implement this? In the docs it says this authentication method is deprecated.
Our implementation broke in the last week or so without us making any code changes and I've confirmed the JWT being sent to the ZD authentication endpoint meets the requirements of this guide.
Were some changes related to this deployed recently?
Thanks!
0