Tiledesk Developer Hub
WebsiteCommunityTutorialsGet started
  • Introduction
  • Community
  • Ask for Support
  • Public Roadmap and Changelog
  • Tutorials
  • Widget
    • Widget SDK
    • Javascript API: Methods
    • Javascript API: Attributes
    • Javascript API: Listeners/Events
    • Widget Authentication
    • Widget Angular integration
    • Widget React integration
    • Widget for Android with WebView
    • Widget for iOS with WKWebView
    • Widget for Flutter with WebView
    • Widget for React with WebView
    • Widget for Wix Website platform
    • Tutorials
      • Hide widget
      • Show/Hide widget programmatically
      • Force widget loading without user interaction
      • Mobile positioning
      • Custom size (width/height)
      • Installing widget on selected pages
    • Conversation Embedded Apps
      • Payment App Tutorial
      • Prechat form App Tutorial
    • Advanced
      • Preset the Widget on a specific Department
      • Authentication Flow
      • Widget protocol specs
      • Prechat Form JSON specs
      • Prevent multiple conversations
      • Old versions
        • Web SDK v4
  • External Chatbot
    • Introduction
    • Hello World tutorial
    • Chatbot to Human handoff
    • Send Text Buttons
    • Advanced Tutorials
      • Introduction
      • Tutorial 1 - Dialogflow as external chatbot
      • Tutorial 2 - Buttons and images
      • Tutorial 3 - Automatic human handoff with fallback intent
      • Tutorial 4 - Explicit Human handoff with user intent
      • Tutorial 5 - Gracefully handling operating hours during handoff
      • Generate Dialogflow Google Credentials file
    • Rasa tutorials
      • Rasa Tutorial 1 - Rasa as external chatbot
  • Resolution bot
    • Introduction
    • Quickstart
    • Webhook service
    • Rich messages
    • Tutorials
      • Chatbot chooser (multilanguage)
      • Department chooser
      • Order info (webhook)
  • APIs
    • REST APIs
      • Introduction
      • Authentication
      • Requests
      • Leads
      • Messages
      • Activities
      • Projects
      • Team
      • User
      • Analytics
      • Canned responses
      • Tags
      • Events
      • Jwt
      • Labels
      • Images
      • Files
      • Segments
      • Chatbots
      • Knowledge Bases
        • Knowledge Base
        • Contents
        • Question & Answer
      • Management Api
        • Departments
        • Groups
    • NodeJS SDK
    • Webhooks
      • Subscriptions
    • Conversation Messages APIs tips
    • Realtime API
    • JWT Authentication
      • JWT Custom authentication Tutorial
    • Tutorials
      • REST API
        • Sending and receiving messages with Tiledesk APIs
        • PHP Tiledesk REST API example
        • Import multiple messages into Tiledesk using REST APIs from third party app
      • Webhooks
        • Custom Request assignment
        • Request transcript on close
  • Apps
    • Build Custom App - Quick start
    • External Channels integration flow diagram
    • Telegram integration tutorial
  • Dashboard & AgentChat SDK
    • Dashboard SDK
    • Agent Chat SDK
  • Architecture
    • Architecture overview
    • Components list
    • Bot Design diagram
    • Multi Channel Message Flow
  • Installation
    • Installation
    • Running Tiledesk using Docker Compose
    • Running Tiledesk with Kubernetes using Helm
    • Choosing Hardware
  • Configuration
    • Chat21 channel configuration
    • Email parameters and templates configuration
    • Configure the logging system
Powered by GitBook
On this page
  • Custom Authentication
  • Generating a Project Shared Secret
  • Create a Tiledesk JWT token
  • Generate JWT Token Server Side
  • NodeJS
  • PHP
  • Java
  • Verify the token
  • Widget Authentication

Was this helpful?

  1. APIs

JWT Authentication

PreviousRealtime APINextJWT Custom authentication Tutorial

Last updated 1 year ago

Was this helpful?

Custom Authentication

The Custom JWT authentication provider allows users to authenticate with an authentication system that is independent from Tiledesk. The external system must return a signed that contains a unique ID value for the authenticated user.

