Introduction

Why is a JWT needed?

Figure 1: JWT Implementation in the ASAP Add-On

• JWT endpoint
  
• JWT secret
  
  

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). 
  

How does a JWT work?

• 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. 
  

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.