Enabling JWT (JSON Web Token) single sign-on

Return to top
Have more questions? Submit a request


  • Aleksey

    Hi. Is there any article that clarifies the conditions when Zendesk redirects user to JWT authentication endpoint? Everything works flawlessly and completely transparently when I manually click the "sign in" button in Help Center, but I don't see any redirections when I just visit the Help Center in a freshly opened browser's incognito mode window.

  • Dara Garvan
    Zendesk Team Member

    Hi Aleksey,

    There's no particular article for this, however we only redirect when a user selects either the "Sign In" button or directly clicks a ticket link from say, an email notification that requires sign in.

    You can of course, require that all users are signed into the Help Center, to ensure they get redirected if required.


  • Dan Zaner

    Hi everyone,

    Can anyone confirm that SSO using JWT is possible on a "Starter" plan account? The "Plan Availability" header at the top of this article says that it is NOT available, but the main Pricing page (https://www.zendesk.com/product/pricing/) says it IS available. I've also read posts in this Forum that say that SSO via JWT is available on all plans, but maybe that person was just reading the Pricing page. Has anyone actually successfully done it?

    I ask because I've attempted an SSO integration that returns a 401 "unauthorized" status page every time with body content set to this sparse and rather unenlightening message:

    {"error":"Couldn't authenticate you"}

    Even more interesting is the fact that an end-user account is created even though I get the error. I'd sort of figure that this would be all-or-nothing; I'd assume I'd either get a new end-user created (if needed) and logged in or I'd get completely rejected and nothing would happen. The fact that the end-user account gets created makes me believe that the JWT got decoded and verified successfully, but then I can't explain the "Couldn't authenticate you" message.

    Has anyone gotten this before? Is there a "verbose" mode where you get a bit more feedback about why you can't be authenticated? Are there any other debugging tips anyone can pass along.

    Thanks in advance!

    -- Dan

    Edit: I figured out how to get around the error. Activate Help Center from your main Admin control panel. That allows you to determine if users must register and log in or not. Turn that on. Then make sure you supply a return_to param with the JWT call, and make sure the return_to URL is somewhere that a logged in user could go -- like the new request form. Don't leave it empty. Whatever the logic is, the JWT handler does not have a reasonable default value for return_to.

  • Moath Almallahi


    I have the following issue, after doing all what is required, there is only one user get redirected with a message "Please use one of the options below to sign in to Zendesk" this case only happens for a single user, and there is nothing special in the data being sent to Zendesk through the JWT for this user, also tried to look around the website if there is any descriptions for the error am receiving, couldn't find any.

    Any help?

  • Anna Everson

    @Moath - it sounds like you don't have SSO enabled for both agents and end users. In the security settings page, there's a separate tab for each set of users, and you have to enable (and hit save!) on both tabs. And if you're trying to sign in as an end user, make sure to have your Help Center activated. Also note that if you're signing in with an email address that is not already associated with a user profile in Zendesk and you're not also passing in a role with your JWT payload, that user will automatically be provisioned as an end user.

    If you need more help, send us an email at support@zendesk.com. Thanks!

  • Taylor Horwood

    Is it possible to manually change the Shared Secret, or revert back to an old Shared Secret?

  • Anna Everson

    @Taylor - Due to security concerns, you cannot manually set the shared secret or revert it to an old one. Your only option is to generate another shared secret.

  • Dmitry Kirilyuk

    Question about "Error handling" section

    >> If you have a return URL configured for your JWT integration, it will redirect to that and pass a "message" and a "kind" parameter.

    What do you mean by "return URL"? Remote logout URL? If yes, change it in text

  • Anna Everson

    Hi Dmitry - the "return URL" is referring to the return_to parameter discussed in the section immediately before the "Error Handling" section. It is a parameter that you can (optionally) pass along with your JWT payload to redirect the user after they log in. The remote logout URL is separate, and is used to direct the user to your logout page in your SSO system when the user selects "logout" in Zendesk.

  • Jim Tarber

    I have a problem with our JWT SSO setup, which is working fine in my tests but not for one user who cannot login because:

    - Sign In keeps invoking our /support/logout URL (which is /support/logout in our case here).

    - This invocation is done without a return_to argument being passed to it, so it has nowhere to go after signout.

    I only added the Sign Out code last week, and as far as I know it was working fine then. However, at this point the two problems above are preventing this user from logging in. I've asked her to clear cache, try a different browser, etc. They all fail the same way.

    Is it ever normal for my Sign Out SSO URL to be invoked on a Sign In? If so, shouldn't it specify a return_to URL?

    - It's only enabled for end-users

    - It's set to SSO -> JWT and the Remote URLs are:

    Sign In: (domain)/support/login/

    Sign Out: (domain)/support/logout/

    Summary: We've set the two URL fields in the SSO JWT options to the values above and in most cases it's working fine (very smooth, no problems implementing SSO), but the second one is being invoked on a Sign In.  Clearing cache, changing browsers, etc, seems to have no effect.

  • Eldien Hasmanto


    I always get a 500 error page when I try to reach http://server/classic_asp_jwt_with_ad.asp based on a IIS W2008 Server.

    Is anyone facing this error ?

  • Justin Fitzgerald

    It would be helpful to add a table of contents to the top of this article with anchor links down to each section (similar to most ZD articles). I use this page all the time! Thanks.

  • Anna Everson


    "Is it ever normal for my Sign Out SSO URL to be invoked on a Sign In?"

    No, this is probably happening due to a problem in the authentication process. If an error occurs during auth, the user is automatically redirected to the remote logout URL. If you could open a ticket with us, we can help you sort out what exactly is happening.


    I'm not sure what URL you're looking for, but if you're looking for our example code for JWT and AD, the code is here:


    Thank you for your feedback, I will pass that along!

  • Anna Everson

    @Justin (again) - Done! Thanks again for your input!

  • Eldien Hasmanto

    @Anna: Yes I was made some changes for our environment and deployed.

    When I access my zendesk url, it will redirect to AD basic authentication after that instead of return to my zendesk, the page return error page 500

  • Mat N



    I am trying to setup jwt with IIS on win2008.  The script classic_asp_jwt_with_ad.asp and his dependencies are located in C:\inetpub\wwwroot\zendesk on my server.

    However I have an issue when I try to connect.

    When I setup my Remote login URL to http://mycompany.com/zendesk/  the login works with my AD users but I just get the web page index of /zendesk/ on nothing happen (no redirection to zendesk) like the script was not executing.

    If I change my Remote login URL http://mycompany.com/zendesk/script classic_asp_jwt_with_ad.asp  the login works but I get an HTTP error 500...

    Could you please clarify what I should exactly setup for the "Remote login URL" in order for the script to execute and redirect me to sendesk once I log in ?


  • Eldien Hasmanto


    I'm also facing the same error. Hopefully someone can help to this matter

  • Anna
    Zendesk Team Member

    @Mat & @Eldien -  In an effort to assist you further, I've created individual tickets for you.  I'll send you an update via your ticket shortly.  

  • Gary Bunofsky



  • Alexandre Thissen

    Hello and thank you for this helpful article. 

    We have been using the normal zendesk authentication for quite a while for our users and now we would like to use the SSO authentication. 

    If a user had already a zendesk account and then we switch to SSO auth. Does that user will end up with 2 different zendesk accounts ? Is-there some merging rule we could take advantage of ? We just don't want to lose or duplicate user data. 

    In advance, thank you very much, 


  • Anna Everson

    Hi Alexandre,

    As long as the email address that is used in the JWT login is the same one already associated with their Zendesk account, it will recognize them as the same user and no duplicate user will be created.

    It is possible to merge users however, should you need to do so:


  • NSABP Foundation, Inc.

    We are trying to setup JWT with IIS on Windows 2016.  Using the script classic_asp_jwt_with_ad.asp and its dependencies we are able to log into Zendesk without issue.


    We want to be able to pass the phone number and department with our end user logins in doing so we are trying to use the "user_fields" API.  I am woefully unqualified as a Classic ASP programmer, I understand most of the code and how the Scripting.Dictionaries are working.  However when I add the string "employee_department Information Technology" to the scripting object, it fails miserably.


    Can anyone point me in the right direction on how to pass these hashes so that it works.  I can work with pseudo code if you are unfamiliar with ASP.


  • Jessie Schutz
    Zendesk Team Member

    Hey Matthew!

    I saw that you posted this in another thread as well, and one of my colleagues was able to point you to some resources. Let us know if you need anything else!

  • Joan Fernbach

    Is it possible to authenticate users by UUID as well as email address?  If a user changes his email address on our website to match someone else's, he would then be logged into that user's account on Zendesk.

  • Jim Tarber

    Joan, we did that. I'm not sure if it's the official way, but what we did was enable the "external_id" in the authentication settings and always provide the user UUID in that. That supports both name and email changes while preserving the account.

    The only negative from this that I could think of was that support for any external sources such as Facebook or Twitter may not be able to match up that user on those services with the user on zendesk, however that's probably a Good Thing anyway, if they are using different email address on another system.

    Using email to sync information about accounts on external systems is a bit evil in my mind anyway, because the user in question may not want any connection between their accounts, e.g. between their Facebook and Twitter accounts, or Zendesk.  In our service, users use only anonymous avatar names (and images) which do not match their real (wallet) info. Using the email to pull information from another system is potentially a serious privacy violation.  For this reason, one of my urgent work items is to replace the use of gravatar profile images with the image the users have provided on their profiles for our (separate) service. Their gravatar image may be their real life identity.

  • Joan Fernbach

    Thank you Jim - I know we can pass in the UUID, but my question is whether that will be validated for login along with the email address, or is just the email address used to authenticate the user?

  • Jim Tarber

    I can't check (I don't have admin access currently) but I believe there was a checkbox on the Admin->Auth->User tab that enabled or disabled use of the "external_id" field as the key for the user. I believe we've already done email address changes and had the zendesk account retain the previous info associated with that account.  It basically just works, as far as I can tell.

    However, there is a potential "gotcha" here.  If you already have existing user accounts showing up in Zendesk, I'm not sure how transitions to that setup would work. If you don't already have it enabled and filled in per-user, then enable it, new JWT fetches with an external_id may determine that to be a new Zendesk user (losing access to old support requests, etc).   It may just fall back to some attempt to match the email address, or at least until the next JWT is returned for that user.  But I haven't found it described in this level of detail anywhere.

  • Joan Fernbach

    thank you again for your help - the existing user issue was exactly what I was thinking about - we have a large number of users who already have accounts without external ids set, so it may not work to change things now.

  • Nehal Kumar



    I am trying to use implement SSO using JWT in node js. The example provided at https://github.com/zendesk/zendesk_jwt_sso_examples/blob/master/node_jwt.js is wrong.

    issue #1 : iat: (new Date().getTime() / 1000), 

    correct will be 

    Math.round((new Date().getTime()) / 1000)

    issue #2 : I am getting error "The%20unique%20request%20identifier%20was%20reused.%20Please%20fix%20this%20and%20try%20again."

    Below is my implementation


    var generateUUID = require('uuid');
    var jwt = require('jwt-simple');

    getZendeskJWTUrl : function(req, res){
    var db = req.db;
    var userUuid = req.query.userUuid;
    var subDomain = 'dev-slicepay';
    var sharedKey = 'XXXXXXXXXXXXXXXXXX';
    var userColl = db.get('userDetails');
    uuid : userUuid
    } , {}, function(err, userDoc){
    if(!err && userDoc){
    var payload = {
    iat: Math.round((new Date().getTime()) / 1000),
    jti: generateUUID.v4(),
    external_id : userUuid
    if(userDoc.hasOwnProperty('name') && userDoc.name !== ''){
    payload['name'] = userDoc.name;
    if(userDoc.hasOwnProperty('email') && userDoc.email !== ''){
    payload['email'] = userDoc.email;
    var token = jwt.encode(payload, sharedKey);
    var redirectUrl = 'https://' + subDomain + '.zendesk.com/access/jwt?jwt=' + token;
    redirectUrl += '&return_to=' + encodeURIComponent('https://'+ subDomain +'.zendesk.com');
    console.log('Redirecting to : ' + redirectUrl);
    res.writeHead(302, {
    'Location': redirectUrl
    } else {
    status : 'error',
    msg: 'Error occurred while fetching token payload.'
  • Bonnie Leib
    Zendesk Customer Advocate

    Hi Nehal, 

    I see you also sent in a ticket for the question about your JWT script. I responded to you already via this ticket. Thanks so much!


Please sign in to leave a comment.

Powered by Zendesk