Tiledesk uses the JWT to identify your application’s users and authenticate their requests but does not impose any restrictions on the external authentication system’s requirements or authentication methods.

To create a Custom JWT Token you must generate a Project Shared Secret as described below.

NOTE: We provide a .

Generating a Project Shared Secret

A Project 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.

To generate the shared secret required for custom authentication you need:

  • Open the Dashboard and go to Project Name > Project Settings.

  • Go to the Visitor Authentication tab 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 '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 cause visitors to be disconnected from the widget.

Create a Tiledesk JWT token

To create a JWT token you must set the following required fields of the user object :

  • _id is the custom unique user identifier of the external authentication system. It must start with <YOUR_PROJECT_ID>_ ( example: 5e5f4e220b28440012117be4_12345678 )

  • sub. JWTs describe their subject in the sub claim. For custom authentication sub field must be equal to value userexternal

  • aud. JWTs describe their audience in the aud claim. For custom authentication must be https://tiledesk.com/projects/<YOUR_PROJECT_ID> whether you use the cloud version of Tiledesk or if you install it on-premise.

  • email. It's the user email

Optional fields:

  • firstname. It's the user firstname

  • lastname. It's the user lastname

  • attributes other custom jwt claims.

The external authentication system must create the JWT signing the user object with the Project Shared Secret code.

User object example:

{"_id": "5e5f4e220b28440012117be4_12345678", "firstname":"Andrea", "lastname":"Leo", "email": "andrea.leo@email.com",  "attributes": {"attribute1":"value"}, "sub":  "userexternal",  "aud":  "https://tiledesk.com/projects/5c81593adf767b0017d1aa68"}

Generate JWT Token Server Side

Find the template below that fits your language needs. Customize the sample as needed, making sure to replace the #{details} with your own information.

NodeJS

npm install jsonwebtoken --save-dev

Then, generate a token using the shared secret:

var jwt = require('jsonwebtoken'); 
var payload = {
  _id: '#{customerIdentifier}',
  firstname: '#{customerFirstname}',
  lastname: '#{customerLastname}',
  email: '#{customerEmail}',  
  sub: 'userexternal',
  aud: 'https://tiledesk.com/projects/#{YOUR_PROJECT_ID}',  
};
var token = jwt.sign(payload, '#{yourProjectSharedSecret}');

PHP

composer require firebase/php-jwt

Generate a token using the shared secret:

$payload = {
  '_id' => '#{customerIdentifier}' ,
  'firstname' => '#{customerFirstname}',
  'lastname' => '#{customerLastname}',
  'email' => '#{customerEmail}',
  'sub' => 'userexternal',
  'aud' => 'https://tiledesk.com/projects/#{YOUR_PROJECT_ID}'
};
$token = JWT::encode($payload, '#{yourProjectSharedSecret}');

Java

SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;
long nowMillis = System.currentTimeMillis();
Date now = new Date(nowMillis);
byte[] apiKeySecretBytes;
apiKeySecretBytes = SECRET_KEY.getBytes();
Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName());
JwtBuilder builder = Jwts.builder().setId(id)
        .setIssuedAt(now)
        .setSubject(subject)
        .setIssuer(issuer)
        .claim("firstname", firstname)
        .claim("lastname", lastname)
        .claim("email", email)
        .signWith(signingKey, signatureAlgorithm);

return builder.compact();

Please refer to the above mentioned repo for further deatils.

Verify the token

  1. Paste the secret code

  2. Paste the jwt code in the left column

  3. Check the "Signature Verified" label

Widget Authentication

If none of these samples match your needs, JWT has a more extensive list of to explore.

Install :

You can find a NodeJs Custom Jwt Authentication example .

Download :

Authentication with Java is covered with a simple Java (Maven) example on the public repo

We use the to implement the Tiledesk JWT sign operation.

You can verify the JWT token using following these steps:

image

See using the JWT token.

JWT libraries
jsonwebtoken
here
PHP-JWT
TiledeskJavaJWTSign
JJWT library
jwt.io
how to setup custom authentication for the widget
JSON Web Token
full tutorial on Custom Authentication