Authenticating end users is important for many business purposes. When providing conversational support, users might try to carry on a conversation between devices and channels. By authenticating the end users, you can make sure all points of contact are associated with the correct end user. This can enhance the quality of support your agents provide and increase the security of sensitive information that might come up while agents assist your end users.
About end-user authentication for messaging
- Increasing confidence that the end users your agents are talking to are who they claim to be.
- Making it possible to identify a single user across channels if you embed the widget on multiple domains or link to external services, such as Shopify.
- Making it possible to identify a single user across different devices and browsers.
Terminology for messaging authentication
- JWT: Zendesk uses signed JSON Web Tokens (JWTs) to authenticate end users for messaging. These tokens contain details that verify the identity of the end users. For more information about JWT, see jwt.io.
- Signing key: A signing key is created by a Zendesk admin in Admin Center and shared with a developer on your team, who then uses it to sign the JWT as necessary.
- External ID: An alphanumeric string, such as a user name or ID from an external system, that is unique to each user. This is the primary identification for messaging authentication, even when an email address is included in the JWT.
- User name: (Optional) The name of the end user associated with the external ID or email address. If you include the user's name in the JWT, it appears in the Agent Workspace. This information can help agents communicate with end users.
- Email: (Optional) The unique email address associated with an end user.
Overview of implementing messaging authentication for end users
- The process of messaging authentication begins with an admin generating a signing key and providing it to a developer. Then the developer uses the signing key to implement a back-end service that can create signed JWTs for users as requested.
- When requested, the back-end service creates and returns signed JWTs to your website or mobile app. The JWTs created by this service must include a unique external ID and, optionally, an email address to identify the end user.
- Any time the user is logged in, your website or app needs to call an equivalent login API available for web widget and mobile SDKs, at which time the JWT is passed to Zendesk to verify the claimed identity of the user.
Requirements for authenticating end users for messaging
- Zendesk Agent Workspace is activated.
- You're using the web widget or mobile SDK channels for messaging.
- You associate email identities with end users.
- If you want authenticated users to have verified email identities, the JWTs you issue to end users must contain both the
email
andemail_verified: true
claims.
Agent experience when authenticating messaging end users
Agents see a green check mark icon next to the visitor's name and the end user's external ID is visible next to the user's profile when the end user is authenticated.
Additionally, each response posted by an end user after they are authenticated has the check mark icon.
Authenticated end user can participate synchronously in a conversation across devices. For unauthenticated end users, separate user records and conversations are created for each device they use. If an end user authenticates mid-conversation, the conversations pre- and post-authentication are automatically merged to provide continuity for the agent and end user.
If you're using email identities, the mapping of end users to user records varies based on your email identity settings. With most configurations, imposters appear as separate user records and won't have the green check mark next to their name because they can't be successfully authenticated. If you permit unauthenticated users to claim verified email addresses, email identities are associated with the first user who claims the address. If two end users claim the same address, the email identity is attached to the user record for the end user who is able to authenticate and verify the email address.
In the event of a conflict, verified email identities supersede unverified email identities. For example, if an unauthenticated user provides an email address that is already associated with a verified identity, Zendesk creates a new unauthenticated session and user record without an email identity for the unauthenticated user who is attempting to impersonate a verified user. Similarly, if an unauthenticated user provides an email address but can't verify it, but later another user provides the email address and is able to verify it and sign in with their JWT, the email identity will be attached to the authenticated user and removed from the unauthenticated user's record.
Agents have the ability to merge duplicate user records and manually add an email identity to user records. We recommend training your agents to perform identity verification checks with end users before taking either of these actions.
End user experience with authentication for messaging
After you implement end-user authentication for messaging, end users shouldn't notice much of a difference. After they have been authenticated and their identity is verified with Zendesk, end users aren't prompted to provide their name or email address by messaging bots as part of the default messaging response.
Conversations for authenticated end users are synced across devices when the end user is authenticated. Separate user records and conversations are created for unauthenticated end users. If an end user authenticates mid-conversation, the anonymous conversation that was created before they signed in is automatically merged with the authenticated conversation to provide conversational continuity.
Creating and sharing a signing key
Signing keys are used by developers to create JWTs for end users. You must be an admin to create a signing key. You can create a maximum of 10 keys. If you attempt to create a new key after reaching your limit of 10, you are prompted to delete unused keys.
- In Admin Center, click Account in the sidebar, then select Security > End user authentication.
- Click the Messaging tab, then click Create key.
If you are creating your first key, Create key appears at the bottom of the page. Otherwise, it appears in the top-right corner.
- Enter a Name for the key and click Next.
- When prompted, click Copy to copy the shared secret and then click Hide key forever.
The key is saved and an ID is automatically assigned. You can find a key's ID in the list of keys on the Messaging tab of the End user authentication page.
- Confidentially send the key's ID and the shared secret you copied to your developer.
Authenticating end users with only an external ID
-
external_id: (Required) This is the unique alphanumeric string that can be used to identify each user. Commonly, these IDs are pulled from external systems. An ID can't exceed 255 characters.
Zendesk uses the
external_id
as the primary identifier for users authenticating over messaging. When authenticating a user with a valid JWT, Zendesk first resolves an existing user with theexternal_id
. If noexternal_id
match is found, users are resolved using the email address provided. See Issuing JWTs with email addresses. -
scope: (Required) The caller's scope of access. The only valid value is
user
. - name: (Optional) The name of the user. Including the name in the JWT payload enables Zendesk to display the user's name in the Agent Workspace and helps your agents provide more customized support.
{
"external_id": "12345678",
"scope": "user",
"name": "Jane Soap"
}
Incorporating email identities into your end user authentication
- Authenticated users are authenticated through signed JWTs.
The use of JWTs provides a trustworthy approach because the content of a signed JWT can't be tampered with by end users. If you're concerned about impersonation attacks, you should restrict email identities to authenticated end users. This is the most secure option and is the default approach for new Zendesk accounts.
- Unauthenticated users are end users who provide an email address in response to a prompt by a Zendesk bot.
Keep in mind that permitting the use of email identities for unauthenticated users can make you vulnerable to people impersonating other users by providing an email address they don't own.
Configuring email identities
On new Zendesk accounts, email identities are on and configured to use only verified email addresses. This is the most secure option. Older accounts are configured to use both verified and unverified email addresses. Before adding email addresses into your JWTs, you should review the options and update your settings as needed.
- In Admin Center, click Channels in the sidebar, then select Messaging and social > Messaging.
- Click Manage settings.
- Click Email identities, and then select one of the following options:
-
Use only verified emails: Email identities are created only for users who are authenticated and have a verified email address included in their issued JWT. Agents can still manually add an email identity to a user record.
With this option, agents see the email address provided by unauthenticated end users in the chat history, but they won't see an email identity attached to the user in the essentials card. If an agent needs to follow up with an unauthenticated user over email, they must manually add the email identity to that user record. If the unauthenticated user's email address already exists on a different user record, the agent has the option to merge the two user records.
Prior to manually adding an email identity or merging two user records, we recommend having your agents perform an identity verification check to prevent social engineering attacks.
-
Use both verified and unverified emails: Email identities are created both for users who are authenticated and have a verified email address in their JWT as well as for unauthenticated users who provide email addresses through bot flows. With this option, agents are more likely to find the end user's email address in the essentials card, and email identities for unverified email addresses are clearly marked as unverified in the Agent Workspace. When needed, agents can ask end users to authenticate if they need to send email follow-ups.
In the event of a conflict, verified email identities supersede unverified email identities.
-
Use only verified emails: Email identities are created only for users who are authenticated and have a verified email address included in their issued JWT. Agents can still manually add an email identity to a user record.
- (Optional, but not recommended) If you want any user, even unauthenticated users, to be able to claim verified email addresses, select Unauthenticated user can claim verified emails.
When you select this option, the verification state of email identities collected from messaging channels is no longer trustworthy because an imposter can show up after a user is authenticated and take possession of their email status in a later messaging interaction. This means impersonation attacks are more likely to succeed and agents have limited means of knowing whether the end user is who they claim to be. However, verified email identities still superscede unverified email identities and the email identity is removed from the imposter's user record.
- Click Save settings.
Issuing JWTs with email addresses
-
external_id: (Required) This is the unique alphanumeric string that can be used to identify each user. Commonly, these IDs are pulled from external systems. An ID can't exceed 255 characters.
Zendesk uses the
external_id
as the primary identifier for users authenticating over messaging. When authenticating a user with a valid JWT, Zendesk first resolves an existing user with theexternal_id
. If noexternal_id
match is found, users are resolved using the email address provided. See Issuing JWTs with email addresses. -
scope: (Required) The caller's scope of access. The only valid value is
user
. - name: (Optional) The name of the user. Including the name in the JWT payload enables Zendesk to display the user's name in the Agent Workspace and helps your agents provide more customized support.
-
email: (Required) The email address of the user being signed in. Must be unique to the user.
Set the email address to the user's primary email address in Agent Workspace. The inclusion of secondary email addresses in JWTs isn't supported.
-
email_verified: (Optional) Whether or not the end user in question has proven ownership of the email address. If you want end users to have verified email identities, the JWTs you issue must contain both
email
and"email_verified": true
claims.
{
"external_id": "12345678",
"email": "janes@soap.com",
"email_verified": true,
"name": "Jane Soap",
"scope": "user"
}
Resolving conflicts between external IDs and emails in JWTs
Zendesk uses the external ID as the primary identifier, with email addresses being used only if no matches are found for the external ID. If, however, an email address presented in a JWT is already associated with a different external ID, Zendesk rejects the JWT and the end user's login attempt fails. When this happens, the conversation begins with the user in an unauthenticated state.
- Update the JWT to use a different
external_id
value oremail
address.OR
- Delete the user with the conflicting
external_id
, freeing it up to be used by a different end user. See Delete User in the Sunshine Conversations API.
158 comments
Mick O'Donnell
Hi Thomas! Apologies for the delay, the developer documentation has now been updated.
2
Alex
Hi team,
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:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImFwcF82MWYyYzQ1MWEzODQ0ODAwZWRmMWU3ZDMifQ.eyJleHRlcm5hbF9pZCI6IjEyMzQ1NmFhIiwiZW1haWwiOiJzb21lQGVtYWlsLmNvbSIsImV4dCI6IjE2NzQ4MzYwODUiLCJuYW1lIjoiSm9uIFdhdHNvbiAxOTg1Iiwic2NvcGUiOiJ1c2VyIn0.RcOsjkbcil5YcmBnZpzsC3do0Q7nYY9-S_P_d-8rJ5Y
Thank you!
2
Alex
Also, the user id is not displayed in the custom ticket field.
1
Mick O'Donnell
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.
2
Kevin Konings
Hello!
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:
29
Jorge Paez
Hi team, is there an estimated timeframe to release the Restricted Articles Access in Messaging for authenticated users?
4
Clayful
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?
3
Kevin Konings
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.
2
Santiago Gandolfo
Hey Kevin Konings, have you received any news?
1
Matt Harrell
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!
4
Jen C
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!
7
Clayful
Hey Jen,
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!
5
Kevin Konings
Hey Jen C,
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.
6
Tim O'Mahony
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.
4
Jen C
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!
2
Ovidiu Varo
Hello guys,
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.
2
Prakruti Hindia
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.
- Prakruti
3
Kevin Konings
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?
Best
2
Flash Coffee Marketing Team
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
Thank you
1
Prakruti Hindia
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.
- Prakruti
1
Prakruti Hindia
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.
3
Mick O'Donnell
Hi Joshua!
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.
1
Mick O'Donnell
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.
1
Abe
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?
Thanks --
Abe
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
1
Santiago Gandolfo
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?
Cheers,
Santiago
6
Justin DoCanto
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.
6
Ovidiu Varo
Hi,
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?
Regards,
Ovidiu
1
Mick O'Donnell
Hi Justin,
This is likely to be an issue with your integration, as I don't believe we've any known issues of this nature on the Web Widget. Do you mind opening a Support ticket at support.zendesk.com please (Messaging icon in the lower right corner), and we'll assist you with this issue.
-2
Justin DoCanto
Hi Mick
Considering the console error I mentioned shows up even when there is nothing but the code I'm provided by Zendesk to install the messaging widget, and the console error is provided by Zendesk code, I completely disagree.
That said, I submitted a ticket. Hopefully, they can be more helpful. Thanks
0
moment long
Zendesk messaging I see doesn't have as many callbacks for us to use as the classic version does.
How do I know when the exp is about to expire and re-call the loginUser APi?
Using a timer to keep track and then calling loginUser is a bad solution
1