Introduction

Deskpro Messenger supports authenticating and authorizing users by means of a JWT (Json Web Token) provided by the host system. This mechanism is used internally within Deskpro Help Center, and it is also available externally when Messenger is embedded into a customer’s web page or mobile app.

How it works

A JWT is a Json payload that is cryptographically signed with a private key. Note that the payload is not encrypted and is easily readable - the payload must not contain secrets.

When the JWT is provided to Messenger then the cryptographic signature is validated on the server, using the same private key. If the validation passes then Messenger trusts, and acts on, the payload; if it does not pass validation then Messenger rejects the payload.

The payload should describe the user, as represented by the host system.

When Messenger accepts a JWT then it will either:

• Find an existing Deskpro user that matches the identifiers in the payload; and update that user to match the payload

• Create a new Deskpro user that matches the payload

In both cases, the Deskpro Messenger user will now be labelled as a “confirmed” user; whereas Messenger users without a JWT will always be labelled “unconfirmed”.

The user identified by the JWT will now be logged in to Messenger and be able to access any existing conversations, and to create new conversations, as that user.

Payload

The structure of the payload is shown below. All fields are optional.

{
    deskpro_id?: string
    email?: string
    emails?: string[]
    name?: string
    first_name?: string
    last_name?: string
    organization_id?: string
    language_id?: string
    usergroup_ids?: string[]
    fields?: { [key: string]: string | string[] }
    timezone?: string
    labels?: string[]
}
 copy

Identifier fields

The deskpro_id and email fields are identifiers for identifying an existing user within Deskpro. If a user exists for either identifier then that user will be logged in to Messenger. If both identifiers are used and refer to different Deskpro users then the JWT will be rejected. If the user does not exist then a user will be created.

Other fields

The other fields will be used to create or update the user in Deskpro.

All users are considered part of usergroup “1”; and all users with a JWT are considered part of usergroup “2”. The usergroup_ids field should only contain other user groups.

Unconfirmed users

Within the deployment options for all types of Messenger configuration (web, iOS, etc.) there is an option to require all users to authenticate with a JWT.

If unconfirmed (anonymous) users (defined as those without a JWT) are to be permitted then leave this option disabled. If Messenger is only allowed to be accessed by users who authenticate by JWT then enable this option.

Usage patterns

There are two patterns for user management with regards to Messenger: upfront or on-demand.

Upfront management

With upfront management, the host system creates and updates the users within Deskpro using the APIs. This can happen as a scheduled synchronization process, or in response to a user navigating to a page containing Messenger.

Since all potential Messenger users exist within Deskpro then the JWT payload can be small - and will typically contain only the deskpro_id.

{
  deskpro_id: "42"
}
 copy

On-demand management

With on-demand management, the host system generates a JWT containing all of the information required to authenticate and authorise the user.

This will require a larger payload that typically does not include the deskpro_id.

{
  email: "john.smith@example.com",
  first_name: "John",
  last_name: "Smith",
  usergroup_ids: ["3", "4"]
}
 copy

The expectation is that the user will be created in Deskpro on the first use of Messenger.

Technical details

How to pass the JWT to Messenger

Web

Modify the Messenger init script to include the signedUserInfo parameter within the DpMessengerOptions.

The example below is an example, from the deployment screen of the Messenger admin, modified to include the JWT. This example assumes that the JWT is available in a variable called jwt.

<script>
  window.DpMessengerOptions = {
    showLauncherButton: true
    signedUserInfo: jwt
  }
</script>
<script
  type="module"
  src="<https://example.com/deskpro-messenger-init/web.js>"
  data-deskpro-url="<https://example.com/deskpro-messenger/00000000-0000-0000-0000-000000000000>"
  data-messenger-id="01HGFZRNX7M9S4PX2G3RIA8S0C"
></script>
 copy

Mobile (iOS, Android)

The instructions for passing the JWT to the mobile SDKs can be found in the readme files for the appropriate SDK.

How to generate the JWT

The generation of a JWT requires the use of a secret key. Therefore the JWT can only be securely generated on a secure customer server.

The user web session must make a request to this server, providing the user’s host credentials, and the server will respond with the JWT.

Any JWT library that supports the HS256 algorithm can be used.

The server should construct the payload based on the host knowledge of the user, and provide both the payload and the private key to the library for cryptographic signing. The server should return the JWT, and then the client provides the JWT to the Messenger configuration as described above.