JWT Custom authentication Tutorial

Introduction

The Tiledesk Web Widget provides a default anonymous identity to its users. The first time the widget starts on an end-user's browser it assigns a unique, random user-id that lasts until the browser cache is cleared. This temporary identity allows immediate installation and use of the widget on your website or application without configuration.

While anonymous authentication enables easy deployment, you may want to give end-users a persistent, recognizable identity—especially if they already have a certified identity from another Identity Provider. Tiledesk supports authenticating end-users with a custom, certified identity using custom JWT authentication.

This tutorial provides a complete example showing how to set up custom JWT authentication for your Web Widget end-users.

The tutorial's application

We developed a fully working application (client + server) deployed here:

https://tiledesk-html-site.tiledesk.repl.co/custom-authentication-example.html

Open the URL, interact with the embedded widget and start a new conversation (e.g., send "test"):

The conversation history is saved on Tiledesk servers per user-id and is visible in the widget's home. With anonymous users, opening the same page in a different browser creates a new anonymous user (history won’t be shared). With custom JWT authentication, the same authorized user can be recognized across different browsers and sessions—so conversation history is conserved:

Steps

To configure the frontend application you need:

a Tiledesk project (and its project id)
a backend authentication service URL (REST endpoint that returns the signed custom JWT token using your project secret)
a frontend application (a web page hosting the widget configured for custom auth)

Follow these steps:

Create a Tiledesk Project

In Tiledesk, click "Add project".
Choose a project name (e.g., "JWT Auth Tutorial") and press Create project. Leave options at default.

Your project is ready.

Setup the Backend Authentication App

You need a web endpoint that runs your authentication logic and replies with a Tiledesk-signed JWT. The tutorial uses Repl.it (Replit) to create a Node.js endpoint.

Fork the tutorial backend app:

https://replit.com/@tiledesk/tiledesk-jwt-token-example#index.js

In your Tiledesk project go to Settings > Project Settings > General and copy the Project id. Paste the project id into the index.js file of the Node.js app on Replit.

In your Tiledesk project go to Settings > Project Settings > Developer and generate a shared secret using "GENERATE SHARED SECRET". Note: generating a new secret invalidates the previous one—replace it wherever used.

Paste the secret key into the index.js file in your Replit app.

Run the Replit app. The authentication endpoint will be available (POST):

Authentication Endpoint: https://tiledesk-jwt-token-example.tiledesk.repl.co/auth

This endpoint simulates authenticating a user (e.g., checking credentials in a database) and returns a signed JWT using your project ID and secret.

Setup the Frontend

Fork or clone the frontend project:

https://replit.com/@tiledesk/Tiledesk-HTML-Site#custom-authentication-example.html

In the page source, set the widget's projectid property to your Project id.

In the widget authenticate method, set the authentication URL to your backend endpoint (service base url + /auth). Use the Replit service base URL from the side panel and append /auth.