This article is intended for Zendesk administrators. For information on the tasks required for developers, see Enabling authenticated visitors.
This article includes the following topics:
About end user authentication for web and mobile messaging
End-user authentication is, simply put, verifying the identity of an end user. The verified end user’s new messaging request can then be connected with their past conversations, allowing agents to better support them.
This section includes the following topics:
Understanding key elements
To understand how end user authentication for messaging works, you should be familiar with the key elements involved in the authentication process:
- JSON Web Tokens (JWT) for authentication. Zendesk uses signed JSON Web Tokens (JWT) for authentication in messaging. These tokens verify the identity of the end users. See jwt.io for detailed information on JWTs.
- Signing key. A signing key is created by a Zendesk admin in Admin Center, and shared with your developer, who will then use it to sign the JWT as necessary. See Creating and sharing the signing key.
- Unique user identifiers, or external ids. These are alphanumeric strings (usernames or customer ID numbers, for instance) that are unique to each user. If you have multiple brands in your Zendesk account, a user must have a unique identifier in each brand.
- User name(optional). Including the name may help agents communicate with end users. If this information is collected and included in the JWT, it will appear in the Agent Workspace. However, it is not required.
Overview of the setup process
To enable end-user authentication, your Zendesk Admin first needs to create the signing key in Admin Center and provide this key (which will contain a secret) to your developer. Your developer will then need to implement a service on your business' back-end that can create the signed JWT and return this to your website or mobile app when requested (steps 1 and 2 in the image below). Any time your user is logged in to your website or app, your developer will need to call an equivalent login API which will be provided in both the Zendesk Web Widget and the Mobile SDKs. At sign-in time, the JWT will be passed to Zendesk in order to verify the claimed identity of the user (step 3 in the image below).
How the end-user and agent experiences are impacted
Once authentication for messaging is implemented, end users and agents will see slight changes in their experiences:
- End users: Once they have been authenticated and their identity has been verified with Zendesk, the end user will not be prompted to provide their name or email address by the messaging bot as part of the default messaging response.
- Agents: Verified end users will be identified in the Agent
Workspace by an authentication icon:
The agents will be able to view the external id as part of the end user's profile.
If the external id provided with the API matches the external id of an existing user, the messaging ticket will be referenced against the existing end user.
When an end user authenticates:
- A new end user will be created. The messaging ticket of the anonymous user will be associated with the newly-created user with the external id.
- If the authenticated end user has a non-closed messaging ticket, that ticket will be updated with the new messages.
- When an end user signs out, a new end user and new messaging ticket will be created for the subsequent conversation.
- End user A sends a message without signing in. User 1 and Ticket 1 is created.
- End user A signs in mid-conversation. User 2 is created with an external id (if no user with the external id exists).
- Conversation continues in Ticket 1 and the requester is updated to User 2.
For returning authenticated users, there’s a background ticket merge to ensure conversational continuity. For example:
- End user A has an open Ticket 1 as an authenticated user.
- End user A logs out.
- End user A sends a message without signing in. User 2 and Ticket 2 are created.
- End user A signs in again mid-conversation. Authenticated User A is retrieved via the external id and the anonymous and authenticated conversations are merged.
- Conversation continues in Ticket 1 and Ticket 2 is closed.
See Working with authenticated end users in the Zendesk Agent Workspace.
Creating and sharing the signing key
As mentioned in the section above, a Zendesk administrator must create a signing key and share it with the developer for use in the JWT. You can store up to 10 keys. Creating a signing key also enables messaging metadata variables in Flow Builder.
To create and share a signing key
- In Admin Center, click Account in the sidebar, then select Security > End user authentication.
- Click the Messaging tab, then click the Create key button. If you are creating your first key, this button appears at the bottom of the page; if you have previously created a key, it appears in the top-right corner.
- In the Create new key dialog, enter an identifying name for the key,
then click Next.
- In the Copy shared secret dialog, click Copy to save the secret
to your clipboard, then click Hide key forever.
You’re returned to the Messaging tab, where the new key appears in the signing key list with the first six characters of the secret shown.
- Confidentially send the shared secret key to your developer, who can then use it to create the JWT. See Enabling authenticated visitors for more information.
If you generate a new key but have reached your 10-key limit, a notification appears, asking you to delete any unused keys.
To delete an unused key
- In Admin Center, click Account in the sidebar, then select Security > End user authentication.
- Click the Messaging tab.
- Hover over the key you want to delete, then click the option menu icon and select Delete.
- Confirm the action by clicking Delete key.
The following limitations apply to the current version of end-user authentication in messaging:
- Restricted Guide articles. Guide articles that require authentication will not be available to users initially, even if they are authenticated. We will make additional improvements to the messaging product to enable users to view Guide articles that require user authentication. Articles that do not require user authentication are not impacted.
- Email addresses in Agent Workspace. The email address of the end user will not be visible in Agent Workspace initially. This is also a limitation that we are actively working to remove. We would encourage businesses who wish to view the user’s email address in Agent Workspace to include this data in the JWT payload in order to prevent future development once this limitation is removed, but it is not necessary. Alternatively, you can use external id to surface email address, if the email address is a unique identifier for your customers.
The Developer Documentation links to https://developer.zendesk.com/documentation/zendesk-web-widget-sdks/sdks/web/sdk_api_reference/#authentication which currently does not exist.
Hi Thomas! Apologies for the delay, the developer documentation has now been updated.
Awesome, appreciate it!
It looks like we've managed to implement authentication for messaging since the end-user is not prompted to provide their name and email address.
BUT in the user profile, the email field is still empty.
Here is the code that we use to generate the token:
Also, the user id is not displayed in the custom ticket field.
HI Alex, this is a currently limitation of the product. We working on an improvement to Agent Workspace to add this information in the near future.
We have been waiting for this feature, as we intend to use it to link Zendesk Messaging users to users in our app, so we can e.g. show additional information to our team through a Zendesk app or similar means. For this link, we are trying to use the external ID, which would be our app user ID.
However, we have not been able to achieve that so far:
Especially the latter behaviour seems like it goes beyond being a limitation - effectively Zendesk seems to create two users using the same email address. This doesn't seem like it would be an issue exclusive to our workflow, but instead also creating users that e.g. have handed in tickets before using that email address.
So my questions are:
Hi team, is there an estimated timeframe to release the Restricted Articles Access in Messaging for authenticated users?
Hey Kevin Konings wondering if you ever heard back about your second point there?
We're running up against the same problem which defeats the purpose of authenticating the user if we're not able to attach them to the existing user and map their history accordingly. Is this a known limitation or a bug?
Hey Clayful, sadly nothing yet, I've messaged Support a few days ago and they told me they'll come back to me.
I 100% agree with you, this is not really authentication if it doesn't authenticate as the same user our agents already interacted with in previous tickets.
Hey Kevin Konings, have you received any news?
To add to this shortcoming from Ken Millar, if our agents can't see the email address of the end user it severely slows them down from doing effective troubleshooting on our internal staff dashbaord to track information about the user.
A timeline of these enhancements would be really appreciate ZD team. Thanks!
We haven't implemented this yet. When you say it doesn't bring over the email address of the customer on the ticket, what information does it bring over? Or is the user information just blank? I'd love to see a screenshot of the whole ticket if someone would like to share. Is there a way to merge the user or add the customer's user info to that ticket? Just curious on what you all are using as a work around until Zendesk fixes this limitation? Your comments make me hesitant to implement this feature even though we have been looking forward to it. Thanks for your help!
Frankly - it's a mess 😅
We're using the SFDC ID as the external field which for some reason ends up getting populated as the Web User ID (but doesn't get recognized as the external ID or tied to the existing user) - screenshot below.
This is good news because at least we *can* actually then merge the user with the existing user by searching for this ID -- so It really only affects the agents the first time the user chats in. For subsequent chats once they're merged, the original user is now the one that pops up. Great.
The issue is now the bot behavior is EXTREMELY wonky! It is quite unclear when the bot starts the convo vs when it doesn't and what messages happen if you're within business hours or not. Some of the bugginess gets resolved if you open the chat in a new window or refresh -- but of course this is not a great look for our users. This is now our biggest issue since the email issue above can be "hacked" around and dealt with internally while this is just a terrible experience for our end users...
I'm also awaiting a response from the support team so will comment on here once I hear back!
Hey Jen Cole,
when we tried to implement this feature two weeks ago, users were created only with the name submitted through the JWT. Neither the email address nor the external ID we submitted were visible in the agent interface nor through the User API. Here's a screenshot of how it looks like (so basically only the name is filled out):
Our plan was to fill user information when users sign up in our app, and then authenticate these users in Zendesk Messaging through their external ID or email address. However, the user created here already had an end user with the same email address and external ID they used for authentication, and Messaging still created a new user instead.
I haven't gotten feedback from Zendesk yet on my questions above, and hope this Mesaging behaviour is not intended because the way it is makes the feature pretty much useless to us.
We're seeing the exact same thing as Kevin Konings and this is really preventing us from moving to messaging. It's likely without a fix we'll go with chat here.
The second issue we're seeing is even if you use the created user, it ends up creating a further duplicate user.
Thank you Ken Millar and Maria Barrera! That was very helpful. Looks like we will need to wait to implement this when the email address/user information can be authenticated and then brought over into the ticket created.
Mick O'Donnell, will we be notified when the feature is updated with the user information/email address of the user is brought over into the ticket creation?
We receive tickets through the messaging channel inside and outside of business hours. If the ticket comes through as a web user and possibly a user's name, but no email address, then it would be pretty hard to track down the correct user without the email address as well (for those tickets that come in outside business hours). Email addresses are our unique identifier for customers and needed to link all user data together. We are very anxious for the update to this feature so we can implement it. Thanks!
We are having a similar issue regarding authentication. We are using loginUser(jwt) and the only data saved and retrieved on successCallback is the external_id.
Note that the jwt contains also a name and an email.
Thank you all for writing in and providing feedback. We want to provide more visibility into our future improvements.
Our plan is to surface external_id and name as part of User profile. They are critical for identifying your customers. This is planned to be rolled out in early Q2. Displaying email will follow soon.
In the short term, we will be displaying external_id in the conversation. This will be rolled out in a couple of weeks.
We will drop an update in the Release Notes as well as on this thread once it is rolled out.
Hey Prakruti Hindia
thanks for the feedback!
What about the issue of creating duplicate users with the same email that me and others are facing? Is this a bug right now or will this also be part of these improvements in early Q2?
Hello Prakruti Hindia,
I want to ask a question. Is it possible to put tags on the payload when we generate the JWT token and be visible on Agent Workspace?
If it's not possible. Do you have any workaround how to send tags on Agent Workspace via Zendesk Messaging (Flow Builder)? so we don't need to input the value that we need manually from the ticket fields
We will be merging users , if there are users already existing in the system with same external id. This will be part of the improvements coming early Q2.
I have also requested other Product Managers to respond to questions on tags and expiry. They will be responding soon.
Important update: We have rolled out a small fix which will surface external id when agent hovers over the authentication badge.
We will continue to focus on associating external_id with the User profile.
In response to this question: "Will there be an expiry if we don't pass in `exp` in the JWT payload? If so, what will be the duration?", no expiry is set if you don't provide one in the JWT. So you need to think about the value that makes sense for your security policy.
Hi Flash Coffee!
Currently it's not possible to insert additional claims in the JWT payload, and use this data is other parts of the system, but we are currently exploring options to allow customers to achieve this. The JWT itself may useful for client-side contextual data, but this is likely to be just one part of the solution. Today, you need to input the values that you need manually, sorry.
Hi Zendesk team,
What is the proper value to use for the `kid` property in the JWT header? Is it the App ID, Client ID, or none of these?
Edit: I got an answer to this question here: https://support.zendesk.com/hc/en-us/community/posts/4421945067546-Having-issue-when-trying-to-authenticate-/comments/4446353121434#community_comment_4446353121434
Hi Prakruti Hindia,
Has the new fix that you mentioned made it so that when the user sends a message from the widget and their external_id is set in the JWT, if there already existed a user with that same external_id then it wouldn't create a new one and instead asign that ticket to that "old" user?
Having an issue implementing authentication with this.
First, I embedded the script (actual key substituted with SECRETKEY)
Next, I generated the JWT with the user scope, external_id, etc., and verified the payload and encryption type using JWT.io. No problem there.
However, now that I look at it, I'm getting this error regardless of whether I'm trying to authenticate users or not. No matter what, the widget loads, but i get this.
Despite this error, the widget still loads, just without any sign of authentication working. So, I can't tell if that's what's stopping my JWT authorization from working or if it's something else.
Also, Here's the code I found to authenticate. I've created a function that matches the callback to deliver the JWT token.
We seen another issue happening on some Samsung devices.
We integrated Zendesk SDK (the new one) and using multiple features from the SDK: initialize, loginUser, logoutUser, unreadMessageCount and the ZendeskEventListener for unreadMessageCountChanged.
So, basically we saw a white screen when opening the chat on some Android (Samsung) devices. Clearing the cache fixes this issue, but when logging out and logging in again the issue persists.
How can we solve this?
Please sign in to leave a comment.