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:
- Customers need only a single login and once authenticated in your portal don't need to enter their details in order to submit an enquiry in Zendesk.
- Customers can see and manage/update all their existing Zendesk enquiries.
- Customers can follow Help Center Articles and Sections and will be notified via email if there is an update.
- Zendesk can provide protected content that is not public facing, based on the customer profile or organisation the customer belongs to.
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:
- Use jwt.io website (or something similar) to build the token. The following is an example:
- 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:
- 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"
- 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
- 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):
- 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:
Now paste this URL into your browser and if all steps have been followed correctly, you should find an authenticated Zendesk landing page... I have now successfully logged in as Harry (see screenshot below).
Once you are successfully able to login via your manually created JWT Token, you are now free to replicate that in your custom code.
Some additional reference articles you may want to take a look at are as follows: