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
Prakruti Hindia
Hi everyone,
External id is now available in user profile for authenticated end-users. This improvement was rolled out in the week of Aug 23. I wanted to ensure that everyone following this discussion received the update.
Thank you all for your patience. If your team is unable to view external id and you have raised a support ticket, we will help you resolve it.
- Prakruti
0
Francis Morissette
Unfortunately, all the limitations here make it so that we cannot enable Messaging. The name and email is not carried over when the ticket is created, and private guide articles are not referenced when a customer is authenticated to the widget.
Such a downer
2
Chin Sin
Hi Aimee Spanier, I noticed that the diagram in the Overview now includes Mobile SDK.
Previously the Mobile SDK has a different JWT flow where Zendesk will request the JWT token from our back-end.
1. Based on the updated flow, does it mean now the Mobile SDK also has the same JWT flow as messaging?
2. Is the primary key also using external_id ?
3. If I submit a request via Mobile SDK, and also trigger a request via messaging, will both requests be tagged to the same user profile?
1
Chin Sin
Hi,
In my sandbox environment, I am able to login using JWT and able to obverse the user profile has the name and external_id that I set in the JWT token.
But in the production environment, I am not able to see it. From the logs, there are no error. Is there a way to check the Zendesk logs if the API is called successfully? I have engaged the support but the forum or blog.
If you have any additional questions, we recommend reaching out through the web and possibly by joining our developer community Forum (https://support.zendesk.com/hc/en-us/community/topics), Blog (https://developerblog.zendesk.com/) and/or Slack (https://docs.google.com/forms/d/e/1FAIpQLScm_rDLWwzWnq6PpYWFOR_PwMaSBcaFft-1pYornQtBGAaiJA/viewform) as this is the venue where you can reach out directly to our developers.
0
Zakhar
Prakruti Hindia
Issue is still there.
Users are not mapped correctly (a new duplicate user gets created once initiated Messaging session).
It's very sad. So much time we were waiting for the fix.
Guys, do anybody can claim opposite - that issue had been fixed?
1
Danny Koss
I can confirm that the messaging authentication is working as designed and conversations from users who have existing end-user profiles are being merged into that profile with the corresponding external ID in our Zendesk environment.
0
Prakruti Hindia
Francis, support for signed email is on the roadmap. Are you referring to carrying over private guide articles to the tickets ?
Yes, this is intended behavior.
Previous data - users and tickets will not be affected, if you decide to disable authentication.
We do not support this.
Ong Chin Shin and Zakhar, can you please raise a ticket with us ? We will look into it.
- Prakruti
0
희승 이
Hi Zendesk team
web widget - login jwt payload was sent along with the email value, but we found an issue where the value was not saved.
Is the email value of null intentional? Or is it a bug?
step to reproduce
{ scope: 'user', role: "end-user", external_id: userEmail, email: userEmail, name: userName };
https://{{domain}}support.zendesk.com/api/v2/users
body:
email value is null
1
Amie
Prakruti Hindia
Are you able to provide any kind of timeline for support for signed email (which you mentioned is on the roadmap)? This becomes a much, much larger implementation for us without it.
1
Trudy Slaght
For those who found alternatives, will you please share what you used instead of this? It appears the email issue isn't going to be resolved soon and I don't see the value in this if we lose the fallback email options and all of the connected ticket history.
Also, is anyone else having issues with their bot re-initializing anytime the page is loaded, even after a conversation has been handed over to an agent? The history of the conversation remains present - but if you refresh the page, the bot re-starts from the beginning flow as if it's a brand new inquiry. This behavior is not present where we use the widget without authenticating users so I don't understand why it's happening when authenticating a user.
I opened a ticket but estimated response was 2 days so hoping someone else may have some insight.
0
Jen C
Does anyone have authenticated users set up for messaging that can tell me if this is working now?
By working I mean, when a customer is authenticated in messaging/web widget with the bot and is then transferred to an agent, does that messaging ticket get linked to a user account in Zendesk and show the customer's email address/user account in the requester ticket field?
We would love to implement this, but I am unsure if the problems were resolved. We need those tickets to come in attached to a user or have a new user created, just like tickets from other channels. Thanks for your help! - Jen
0
Trudy Slaght
Hi Jen C - it is not working for us. Authenticated users come in without a name or email address, although the authentication is working based on the end user not being asked to enter their name or email. We are having issues with the bot re-launching on page refresh even though the history is brought in and I believe it's linked to the behind-the-scenes merge that is happening and the end user not being identified as having already been handed over to an agent. Perhaps someone else has additional details - I have an open ticket with ZD but am waiting for a reply still.
4
Raphaël Péguet - Officers.fr
The big lack of info of this article is how to use in the flow builder infos that we've loaded/got by authentification..
A placeholders reference (such as {{sf.requester.email}}) would be most welcome
To be able to say "Hi {{requester.first_name}} how can I help you" for instance.
2
Francis Morissette
Raphaël Péguet - Officers.fr I wasn't even aware that we could do this within our workflows... that would open a lot of possibilities.
0
Dmitriy Cherchenko
We're still waiting for the feature where an authenticated end-user's email address is displayed in the Zendesk chat UI.
3
Sergio Bellon Alcarazo
HI Prakruti Hindia,
Is there any news on this bug? is your team working on it? there are already 82 comments of people blocked and we haven't heard from you in a while. It's been almost a year since we identified this issue.
Can we organize a meeting with our developers to help? please give us any deadlines, we choose Zendesk to use the Guides for only logged-in users and we still can't use it.
Thank you,
Sergio
3
Prakruti Hindia
Hi everyone,
Wanted to chime in on the discussions here.
For cases where email is the primary identifier, I suggest passing email as external id. If the system finds another user with the same external id , it will reference the same end-user. Currently, the email value is not passed along. It is expected to not be able to retrieve email user using the Users API.
Surfacing email provided as part of authentication API is on the roadmap and are targeting Q1 for the rollout.
- Prakruti
0
Sergio Bellon Alcarazo
Hi Prakruti Hindia ,
Our primary identifier is not the email, it's our internal ID. We have tried to pass it on the external id and it doesn't work either. Any other work around?
Thank you,
Sergio
0
Daniel Jones
Hi Sergio,
Just to add our experience. We've been aiming to use Zendesk Messaging for a long time now. Initially the main blocker was the lack of authentication (and so there would have been no way for our agents to know who a customer was without asking them - a non starter).
Following the release of authentication support, the next issue was that the "external_id" wasn't surfaced by the API (like you describe, we are setting this to our internal id for a user).
The "external_id" that you supply as part of authentication is now surfaced from the Zendesk Support API on the user object as of mid August this year.
We already have an internal app/plugin that we have written for Zendesk Support which fetches user details, order history etc from our CRM and displays it to our agents. Now that the "external_id" is available, we can use that - and so our plugin displays the customer name and email address to our agents.
Creating a Zendesk Support app/plugin is perhaps not the workaround you are looking for but it's definitely a solution. There are other benefits in being able to surface any information/context you want to your agents all within Zendesk Support.
Our thoughts are that Zendesk Messaging has been very much a work in progress/draft since it was released, and prior to August this year pretty much unusable for anything real (unless you want a terrible customer experience).
It's now usable we think with the above caveat, but still not an out-of-the-box solution. The improvements are arriving slowly, this is definitely "the future". We've evaluated a lot of alternatives to Zendesk and they all seem to fall short in other ways (lack of native mobile SDKs, lack of support for particular channels etc) so I think Zendesk is the most comprehensive solution.
Hope this is helpful.
Thanks,
Daniel
1
Abdurasul Rustamov
Hi! We are using jwt sso for messaging to authenticate users who use our mobile app. Currently we have faced a problem with end users created with random names in tickets. In zendesk admin panel > Customers section new users are being created as for example Visitor 88802267, but in jwt we are sending user name and email that user has in our mobile application. Before using jwt sso users would enter their name and/or email (in ios) and ticket would be created with name user entered, and then we decided to enable sso to use same email and name as in our mobile application. JWT generate process works as follows:
1. User signs in in our app.
2. Application sends GET request to our api that we developed in our backend with following data in payload -> user's name and email
3. API generates jwt and responds
4. Mobile application (which is written in Flutter) calls ZendeskMessaging.login() and sends jwt that it got from api request as paramater for login() method
5. zendesk messaging page opens and user starts conversation
Here is the example jwt token that is generated: eyJhbGciOiJIUzI1NiIsImtpZCI6ImFwcF82Mzg5OTcxNjdlM2NiMzAxMDVjMWJiODIiLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6InVzZXIiLCJuYW1lIjoidGVzdCIsImVtYWlsIjoidGVzdEBtYWlsLmNvbSIsImV4dGVybmFsX2lkIjoiODNjODA5NzItMjNmNi00MGU2LWEzNGItOWU2MmViYzhjZDRjIiwianRpIjoiZjRhZjg4NjAtMzg0OS00OGQ1LWI0Y2YtZTZmMmU3ZjEyZmZiIiwiaWF0IjoxNjcwMDY5MDI0fQ.HISo3nXh_4Egr80ffxwLsDUBSlbYqi5sPkkhZWyBxdE
We didn't quiet understand what is login redirect url is and that's why we just respond with jwt itself. Is it because we are using jwt sso incorrectly?
We were trying to view tickets in salesforce and we did manage to view, but after enabling jwt sso, tickets stopped being viewed in salesforce. I guess it is because the problem with users being created as Visiter + some random numbers.
Could you please help with finding what is the problem?
0
Nara
0
Eric
Anyone else getting a random name (ex. Visitor 66340348) for the user even though a name is in the token? The name seems to be received on Zendesk's end since the chat has a message saying "Changed their display name to ...", but the name is not actually changed.
2
Craig Obee
Hi Prakruti Hindia,
Could you please confirm if the email address being passed through is on track to be completed in Q1?
2
Grant Martin
I'm having the same issue Eric. No matter what I do everything comes across as Visitor and some numbers.
I also can't figure out how for new conversations to appear in a separate ticket from the same authenticated user. Marking as solved, closing the chat on the user side, waiting over 10 minutes doesn't make a difference, it always just re-opens the original already Solved ticket.
0
Dinesh Reddy
Is there a roadmap when the current limitations will be resolved? Like email address mapping to existing user?
0
Paul
Hi,
Hi, as per this article when do you think realistically the email address will be included in the newly created contact. This is important for us before we go live with chat on our site and we have been told on numerous occasions that this is coming soon but over a year later this is still a problem.
When a user of our site is logged into our site and engages with ZD messaging, we log them into the Zendesk chat using a JWT token that contains name, email and external Id.
Whilst the name and external id are set, the email address is not and it is vital to our operations to ensure this is automatically set rather than our agents having to manually set it which is both error prone and time consuming.
Please can you give an update on this work with a realistic timeframe for it being implemented?
Thanks
1
Tim M
It is now Q2, is there any update on this improvement for the ability to pass the email address? The metadata is now available in flow builder, how come it cannot pass into agent workspace?
2
Simon Gellis
Our organization found another workaround for passing in the email address: before authenticating to messaging, we generate the token used for SSO authentication, and have the browser make a call to the Zendesk JWT SSO endpoint https://support.zendesk.com/hc/en-us/articles/4408845838874-Enabling-JWT-single-sign-on#topic_w5x_1fh_3fb (in no-cors mode, ignoring the response). We also set the same externalId for each user on both SSO JWTs and messaging JWTs.
The end result is that anyone signing into messaging has their account linked to the one used by SSO, and the email shows up as you'd expect.
2
Shayan Moussawi
Thomas (internalnote.com) You need to use external ID to match users with one another.
When a user is created in your system, you need to create it in Zendesk with the given external ID from your system. Meaning, you need to use the Create or Update API endpoint, to create a user in Zendesk every time a User is created in your system.
When a user signs into messaging and is authenticated using JWT, you need to pass external ID as a parameter.
This will automatically merge the User that just signed in, with the user that is already created in your system, linking the Messaging Ticket immediately.
To circumvent Zendesks implementation of the JWT authentication, I'd also recommend always having a User Create or Update Call before passing the JWT auth.
This will guarantee that even if a new user is logged in through Messging, the user is first created with his Email and external ID, and then can be merged into for future Messaging conversations.
0
Shayan Moussawi
Thomas (internalnote.com) Wow.
I just watched your video and I am stunned by how this feature is still not properly implemented yet. I am glad I postponed our implementation after taking an initial look at it.
My impression was, and even from reading the support article, this is the behavior I would expect, is that once a user authenticated through messaging, a user is with an external_id is created in Zendesk, and merged into potentially an existing user (if that existing user shares the external_id).
The current state of the implementation seems like a bit of a mess, since the "external id" that is shown... is not actually an external ID as you would expect in Zendesk. It's just the SunCo external ID surfaced next to the user...
0