You can configure your widget to authenticate visitors on every page load using a new Javascript API and JWT token.
This article applies to customers using the following versions of Chat:
- Zendesk Chat Phase 3 (Chat-only)
If you are using any of the following versions, see Enabling authenticated visitors in the Web Widget:
- Zendesk Chat Phase 4 (Chat-only or with Support)
- Zendesk Chat Phase 3 with Support
For help identifying which version of Chat you're using, see Determining your Zendesk Chat account version.
This article includes the following topics:
Overview
When you configure the Chat widget to use authenticated visitors, you get the following benefits:
-
Ability to have higher confidence and security that the visitor/customer you or your agents are talking to is the real deal
-
Support for cross domain traffic. If you are embedding the widget on multiple domains or link to externally hosted services (ex. Shopify), authenticating the visitor will make it one visitor across the domains to the Chat platform which allows your agent to have more context
-
Support for cross device/browser identification. The visitor can be viewed as the same person if or when they choose to use a different device or browser when the custom ID is specified in the authentication call.
Generating a Chat shared secret
To configure your widget for visitor authentication, you need a shared secret. A shared secret is a security setting, intended to be generated, copied, and pasted into a communication with your engineering team, or directly into your codebase, in a single sitting. It should not be entered into a browser.
Only Chat administrators can configure visitor authentication settings.
To generate the shared secret required for authenticated visitors
- Open your Chat dashboard and go to Settings > Widget.
- Click the Widget Security tab.
- Scroll down to the Visitor Authentication section and click the Generate button.
Regenerating a new shared secret will revoke the previous token. If you have concerns the shared secret has been compromised, you should regenerate a new one. If you need to rotate the keys, you should schedule it when Chat is offline because regenerating the secret may cause visitors to be disconnected from the widget for 5 minutes.
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 snippet.
Creating a JWT token
To create a JWT token and add the code to the Chat standalone 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
- external_id: alphanumeric string, unique to identifying the customer. Once set for the customer, this value cannot be changed. We recommend that you use your system's unique user ID for this field. For example, user-123456. (Max length is 200 characters)
- 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 Chat authentication permits up to two minutes clock skew.
- exp: (optional) Integer value of the expiry timestamp, in seconds. This value indicates when this JWT token will expire. The value is permitted to be up to a maximum of 7 minutes from the iat value.
-
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.
-
Use the $zopim.livechat.authenticate Javascript API to provide a function which supplies a fresh JWT every time it is invoked. Below is a code example:
In the example above, JWT_TOKEN_ENDPOINT is an endpoint which can be implemented on your own server to obtain a fresh JWT.$zopim(function() { $zopim.livechat.authenticate({ jwtFn: function(callback) { fetch('JWT_TOKEN_ENDPOINT').then(function(res) { res.text().then(function(jwt) { callback(jwt); }); }); } }); });
Note: The jwtFn can be called multiple times throughout a chat session to obtain a new JWT in order to validate the visitor’s identity over the session’s lifetime. - You can use the $zopim.livechat.clearAll() API to log out the user from the widget when they log out of the host app/website.
For single-page apps, note that it is not possible to re-authenticate a visitor after the $zopim.livechat.clearAll() API is used. You would need to reload the page for the visitor to be authenticated again.
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,
:external_id => "#{externalId}"
}
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},
external_id: '#{externalId}'
};
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
payload = {
'name': '#{customerName}',
'email': '#{customerEmail}',
'iat': #{timestamp},
'external_id': '#{externalId}'
}
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},
'external_id' => '#{externalId}'
};
$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}",
external_id: "#{externalId}"
}
options = %{ key: "#{yourSecret}" }
jwt = JsonWebToken.sign data, options
About the agent experience with authenticated visitors
A few things are updated in the Chat dashboard when an agent starts chatting with an authenticated visitor.
First, the agent will be able to tell the visitor is authenticated by the green authenticated checkmark overlay on the visitor's avatar:
The agent will also notice that they cannot edit the visitor's name or email, since the source of truth comes from the information that is being sent via the Javascript API.
Finally, banning an authenticated visitor will mean the visitor cannot access the Chat widget across devices and browsers.
About the widget experience for authenticated visitors
Authenticated visitors will also have a slightly different experience in the Chat widget. First, their information is read-only and cannot be modified by them via the widget or through the Javascript APIs.
Second, ongoing chat sessions are synced across devices when the visitor is authenticated. This gives the visitor flexibility to switch computers/browsers and continue their ongoing chat session if, for example, they are moving between the Chat widgets on a desktop web browser and a mobile web browser.
Finally, the ability to have the chat in a popout is removed for authenticated visitors because there is no way to verify their identity via the popout (as the experience is hosted on our domain, zopim.com).
28 Comments
If implemented, how does that affect a chat visitor? Are they required to authenicate or is it just an option?
If you start authenticating visitors, the chat visitor will not need to do anything on their end. Their name and email will be set from your backend server.
Is it possible to implement this in Guide (Help center)?
Hi Nick,
It is possible but requires work and is not out of the box. You would need to create a public endpoint on a URL you own and whitelist the help center URL to get the JWT token. The other option would be to host the help center content yourself and rely on the Guide APIs.
-Ramin
Can you post an example of a properly encoded JWT and the secret used for the signature (feel free to make it the number 1 repeating)? I am fairly certain what I have set up is posting the correct format but the server's response. Also are the IAT and EXP claims expecting UTC or some other timezone that we are supposed to guess at? jwt.io event verified the signature, so I'm not sure where it is failing.
Hi Casey,
The IAT & EXP should be a unix timestamp which does not carry a timezone (The number of seconds since January 1, 1970 00:00 UTC)
Using your suggestion of '1111111111111111111111111111111111111111111111111111111111111111' as the secret, I have generated the following JWT:
eyJhbGciOiJIUzI1NiIsImN0eSI6IkpXVCJ9.eyJuYW1lIjoiU3VuZ2d1bCIsImVtYWlsIjoic3VuZ2d1bEB6ZW5kZXNrLmNvbSIsImlhdCI6MTUzNjI5MDcyMywiZXh0ZXJuYWxfaWQiOiJzdW5nZ3VsIiwicGhvbmUiOiIxMjM0NTY3ODkifQ.73Fd-WO-cJoXGu3DJrY16lArDVBudxGSMW6JqpfprCE
Which should decode as:
{
"name": "Sunggul",
"email": "sunggul@zendesk.com",
"iat": 1536290723,
"external_id": "sunggul",
"phone": "123456789"
}
Some possible reasons I can think of for your unsuccessful JWT authentications are:
1) Your server time might not be in sync, you could look at several public ntp providers to keep your clock in sync. (time.google.com is an option)
2) You are specifying iat/exp in a unit other than the second
Warmest regards,
Benjamin
Hmm... my payload looks like this:
{
"name": "First Last",
"email": "my@email.com",
"iat": 1536270946,
"external_id": "S3s2bJgyWP9BekE4Q3lNdGp5bzJLQT09",
"exp": 1536271306
}
Could it be that you are posting a phone number and only the first name and no exp?
Is the external id something that should exist somewhere in zendesk already?
Hi Casey,
To better address your query and maintain privacy on our communication I created a support ticket for you on Monday but have not heard back.
Please feel free to reply via email to the support ticket if you are still facing problems implementing authenticated visitors, so that I may be better able to assist you.
Warmest regards,
Benjamin
Where should I put this code? I can't get it works. Please help.
Hi there Hayya,
It should be added below the widget embed script on your website. If you need help with the process, please email chat@zendesk.com
-Ramin
Hi Ramin,
I did it, but is says $zopim is undefined, and when I did it after $zopim is loaded it says "Zendesk Chat: visitor authentication must be initiated immediately after embedding script"
Hi Hayya,
This is because you are using the Web Widget and not the Chat standalone widget.
Here are the instructions for the Web Widget: https://chat.zendesk.com/hc/en-us/articles/360001301627-Enabling-authenticated-visitors-in-the-Web-Widget
You will need to be in the EAP for the integrated chat experience first before you can use the APIs listed in that article.
-Ramin
I'm interested would that help if I want to prevent spam attacks? Currently, we suffer a lot of those as they target the chat widget on the Guide page. If we implement this, would that mean all chat visitors will be authenticated first (which will exclude the spammers)?
Hi Zornitsa,
Sorry to hear that you are experiencing high levels of spam on your help center.
Authenticating visitors would not reduce these spam messages but we have some things we can do to try and reduce the spam internally.
Please send the IP addresses of the spam messages and also the content of the message (if it is the same) to chat@zendesk.com
From there, our developers will investigate it further and see if there are things we can do to reduce the spam messages for you.
If they are coming from a country you are not supporting, you can also look at using the Country Blacklist setting in the Widget Security Settings section of the Chat dashboard.
-Ramin
Hi,
Hi Web ZMT,
Can you ensure that the secret you are using is the one from the Chat dashboard and not the Support one? Also ensure you are sending the iat value as an integer.
If you are still experiencing problems, please email chat@zendesk.com with your webpage with the code and the team will look into it further.
Thanks,
Ramin
Hi Ramin,
I've an error on my local machine while trying to authenticate loggedin user in zendesk.
Here is my node js server code:
I get this error in browser's console:
Zendesk Chat: failed to verify token: jwt verification error
I don't know what to do because I follow everything in your instruction above.
Thank you very much
Hi Ahmad,
Nothing looks wrong with your code. Is there a page we can look at to see the error ourselves? Alternatively, can you send us a HAR file so we can investigate it further.
Thanks,
Ramin
Hi,
I was able to have that working already, but, I was hopping to have a way of catching if any error occur during authentication, so I can use the setName and setEmail approach.
If that is possible it would be awesome, 'cause we don't want to block our users from using the chat if there was an error during authentication process, 'cause most of times that wouldn't be their fault.
Hi Franco,
Currently, there is no callback function for when an authentication attempt fails. There is an error in the browser console if/when it happens.
I have shared your feedback with the engineering team and we will let you if/when an enhancement to the widget would add such capability down the road. Currently, there is no plans for this to be addressed in the next 6 months but we will let you know if that changes.
Thanks,
Ramin
Hi team,
forgive me if this is a dumb question, but does this mean that we can display the chat widget only to users who have signed into our website? Or is it for forcing users to sign in with their credentials on our website in the pre-chat form?
Thanks folks! :)
Hi team
Is it possible to implement an unauthenticated chat version and an authenticated one at the same time? In other words, does the unauthenticated customer access by entering certain data, while the authenticated customer does not have to enter anything?
thanks!
Fabio
@Oliver It is more of the later, setting the visitor information in an authenticated manner. If you need to show/hide the widget, you will need to write custom code and use our JS APIs to do that. If you need help using the APIs, please email support@zendesk.com
@Fabio it is possible to have authenticated and not authenticated widgets on different domains. One thing to note, a non-authenticated visitor cannot have their details/chats transferred/continue after becoming authenticated.
Hi Ramin
But I could have authenticated and not authenticated on a single Zendesk instance, so on only one domain. This is not possible? Or, alternatively, is it possible to have only one Zendesk instance with two separate addresses? For example: zendesk1.abcd.it and zendesk2.abcd.it? Or how?
thanks
Fabio
Hi Fabio,
You can have authenticated and non-authenticated in the same account, you cannot have it on the same URL (as in a user cannot be authenticated and not authenticated at the same time).
If you have more questions, please email support@zendesk.com to get further assistance.
-Ramin
Try telling that to Shrödinger's cat :)
Hello,
I have a problem with fetch JWT_TOKEN_ENDPOINT. what is JWT_TOKEN_ENDPOINT format which we can pass in?
Help me soonest, Thanks
Hi Saopheng,
Please email support@zendesk.com to get assistance.
-Ramin
Please sign in to leave a comment.