TABLE OF CONTENTS

• Overview 
• Enforce user authentication
  • Step 1: Generate JWT Token
  • Step 2: Enforce JWT user authentication
  • Disable JWT authentication
• Generate a JWT token
• Embed the JWT token with Web Chat widget
• Agent experience
  
  

Overview 

When user authentication is enforced on Web Chat Widgets, JSON Web Token (JWT) authentication becomes mandatory for both authenticated and anonymous users. This ensures that every interaction, whether from a registered customer or a visitor, is securely validated through token verification. 

With JWT-based authentication, contact history is preserved across sessions. For example, if a customer starts a conversation via Web Chat today and returns the next day, their previous session and conversation context are automatically restored.

JWT User authentication workflow for Web Chat widgets

1. Conversation Initiation: A user clicks on a Web Chat widget to start a chat.
2. Token Request: Freshdesk requests a signed JWT token that includes user data.
3. Chat Initialization: Freshdesk initializes the chat session by passing the JWT token.
4. Token Verification: Freshdesk receives the user details from the JWT payload and grants the user access to the chat session.

Enforce user authentication

Note: If JWT user authentication is configured and enabled, it becomes mandatory for both visitors and identified users. This ensures that all interactions, whether from anonymous visitors or authenticated users, require secure token verification.

Step 1: Generate JWT Token

1. Log in to your account as an admin.
2. Go to Admin Settings > Channels > Web Chat > Widgets. 
3. Click Configure next to the widget for which you want to enable JWT authentication.
4. Click User authentication tab.
   
   
5. Generate Encryption key 
   • Click Generate Key to create a new encryption key. This is a one-time process.
   • Copy and save the encryption key as you'll need it to generate JWT tokens after enabling user authentication.
     Note: The generated key is valid and the same for all configured widgets in your account.

Step 2: Enforce JWT user authentication

When you enable JWT authentication, only authenticated users can initiate conversations via your Web Widget.

1. In the User authentication Settings section, select Enforce user authentication.
   
   
2.  A confirmation pop-up will appear. Click Enforce to confirm.
   
   

Disable JWT authentication

You can disable JWT authentication and allow both authenticated and anonymous customers to contact via Web Widget. 

1. In the User authentication Settings section, select Don't enforce user authentication.
2. In the pop-up that appears, click Disable.
   
3. Select the ticket fields and contact fields that can be modified even if JWT authentication is disabled.
   Note: These restrictions do not apply to AI Agents, and they can continue to update ticket fields and contact properties, even if these fields are included in this list.
   Note: If you add unique fields to this list, contacts that share the same unique value will be automatically merged. For example, if a customer with External ID = 1 contacts you via Web Chat and another customer with the same External ID = 1 also initiates a chat, both contact records will be merged into a single contact.
4. Click Save.

Generate a JWT token

JWT is an open standard (RFC 7519) URL-safe token used for securely transferring information between parties. For example, after enforcing user authentication, a JWT token will be required each time a user starts a conversation via Web Chat widgets.

Note:  You don't need to manually create JWT tokens. You can use one of the available JWT libraries in languages such as Node.js, Ruby, or Python. Alternatively, you can use jwt.io to generate tokens through a web-based form. However, it is recommended to avoid exposing JWT tokens to third-party sites.

If you are unsure about generating JWT tokens, contact your Engineering or Support teams for assistance.

Components of a JWT Token

A JWT comprises the three main parts:

• Header
• Payload
• Signature

Header

Specifies the type of token and the signing algorithm used. It includes two fields:

alg: The algorithm used to sign the token. For example, HS256 for Freshdesk.

typ: The type of token, which is JWT.

Example:

{
  "alg": "HS256",
  "typ": "JWT"
}

{
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+1234567890",
  "exp": 1716239022,
  "reference_id": "ref-123456",
  "freshcat_uuid": "uuid-123456-abcdef"
}

• first_name (Optional): The user's first name (e.g., "John"), used to include user-specific information in the payload.
• last_name(Optional): The user's last name (e.g., "Doe"), also used for user identification.
• phone_number (Optional): Stores the user's phone number (e.g., "+1234567890"), which can be used for contact purposes or to facilitate user identification.
• exp (Optional): Defines the expiration time of the token, represented as a Unix timestamp (e.g., 1716239022). This timestamp limits the validity period of the JWT, enhancing security by enforcing timely token renewal.
• Reference_id (Required): A unique identifier for the user within your system (e.g., "ref-123456"). This ID is essential for recognizing and tracking the user accurately across platforms.
• freshcat_uuid (Required): A unique identifier for a user or session in the application's context (e.g., "uuid-123456-abcdef"). Used internally to differentiate between distinct entities or sessions, enabling precise user management and tracking.

Signature

Ensures the token is not altered. It is created by combining the encoded header, payload, and a shared secret using the specified algorithm. You can find your account's shared secret under the User Authentication tab.

The final JWT token is created by combining the encoded header, payload, and signature, concatenated with periods (.).

JWT token = header.payload.signature

Embed the JWT token with Web Chat widget

Once you have enforced JWT user authentication, embed the following script to launch the Web Chat widget with JWT authentication.

<script>
function initFreshdesk() {
  window.fdWidget.init({
    host: 'your_host_here',
    token: 'your_token_here',
    widgetId: 'your_widget_id_here',
    jwtAuthToken: 'yout_jwt_token_here'
  });
}


function initialize(i,t){var e;i.getElementById(t)?initFreshdesk():((e=i.createElement("script")).id=t,e.async=!0,e.src="your_host_here/webchat/js/widget.js",e.onload=initFreshdesk,i.head.appendChild(e))}function initiateCall(){initialize(document,"Freshdesk-js-sdk")}window.addEventListener?window.addEventListener("load",initiateCall,!1):window.attachEvent("load",initiateCall,!1);
</script>

Agent experience

If JWT user authentication is enabled, the customer contact will be shown as authenticated in the Conversation Inbox. For users with expired authentication, a cross mark will appear in the inbox.

This ensures secure and up-to-date interactions between users and agents.

Authenticated user

Non-authenticated user