Authenticating Chat Users

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.
   • 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: Integer value of the current 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.