Introduction

Why is a JWT needed?

Figure 1: JWT Implementation in the ASAP Add-On

Prerequisites for Enabling JWT

The following two components are essential for JWT-based authentication:

• JWT endpoint
  
• JWT secret
  
  

JWT endpoint : This is a server endpoint that you must set up before configuring JWT authentication for the ASAP add-on. This endpoint must contain the code that generates the JWT and it is this endpoint to which the IAM server sends the GET request containing the user token. Make sure to provide a valid URL for the JWT endpoint when setting up the add-on in Zoho Desk. 

Here's an example of a JWT redirect URL -  https://safe-forest-77068.herokuapp.com/getjwt?user_token=token

The JWT endpoint must also constantly run the following program with the JWT secret generated for your add-on. 

import io.jsonwebtoken.SignatureAlgorithm;

import javax.crypto.spec.SecretKeySpec;

import java.security.Key;

import io.jsonwebtoken.JwtBuilder;

import io.jsonwebtoken.Jwts;

import java.io.UnsupportedEncodingException;

 

 

public static String generateJwt(String userToken) throws UnsupportedEncodingException{

 String secretKey = ""; //This value will be given once add-on is created. Then replace the provided value here

long notBeforeMillis = System.currentTimeMillis();

long notAfterMillis = notBeforeMillis + 300000;

 

SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

 

byte[] apiKeySecretBytes = secretKey.getBytes();

Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName());

 

JwtBuilder builder = Jwts.builder().signWith(signatureAlgorithm, signingKey);

 

String jwt = builder.claim("email_verified", true)

.claim("not_after", notAfterMillis)

.claim("not_before", notBeforeMillis)

.claim("email", <user_email_address_from_user_token>).compact();

return jwt;

}   

• userToken is an input parameter that considers the user token received from the app. This parameter carries the details of the user logged into the app. Therefore, make sure that the user token is encrypted when it is sent from the app to Zoho's IAM server and then to the JWT endpoint. It is at the JWT endpoint that the user token must be decrypted and verified for authenticity. 
  
• The  email parameter returns the email address of the user. 
  
• The  email_verified parameter is a Boolean parameter that returns if the email address is verified or not and subsequently sends the OAuth token to the ASAP add-on. 
  
• The  not_before and  not_after parameters define the duration after which the JWT expires. The value of these parameters must be in the Coordinated Universal Time (UTC) format and expressed in milliseconds. 
  
• To ensure strong security, make sure that the time difference between the not_before and not_after parameters does not exceed 600000 milliseconds (10 minutes). 
  

JWT secret : The JWT secret is a unique code shared when you set up the ASAP add-on in Zoho Desk. It is used for signing user details after the JWT endpoint verifies the user token it receives from the IAM server. This signed piece of data is called the JWT response. 

 

The JWT secret is shared only once--at the time of registering the add-on. Therefore, make sure to store the secret in a highly secure location and do not share it with any untrusted parties.

How does a JWT work?

When a user tries to log into the ASAP add-on using the credentials for the main app, the app sends its client ID, client secret, and user token to Zoho's IAM server for verification. 

 

If the IAM server finds the credentials to be valid, it sends the user token and a GET user request to the JWT endpoint, via the JWT redirect URL. 

 

Then, the JWT endpoint verifies the user token for its authenticity. Following this verification: 

if the user token is valid, the JWT response containing user details (user email ID, email verification status, login time interval) is signed with the JWT secret and sent back to the IAM server

• if the user token is invalid, the JWT response is sent back with the value of the email_verified parameter set to false
  
• If the IAM server receives a valid JWT response, it further sends the OAuth2 token that finally considers the end-user a user of the help desk portal. 

In the case of the ASAP add-on, security reasons mandate the use of the GET method and not any other method to fetch the JWT. 

Key Points to Remember

• You can change the JWT URL anytime on the setup page. 
  
• The URL must include a param called "user_token" for passing on user information to the JWT server. 
  
• The JWT response must be returned as a plain string. 
  
• The JWT response must contain the  email ,  email_verified ,  not_before , and  not_after params.
  
• A change in the app server time might affect the values set for the  not_before and  not_after params. Therefore, make sure to modify the JWT code too when the app server time is changed.  
  
• Currently, only the HMACSHA256 algorithm is supported for signing. 
  

For web users who activate new or additional ASAP going forward in Desk, the authentication mechanism will be based on the new flow. See also JWT new flow .

Also read:

Working with the ASAP Add-On for the Web

Working with the ASAP SDK for iOS

Working with the ASAP SDK for Android