How do I test a JWT Token to integrate my Zendesk Help Center into a web portal?

 

This article has been created as a step-by-step guide in building a Zendesk JWT authentication token manually. This article can be used as a primer to build authentication from your own portal into Zendesk using Single Sign On (SSO) using your own custom code. 

 

Background: Many customers have published web-portals who would like their customers to access in order to view services and account information. If you have one, then why not integrate your Zendesk Help Center and embed all that self-service goodness into your own portal?

 

The benefits of of integrating the Help Center into your portal are many:

 

If you plan on integrating your portal with the Zendesk Help Center, you will be required to pass a JWT authentication token to Zendesk so the customer is directly authenticated from your portal. This can be notoriously difficult to debug when you are building the token, so here are some tips on making sure it works...

 

There are a few pieces to the puzzle and items to watch out for, so here is my laundry list:

 

1. Use jwt.io website (or something similar) to build the token. The following is an example:
   https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cGUiOiJKV1QifQ.eyJqdGkiOiIzYjE1OGJhM2ZmMDQxMzg3NmJmOGI2MGUwNGQ0OTE0MCIsImlhdCI6MTY1ODI4NTA0NCwibmFtZSI6IkFybm9sZCIsImVtYWlsIjoiYWx5YW5jaGFAZ21haWwuY29tIn0.183212312312eb98c9af9a78ee61a4e791deed3094ccf079d85e4ac659212ae9047ef
2. You need to add the shared secret that is generated in Zendesk when you setup the JWT authentication (remember to save this somewhere safe as it is effectively given a admin password away). This can be found in your Admin Center at:
   Account Security->Single sign-on->Create JSON Web Token configuration
   
   Here's what the jwt.io page looks like with the following Header and Payload components:
   
3. The unique id “jti” needs a new and unique number everytime you run it. If you use the same ID for two requests, the 2nd one fails. I just made up random numbers for each request such as “1231231231321312123312132113132"
4. The timestamp “iat” is the unix epoch clock. If the timestamp is more than 3 minutes in arrears, then the request will fail. I used this URL to determine the current timestamp and replaced the old one: https://www.epochconverter.com/clock
5. With that information, I generated the token from that website which looks like this (note that the start of the URL refers to the jwt.io website which we will need to replace in the next step):
   https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cGUiOiJKV1QifQ.eyJqdGkiOiIxMjMxMjMxMjMxMjMxMjMxMjMxMjMxMzIxMzIxIiwiaWF0IjoxNjU4MzkwNDMzLCJuYW1lIjoiQXJub2xkIiwiZW1haWwiOiJhbHlhbmNoYUBnbWFpbC5jb20ifQ.JORYyurSx-uNucOfIwA6G06RavlqnlTVZRU30JvzQ7
6. Finally, I just needed to replace the domain name reference at the start with the Zendesk domain you are testing it against like the following:
   https://mysupportportal.zendesk.com/access/jwt?jwt=eyJhbGciOiJIUzI1NiIsInR5cGUiOiJKV1QifQ.eyJqdGkiOiIxMjMxMjMxMjMxMjMxMjMxMjMxMjMxMzIxMzIxIiwiaWF0IjoxNjU4MzkwNDMzLCJuYW1lIjoiQXJub2xkIiwiZW1haWwiOiJhbHlhbmNoYUBnbWFpbC5jb20ifQ.JORYyurSx-uNucOfIwA6G06RavlqnlTVZRU30JvzQ7