You may want to authorize Users or Agents with credentials from a web-based service that your company has developed: your intranet/extranet, an app or service you provide.

The way to implement this is using Deskpro’s support for JSON Web Token (JWT) authentication.

JWT is a token-based method of securely transferring authentication claims between two servers: in our case, a claim that your system has approved the User and they should be allowed access to Deskpro. The claim is encoded in a compact token. The token is cryptographically signed, so Deskpro knows the claim is genuine. It doesn’t contain the User’s password, just a confirmation of their identity and for how long the claim is valid.

To set up JWT, you install the Deskpro JWT authentication app and provide it with the URL of a page that can tell Deskpro if the User is authenticated.

JWT is a fairly straightforward method to implement, with libraries available in the major web development languages.

Further reading:

https://scotch.io/tutorials/the-ins-and-outs-of-token-based-authentication

https://scotch.io/tutorials/the-anatomy-of-a-json-web-token

JWT Authentication Overview

When Deskpro verifies a User or Agent with JWT, the sequence of events is as follows:

1. Deskpro directs the browser to a remote login URL which indicates a page you have developed where your service can verify Users, with an HTTP GET “return” parameter.

2. The page at the URL authenticates the User; the details of how this happens are entirely down to you.

3. If the User is authenticated, the system generates a JWT token containing the User’s ID, Email and name, and returns the browser back to the “return” URL specified in step 1, with the JWT token encoded in a “jwt” GET parameter.

4. Deskpro can verify the JWT token using a shared secret that you have entered.

JWT Implementation Details

We suggest you consult jwt.io for links to JWT libraries and information, including a debugging tool.

There is PHP example code available on our GitHub repository showing a working example implementation.

The JWT token must include the following claims:

• "id" (a unique ID for the User on your service; this will not be used for the Agent or User ID in Deskpro)

• "email"

• "name" (or first_name and last_name)

For security, you should also include these claims as per the JWT specification:

• "iat" (the time the token was issued)

• "exp" (the time the token expires e.g. iat + 5 minutes)

• "jti" (a unique identifier for the token).

Configuring Deskpro to Use JWT

Once you have implemented JWT:

1. Install and enable the Deskpro JWT app from Agents > Auth & SSO or CRM > Auth & SSO, depending on whether you want to authenticate Agents or Users.

2. Enter the Remote Login URL where you service will authenticate Users.

3. Enter the JWT Secret Code: this is an arbitrary secret you use to encode your JWT tokens. It must match between your tokens and the JWT auth app.

4. Configure the  Authentication and SSO. You need to specify an Agent Logout Redirect URL where the Agent is sent when they log out.

5. Set the  Auto Agent option (for Agents) or  Grant Usergroup option (for Users) to set what Permission Group or Usergroup is granted through a JWT login.

6. Click Save and then Test Settings to check that your implementation is working.

Automatically Redirect Logged in Users

When configuring the remote login URL, you can specify which page Users are returned to after they authenticate. By default, Users will be returned to your Deskpro homepage. You are able to change this by appending the Remote login URL with some return information.

/login/authenticate/1?return=/new-ticket/
 copy

The above example would redirect Users authenticated through JWT to the new Ticket submission page.