JWT for Authenticating Users in the ASAP Add-Ons

JWT for Authenticating Users in the ASAP Add-Ons


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  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 SDK for Android                                                                                                                                                                                   

    Zoho CRM Training Programs

    Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

    Zoho CRM Training
      Redefine the way you work
      with Zoho Workplace

        Zoho DataPrep Personalized Demo

        If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

        Zoho CRM Training

          Create, share, and deliver

          beautiful slides from anywhere.

          Get Started Now

            Zoho Sign now offers specialized one-on-one training for both administrators and developers.

            BOOK A SESSION

                                You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.

                                    Manage your brands on social media

                                      Zoho Desk Resources

                                      • Desk Community Learning Series

                                      • Digest

                                      • Functions

                                      • Meetups

                                      • Kbase

                                      • Resources

                                      • Glossary

                                      • Desk Marketplace

                                      • MVP Corner

                                      • Word of the Day

                                        Zoho Marketing Automation

                                          Zoho Sheet Resources


                                              Zoho Forms Resources

                                                Secure your business
                                                communication with Zoho Mail

                                                Mail on the move with
                                                Zoho Mail mobile application

                                                  Stay on top of your schedule
                                                  at all times

                                                  Carry your calendar with you
                                                  Anytime, anywhere

                                                        Zoho Sign Resources

                                                          Sign, Paperless!

                                                          Sign and send business documents on the go!

                                                          Get Started Now

                                                                  Zoho TeamInbox Resources

                                                                          Zoho DataPrep Resources

                                                                            Zoho DataPrep Demo

                                                                            Get a personalized demo or POC

                                                                            REGISTER NOW

                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now

                                                                                            You are currently viewing the help articles of Sprints 1.0. If you are a user of 2.0, please refer here.

                                                                                            You are currently viewing the help articles of Sprints 2.0. If you are a user of 1.0, please refer here.

                                                                                                  • Related Articles

                                                                                                  • Understanding the enhanced JWT mechanism for Authenticating Users in the ASAP Add-Ons

                                                                                                    Types of Users End-users can be categorized as guests or authenticated users based on how they log in to the ASAP add-on. Guest Users Guests are users who do not sign in while logging in to the ASAP add-ons. They can access the Knowledge Base module, ...
                                                                                                  • Implementing a secure user authentication for help center using JWT

                                                                                                    This feature is released in a phased manner and will be available only to those who request for it. To request early access, click the registration link and provide your details. We will enable the feature for your Desk account. User authentication ...
                                                                                                  • 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 embedding this add-on with your website, you can provide your customers with easy access to your: Customer support team (to raise ...
                                                                                                  • Working with the ASAP SDK for iOS

                                                                                                    SDK version 3.0 The ASAP SDK for iOS provides easy access to help 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 the following help center ...
                                                                                                    Wherever you are is as good as
                                                                                                    your workplace



                                                                                                      Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.


                                                                                                      Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.


                                                                                                      Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.

                                                                                                      CRM Tips

                                                                                                      Make the most of Zoho CRM with these useful tips.

                                                                                                        Zoho Show Resources