When you provide conversational support, users might try to carry on a conversation across multiple devices and channels. By authenticating 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.
- Terminology for messaging authentication
- Overview of implementing messaging authentication for end users
- Creating and sharing a signing key
- Authenticating end users with only an external ID
- Incorporating email identities into your user authentication
- Resolving conflicts between external IDs and emails in JWTs
Related article: Understanding user authentication for messaging.
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 an 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
Zendesk uses JSON Web Tokens (JWTs) to authenticate messaging end users, which provides a flexible and stateless way to verify user identities and secure API endpoints.
- 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.
- Anytime 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.
For more information, particularly for the developers on your team, see Enabling authenticated visitors for messaging with Zendesk SDKs or watch the following video:
Authenticating end users in web messaging (17:22)
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.
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.
- Click Hide key forever.
Authenticating end users with only an external ID
To authenticate an end user, you must supply an external ID in the JWTs you issue to users. Zendesk uses the external ID provided in a JWT as the primary identifier for user authentication for messaging. When performing the user authentication, Zendesk first resolves an existing user with the external ID. If an email address is included in the JWT, it is used to resolve user identity only when no existing users match the external ID.
Signing JWTs with an external ID only
- external_id: (Required) This is the unique alphanumeric string that can be used to identify each user. See Selecting the external ID to use in JWTs issued to users.
-
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 allows 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"
}
Selecting the external ID to use in JWTs issued to users
- An external ID must be an alphanumeric string.
- External IDs can be a maximum of 255 characters.
- Each user's external ID must be globally unique at the account level.
If your account has multiple brands, external IDs must be unique across all brands.
- A user's external ID should never change.
- A user can have only one external ID assigned to them.
Some examples of good choices for external IDs include: an incremented or randomized ID assigned at initial contact (example: usr_12345) or, for multiple brands, a brand-specific identifier combined with an incremented or randomized ID assigned (example: brand1_a8dedg).
Avoid using the user's email address and phone number because these can change over time and users can have multiple values. Also avoid the user's name, since this may not be unique.
Incorporating email identities into your 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 configuration 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.
The following flow chart demonstrates how email identities can be used in your messaging authentication:
Configuring email identities
With the Web Widget or mobile apps, users can provide their email address in response to a form or AI agent prompt. In these scenarios, there's nothing preventing a malicious user from providing someone else's email address in an attempt to impersonate them. However, using JWTs to authenticate users with both external IDs and email identities is a more trustworthy way to assign email addresses to users.
Depending on your settings, agents could see both form-collected and JWT-provided email addresses in user profiles. On new Zendesk accounts, email identities are turned 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.
- 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: (Default) Email identities are created only for users who are authenticated and have a verified email address included in their issued JWT.
- Use both verified and unverified emails: In addition to the email identities for authenticated users with verified email addresses being visible in user profiles, unverified email addresses provided by users through AI agent flows are also added to the user's profile.
- (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.
- Click Save settings.
Using only verified emails
Email identities are created only for users who are authenticated and have a verified email address included in their issued JWT.
With this option, agents see the email address provided by unauthenticated end users in the conversation history, but they won't see an email identity attached to the user. If an agent needs to follow up with an unauthenticated user over email, they must manually add the email identity to that user record.
Using both verified and unverified emails
In addition to the email identities for authenticated users with verified email addresses being visible in user profiles, unverified email addresses provided by users through AI agent flows are also added to the user's profile.
This option is less secure because malicious users could still attempt impersonation attacks. However, agents can inspect the user profiles to determine whether an email address is verified. Unverified email addresses are clearly marked in the Agent Workspace. When agents need to send email follow-ups, they can be instructed to verify end users with security questions to increase confidence that the end user is who they say they are.
Event order | Event | Resulting email identity |
---|---|---|
1 | An unauthenticated user provides a form-collected email. For example, alice@example.org | Zendesk creates a new, unauthenticated user (id: 12345) with the unverified email identity (alice@example.org). |
2 | An authenticated user is issued a JWT with the following
claims:
|
Zendesk creates a new, authenticated user (id: 22345) with
a verified email identity (alice@example.org). The unauthenticated user (id: 12345) loses its unverified email identity because it was superseded by a verified identity. |
Allowing unauthenticated users to claim verified emails (not recommended)
In contrast to the other email identity options, this setting allows users to assume the identity of authenticated users simply by providing that user's email address when prompted. When selected, verified emails don't supersede unverified emails.
This option is the least secure and most susceptible to impersonation attacks. However, diligent agents can still detect potential imposters in this scenario by looking for the green check mark icon on the user's profile and next to their messages, which indicates whether the user is authenticated.
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 supersede unverified email identities and the email identity is removed from the imposter's user record.
Issuing JWTs with email addresses
- external_id: (Required) This is the unique alphanumeric string that can be used to identify each user. See Selecting the external ID to use in JWTs issued to users.
-
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 allows 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 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.
It's best to implement messaging authentication with conflict-avoidance in mind. For example, pick your external IDs and email settings in Zendesk to ensure they can't conflict. 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
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
5
integracao_operador_getrak
Hi Prakruti Hindia
When a user sends a widget message and its external_id is set by a JWT authentication, if there is already a user with the same external_id in the base (in the case of a base import, for example), will the application create a new user instead of linking it to the existing one?
3
Piotr Jaworski
So I've implemented the backend functionality to provide a signed JWT to the client part of the application, then I use the Web Widget API (https://developer.zendesk.com/documentation/zendesk-web-widget-sdks/sdks/web/sdk_api_reference/?_ga=2.111275911.280573301.1649945109-889103865.1649945109#authentication) to log the user in, after which in the response I can see that the JWT was successfully decoded. Yet, the `name` and `email` don't get pre-filled in the chat - should I somehow retrieve the users' Zendesk ID in our client application and add it to the JWT? I'd assume that this is the role of the Web Widget API... What might I be doing wrong there?
0
Don Pham
Hi Zendesk team,
I using widget classic and facing this issue when I called API: https://id.zopim.com/authenticated/web/jwt and I got this error: "error fetching shared secret"
I generated SHARED_KEY in https://textback.zendesk.com/admin/account/security/end_users#messaging . Its right?
0
Danny Larsen
Did anyone solve the issue with not linking users?
We are also trying to create users via the APi with email and external_id and then identify them via a JWT token. But that just creates a new user without the external_id.
Pretty useless without this.
1
Kevin Konings
Danny Larsen we haven't, and since then also moved on to a different solution.
For us being able to link users in live support use cases to our customer base is absolutely crucial. Neither this thread nor Zendesk Support had yet provided a satisfactory answer to even whether the fact Zendesk Messaging creates duplicate users with not even the external ID but also the same email address is known behaviour, a bug of Zendesk, or should not happen and we were doing something wrong.
The only feedback so far is that users will be "merged" as soon as the improvement goes live, with no further information on what this means in terms of data conflict resolution, etc.
It's disappointing there is such a lack of transparency for what probably comes down to the main use case of this feature for most people.
2
Prakruti Hindia
Hi Santiago, this will be rolled out in early May.
- Prakruti
1
Prakruti Hindia
Hi all,
Wanted to drop an update and provide more information on the upcoming fix (early May). Currently, the external id is surfaced on hover over the authentication badge. With the fix, the external id will be surfaced against the external id field in the user profile. If there is an existing user with the same external id as provided via API, the messaging ticket will reference the existing user.
We will be adding details on conflict resolution to this article once it is rolled out.
- Prakruti
2
Zakhar
Hello, Prakruti Hindia
Just wanted to inquire about `external_id` `JWT` issue.
Upcoming fix planned to early May - was it rolled out?
Or, when can we expect it?
2
Santiago Gandolfo
Hi Prakruti Hindia, has the external_id fix been postponed?
Cheers!
1
Amy Spagnolo
+1 on the above, any news? It is causing a very bad experience for our customers and we're getting complaints because we don't auto auth through the widget.
0
Prakruti Hindia
Hi everyone,
Apologies for the late response. I was hoping my next update would be a positive one. Unfortunately, it is taking longer than expected to roll out external id in user profile. I will update this thread in a few days with target rollout timeline.
Currently, external id is displayed on hover over the authenticated badge - https://support.zendesk.com/hc/en-us/articles/4411666638746/comments/4433112143130. (For new followers / readers of this post)
- Prakruti
0
Ahmed Ur Rehman
https://support.zendesk.com/hc/en-us/community/posts/4640250446362-401-Unauthorized-Login-via-Messaging-SDK
Receiving 401 Unauthorised error when attempting \
0
Mick O'Donnell
Hi Ahmed,
Thanks for writing in! I've replied on the post that you have linked to.
1
Shayan Moussawi
Hello Prakruti Hindia,
Do you have a target rollout timeline for associating authenticated end users with already created end users via the external ID?
This is really a key feature, without it, authentication kind of seems pointless, as all Tickets created with authentication will not be properly linked to the end-user with contextual information etc.
5
Zakhar
Hello,
Prakruti Hindia, is there any update on the fix rollout time?
We ve prepared a feature within our App, that is blocked by the fix - we are waiting for it.
2
anna.kalinichenko
Hi Prakruti Hindia
I'm joining all the previous inquiries on the date of the fix. I would appreciate knowing at least if this isn't something that's going to happen this month, so that we wouldn't wait in vain and move to another solution.
Thanks
1
Francis Morissette
Prakruti Hindia
It seems that the email is not carried over from the JWT to the created profile when Messaging with authentication is enabled. The external_id does show, but the email is not added to contacts, AND it creates a duplicate user instead of using the user with the same email that already exists. See ticket ID #10490436
3
Prakruti Hindia
Hi folks,
Wanted to drop a general update for associating external id with user profile and connecting messaging conversations to users based on it. This is our top priority and we are working on it. It is taking longer than expected. We understand it is critical to your workflows. I will drop an update soon with our new timelines.
- Prakruti
0
Ran Geller
After implementing end-user authentication, we experience the same situation - the end-user email is not captured.
It is annoying as it is impossible to switch from messaging to email and have unread messages automatically emailed when the end-user leaves the messaging session.
To overcome this, we configured the external_id to have the email, and the agent must copy it when hovering over the authentication badge and then update it in the end-user profile.
What is the ETA for removing this limitation?
2
Zakhar
Hello Prakruti Hindia,
Could you please share us with updates if they are since latest news at June 15.
3
Zakhar
Hello, Prakruti Hindia
Could you please share any news about the issue and it's resolution?
It's already 3 weeks passed since latest updated.
We are blocked waiting for the fix.
5
Prakruti Hindia
Hi everyone,
Thank you for your patience. As I mentioned earlier, we have prioritised support for external id, which will associate external id with user profile and connecting messaging conversations to users based on it. We are targeting early Aug for the rollout. This will not include support for email. I will provide an update on email at later date.
- Prakruti
1
Carlton
We're not even seeing the badge. Login is returning success with a correct externalId value on the swift object, but I don't see the badge in the dashboard anywhere.
0
Zakhar
Hello, Prakruti Hindia
Are there any updates, timelines?
Please share some insights, so we were calm.
Even though the fix is really hot topic for us.
2
Anthony Moynet
Why I didn't see any Messagin tab in Account > Security > End-user ?
0
Jo Warren
Justin DoCanto - Did you ever figure out your issue? I'm having a very similar problem. Get an error unless I wrap the auth function in a try/catch and the auth itself isn't working. The function IS running though because I can hit the debugger if I put it right before the callback.
0
Valentin Cardozo
Hi, I would like to consult as Jorge Paez in what time frame you plan to implement the authentication to view the articles of the Zendesk Guide?
I would need this functionality so that my customers can see the documentation generated in the Guide about the use of my software.
I look forward to hearing from you!
Regards
0
Dainne Kiara Lucena-Laxamana
Hi Carlton
I went ahead & created a ticket on your behalf to look into what is happening with the badge. Please keep an eye out for our email so we can look into this further for you!
0
Santiago Gandolfo
Hi, Prakruti Hindia
Are there any updates?
1