JWT for Authenticating Users in the ASAP Add-Ons

JWT for Authenticating Users in the ASAP Add-Ons

Introduction

Based on whether they choose to login to the ASAP add-on or not, end-users can be classified as guest users and authenticated users. Those who choose to not login are called guest users and those who choose to login are called authenticated users. In the ASAP add-on, you can define which component and content will be visible for each type of user. 

Guest users can access the knowledge base, submit a ticket, view posts in the user community, and chat with your customer support agent.  

On the other hand, authenticated users can access the knowledge base, submit a ticket, view tickets that they have submitted, chat with your customer support agent, and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts). 

Why is a JWT needed?

The ASAP add-on, though provided by Zoho, is not a stand-alone app; it works in tandem with your main app, empowering it with the help center functionality. When end-users log into your app, they would want to access all associated features, including the help center, through a single login. Having to log into the app with one set of credentials and having to log into the help center with another set of credentials--because the services could be using different authentication methods--inconveniences end-users. This is where the JSON Web Token (JWT) comes into play.

- JWT-based user authentication is possible only if Single Sign-On (SSO) is enabled in your Zoho Desk portal. SSO ensures that end-users need not use different login credentials to access the different support systems you have. If SSO is not enabled, end-users can access the ASAP add-on only as guest users.

- Make sure that SSO is enabled in the default help center and not in one of the multibrand help centers in your portal. 

What is JWT?

The Internet Engineering Task Force, the body that created the JWT standard, defines JWT as "a compact, URL-safe means of representing claims to be transferred between two parties." 

In the context of the ASAP add-on, JWT is the mechanism that verifies the authenticity of a user of the main app and provides them with permission to use the ASAP-driven help center with the same credentials.  

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






Also read:
Working with the ASAP SDK for Android                                                                                                                                                                                  
    • Related Articles

    • Debugging JWT-Related Errors While Configuring the ASAP Add-On

      While setting up an ASAP add-on for your web/mobile app, you might encounter an error related to JSON Web Token (JWT) configuration. It is essential to debug this error because user authentication in the ASAP add-on is possible only through JWTs.  ...
    • Working with the ASAP Add-On for the Web

      Introduction The ASAP add-on for websites makes your help center available within quick reach for your end-customers. By integrating this add-on with your website, you can provide your customers with easy access to your:  Customer support team (to ...
    • Working with the ASAP SDK for iOS

      SDK v2.0 Introduction The ASAP SDK for iOS makes help available within quick reach for the end-users of your iOS app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your: ...
    • Working with the ASAP Add-Ons for Mobile Platforms

      The ASAP SDKs for mobile platforms--iOS and Android--make help available within quick reach for the end-users of your mobile apps. Using these SDKs, you can create and customize add-ons that reside within your app and provide end-users with easy ...
    • Working with the ASAP SDK for React Native

      The ASAP SDK for React Native makes help available within quick reach for the end-users of your mobile app. Using this SDK, you can add and customize an add-on that resides within your iOS/Android app and provides end-users with easy access to your: ...