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
Anastasiia Kalugina
Hi everyone and Zendesk product team,
I have found that the messaging widget and classic web widget (Enabling authenticated visitors in Web Widget (Classic) – Zendesk help) has similar features related to jwt auth.
Expiration time of token must be within 7 minutes and you should rotate it before its expiration time while chatting.
Why didn't you mention this in the documentation for the messaging widget?
1
Anastasiia Kalugina
And I am also waiting for the "email address mapping feature".
1
Anastasiia Kalugina
Thomas (internalnote.com) Thank you for your article on `internalnote.com`. Very hot topic.
2
daniel carvalho
Hi, I would like to prefill the message for the user. Is that possible?
0
Flora Chen
Hi, Prakruti Hindia Mick O'Donnell
Is there any update on this improvement in the ability to pass the email address for newly created users? We recently changed to messaging channel, this issue affects us heavily. Because we can't send follow-up messages without the user's email in the ticket. That does not make sense. Please solve this issue sooner.
0
Sun, Shuai
Hello Prakruti Hindia, Mick O'Donnell
Our team want to use Zendesk Messaging to instead of Zendesk Chat,
And we have setting it according to the following guide:
https://developer.zendesk.com/documentation/zendesk-web-widget-sdks/sdks/web/enabling_auth_visitors/
https://support.zendesk.com/hc/en-us/articles/4411666638746
Our generated JWT token python script as following:
We use the JWT token like following:
As our expected is 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.
But currently it is still need to input name and email,
Could you please confirm where exist problem for our implements?
And How can we solve it?
0
Sun, Shuai
Hello Thomas (internalnote.com)
By your comment, I have tried to use the new API, and it is OK.
Thank you very much for the help!
0
Hannah Bowers
When will the customer's email address be included in their profile during a chat in the Agent Workspace? Tickets via chat do not have an email and results in the conversations NOT being linked to existing customer records, which also causes the chat to not be persistent for a user. The email is not included in the events of the chat either.
Given that this has been a request for more than a year, and that non-messaging chat could easily capture this, I'm very confused on why Zendesk is not addressing this. Can anyone provide an update and explanation?
18
Rusty Wilson
If the only place we plan to put the web messaging widget in on our help center, and if we assume the customer has logged in to our help center (which I'm trying to figure out how to make a requirement before the widget is shown), do I need to worry about setting up JWT/Authentication since the site will already know who is logged in?
0
Viktor Osetrov
Yes, you should worry about setting up JWT/Authentication on messaging as well. Because unfortunately cross- authentication doesn't work by default between Guide and Web Widget. You should add JWT/Auth for both of them separately or you can build rich end-user experiences directly integrated with third-party systems.
Thank you
0
Anton Maslov
@... Prakruti Hindia can we pass email same way as for Web Widget Classic?
> zE('webWidget', 'identify', { name: `${HelpCenter.user.name}`, email: `${HelpCenter.user.email}` });
0
Jeremy B
When I send name and email in the jwt, when does zendesk update? My user may change their name and I want that to update. Even after calling login again with the new token, it doesn't seem to update.
0
Mick O'Donnell
Hi everyone. Thank you for posting on this topic. For anybody who may be struggling with an implementation issue around JWT authentication, or you suspect a potential issue with the Zendesk Web Widget / Mobile SDKs, could I request that you open a support ticket via support.zendesk.com (chat launcher in the lower right) and we will investigate each case.
We will follow up in the comment thread with responses to general questions where possible. Many thanks!
0
Mick O'Donnell
Hi Anton Maslov, yes this is possible using the Zendesk Web Widget as described here. Here is an example payload:
0
Mick O'Donnell
Hi Jeremy B, no this doesn't happen today. The name value won't modify or overwrite the name stored in Zendesk Support. This is a limitation that we will address in the future.
1
Prakruti Hindia
Hi everyone,
Posting an update on surfacing email address, provided in authentication API, on Agent Workspace. We are targeting Nov to support this enhancement. With this change, external Id, email or a combination of both can be used to uniquely identify your users.
I will provide more updates closer to the rollout date.
- Prakruti
14
Onur Okutan
We appreciate your feedback on this topic and would love to hear more directly from you live. Please join us on Wednesday, September 20, 2023, at 11 AM CDT, for our PM Roundtable on Messaging End-user Experience. It’ll be an open discussion on what is and isn’t working for you in this focus area of Zendesk. So please bring those questions, concerns and feedback because we want to hear from you! The link to register can be found here, we’d love to see you all there.
Best regards,
2
Jean-Philippe Maligne
Hello, I would like to know if we can enable end users authentification for Messaging when users are already logged-in using Single Sign-On (SSO).
The aim is to have 'articles suggestion' made by bot work for non-public articles (Articles having visibility set to Sign-in or base on User-segments). This doesn't seems to be possible for now.
3
Jacquelyn Redington
I have the same question as Jean-Philippe. We use our platform for an internal employee HR support service and we use SSO through Okta. The user will already be signed in, but messaging does not recognize this which creates a new user account for them. When a user has a question that cannot be solved within a conversation or needs to go back to see the conversation, they cannot view it because it is going to their SSO user profile. We try our best to merge the customer profiles created by messaging but if the user comes back and uses messaging, it again creates a new account. A lot of added steps that are needed to do this.
0
Cassie Salgado
We have multiple examples where this occurs without the action of logging in or out. Some other action is randomly causing the ticket to be closed by merge. It's frustrating for agents and end users who lose the connection mid-conversation without any explanation. I've had a long back and forth with Zendesk support, which has not completely solved the problem, as we can't recreate the scenario. It's, as I said, random, leading me to believe it's buggy. Is there any way we can disable this?
0
Kristin Battaglini
Cassie Salgado We are seeing something similar. We haven't seen any tickets closed by merge, but we have seen tickets mysteriously merged without manual intervention, and examples where our conversation bot fires mid-chat as well, and ZD support has said this is due to merging happening in the background. Have you gotten any additional clarity on this?
0
Oscar Mejias
At the moment, the Single Sign-On (feature) works separately and does not influence end-user authentication in the Web Widget. We appreciate the feedback here so that our Product Managers can review it and consider for future implementation.
Thanks!
0
Wathanyoo Khaisongkram
Hi Prakruti Hindia
We are a major retailer from Japan and a newcomer to Zendesk community. Like others, we're also stuck with this limitation on surfacing e-mail address from JWS-authentication. We've been doing PoCs on Zendesk services for a while and this limitation has become a key factor for our decision on adoption of Zendesk.
Regarding your last post that the fix will likely to be on November and as it's now December, so may I ask how it's going with this enhancement support? Any update or outlook would be truly appreciated.
Due to the nature of our business, it is not secured and not efficient to create user profiles in advance on Zendesk for all of our customers, so the workaround which matches user external ID is not realistic for us. The workaround where agents have to merge users for every single request is also not practical at all. Thanks in advance for your response.
15
Mick O'Donnell
Hi Wathanyoo Khaisongkram,
Thanks for that information, that's helpful. I checked internally, and we're currently targeting January for this update of displayed verified email address in Agent Workspace once the end user is authenticated.
3
Sandro Olivieri
Hi Mick O'Donnell,
this means that using JWT to authenticate the messaging Widget, if the user doesn't exists in Zendesk, it is created with email address? Now the email information isn't valued in the created user, according with the current "Email addresses in Agent Workspace" limitation.
Thanks,
Sandro
0
Eric
0
Fien De Paepe
Mick O'Donnell is this targeted begin or end of January to be released?
Kr
Fien
0
Destiny
We're excited about the ongoing development of our new feature that you've expressed interest in. We're working diligently to ensure it provides significant value to our users when it's ready.
However, as much as we strive to deliver it as soon as possible, we don't want to compromise on its quality and performance. Therefore, we are unable to commit to a specific timeframe in January for its release.
We understand the anticipation for this feature and rest assured, we will continue to prioritize its development to deliver a robust and efficient feature.
Once we have a more definitive timeline, we will be sure to communicate this information. We appreciate your patience and understanding.
Thank you for your continued support and interest.
Best regards,
[Your Name]
-2
Blair Robinson
Hello,
I would just like to add that we too have been waiting for quite awhile to see this update of displayed verified email address in Agent Workspace once the end user is authenticated. This has been a blocker for us in rolling out Messaging which is key to unlocking the boasted about Zendesk Bot features. It would be great to see this prioritized sooner than later.
2
Viktor Hristovski
Hi all,
is there any guidance/solution on how to enable sso/Okta login for the messaging widget, if we are using only the default Zendesk Guide page with the widget enabled? Thanks for the help
1