Enabling authenticated visitors in the Chat widget

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
• Generating a Chat shared secret
• Creating a JWT token
• Code samples
• About the agent experience with authenticated visitors
• About the widget experience for authenticated visitors

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

1. Open your Chat dashboard and go to Settings > Widget.
2. Click the Widget Security tab.
3. Scroll down to the Visitor Authentication section and click the Generate button.

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 the 'Regenerate' 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

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
   • 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.

2. 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.
3. Use the code samples below to find a template that fits your language needs.

4. 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:

   $zopim(function() {
     $zopim.livechat.authenticate({
       jwtFn: function(callback) {
         fetch('JWT_TOKEN_ENDPOINT').then(function(res) {
           res.text().then(function(jwt) {
             callback(jwt);
           });
         });
       }
     });
   });

   In the example above, JWT_TOKEN_ENDPOINT is an endpoint which can be implemented on your own server to obtain a fresh 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.
5. 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
• NodeJS
• Python
• PHP
• Elixir

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. 

Note: Because the current Chat mobile SDKs do not support visitor authentication, visitors cannot continue a chat session when moving between the desktop widget and a mobile app using the Chat SDK.

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).