Using email identities to authenticate end users for messaging

Zendesk identities are unique, which means the email identity owned by one user can't simultaneously be owned by another user. This article explains what email identities are, how Zendesk messaging channels collect email identities, and how you can configure your security settings to best use them.

For more information on authenticating end users, see Authenticating end users for messaging.

Requirements and recommendations

Your account must meet the following requirements to use email identities to authenticate users:

Messaging is activated.
Zendesk Agent Workspace is activated.
You issue end users JSON Web Tokens (JWTs). See Authenticating end users in messaging for the Web Widget and mobile SDK.
You associate email identities with end users. You can choose to use email identities with authenticated or unauthenticated users:
- Unauthenticated users are end users that 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.
- Authenticated users are authenticated through signed JWTs. The use of JWTs provides a trustworthy approach because the contents of signed JWTs can't be tampered with by end users. If you're concerned about impersonation attacks, email identities should be restricted to authenticated end users.
If you want authenticated users to have verified email identities, the JWTs you issue to end users must contain both the email and email_verified: true claims.

In addition to the requirements, we also recommend the following when using email identities in messaging authentication.

Depending on your business needs, you may want agents do an identity verification check with the end user before manually populating the email identity in order to prevent social engineering attacks. It is possible for an end user to provide their email address to a bot flow and for that email to not be displayed in the essentials card. This is common for accounts that are configured to Using only verified email addresses. The agent can find the user’s email in the chat history, but they won't be able to follow-up with that user over email unless they manually add the email to the user in Agent Workspace.
Based on your business needs, agents might want to perform an identity verification check prior to merging duplicate records. It’s possible for an end user’s email to be absent from the essentials card and already taken by a different user. This is a common occurrence for unauthenticated user with an account configured with Using both verified and unverified email addresses. This occurs when a user has authenticated in the past, then later reaches out and provides their email address on a different device without first authenticating. Again, the agent won't be able to send email follow-ups for that ticket. To solve this problem, agents have the option of asking the end user to authenticate, or they can manually merge the two duplicate user records together.
Only use the user’s primary email address inside of the JWT email claim. Agent Workspace allows agents to add one or more secondary email addresses to an end user. However, authentication in messaging doesn't support the option of including secondary email identities inside of issued JWTs.
Use 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 the external_id. If no external_id is found, users are resolved using the email address, if provided.
Set the email claim issued in a JWT to match the user’s primary email address in Agent Workspace. If a secondary email is included, it can lead to issues because the user in Agent Workspace is resolved by the external_id, not the email address. The email inside of the JWT payload populates an end user’s primary email address at creation time, however it isn't intended to serve as a means of synchronizing changes to user data. Updating a user’s email address must be done separately, either in Agent Workspace, or by using Update Users.

Creating email identities

Within Zendesk Admin Center, there are three options for creating email identities:

Using only verified email addresses
Using both verified and unverified email addresses
Allowing unauthenticated users to claim verified email addresses

Using only verified email addresses

Requiring verified emails is the most secure option. This is the default approach for new Zendesk accounts. With this method, the following is true:

Email identities are created only for users who are authenticated and have a verified email address included with their issued JWT.
When agents see an email identity in the essentials card, they can be confident that the user they are talking to is the legitimate owner of that email address.
An attacker, whether they are authenticated or unauthenticated, can't impersonate a user by providing their email address over messaging. If they try, the agent sees two separate user records and the email identity is attached to the real user.
The only way for an email identity to show up as a result of a messaging interaction is for the email and email_verified: true claims to be included in the end user's JWT. However, agents can manually add an email identity onto a user record.
For unauthenticated users, the agent sees any email address provided in the chat history, but they won't see an email identity attached to the user. If the agent needs to follow-up with the user over email, they must manually add the email identity to that user record. If the unauthenticated user’s email already exists on a different user record, the agent has the option of merging the two user records together.

For example, suppose Alice interacts with a messaging bot and both email and email_verified: true are included in her JWT. If Alice later logs into a different device and begins a new messaging interaction, as long as the external_id of her JWT matches, the agent sees a ticket associated with the same Alice as before.

If Alice has an issued JWT, but it doesn't have a verified email address in it, then a user record is created for her without an email identity. Similarly, if a Zendesk bot flow later asks Alice for an email address, the agent sees this request in the chat history but the email identity isn't listed in Alice’s user record.

Now, suppose your organization later assigns an email address to Alice, has her verify ownership of it, and then issues a new JWT that includes the email address. The next time Alice interacts over messaging, the agent sees a new email identity has been added to the existing user record in Zendesk.

Finally, consider the scenario when Alice is an unauthenticated user. That means she doesn't have a JWT or verified email address. In this case, the user record that the agent sees is tied to the Alice’s device rather than the email address that she provided in a Zendesk bot flow. For example, if Alice initiates two unauthenticated conversations, one from her laptop and one from her mobile phone, the agents sees Alice’s name and chat history with two versions of Alice.

Using both verified and unverified email addresses

With this option, verified emails included inside a JWT populate email identities just as they did with Using only verified email addresses, but now unverified emails provided to bot flows can also populate email identities. Email identities with unverified email addresses are marked as unverified in Agent Workspace.

With this approach, the following is true:

Agents can inspect the verification state of an email address received over messaging. Notice the warning icon next to the primary email for an unverified user.
Email identities are unique, and in the case of a conflict, verified email identities supersede unverified email identities.
Agents are more susceptible to impersonation attacks because the end user has direct control over what email address is displayed in the essentials card.
Agents are less likely to find the end user's email address missing from the essentials card.

For example, if an impostor starts an unauthenticated session and types in Alice’s email address, Zendesk notices that the provided email identity is already verified and owned by Alice. Instead of resolving the impostor's ticket to Alice’s legitimate user identity, Zendesk instead creates a new user record for the impostor, without any email identity.

Suppose the imposter enters Alice's email in an unauthenticated session before the real Alice is in the system.

In this scenario, the agent sees Alice’s email address in the essentials card, potentially leading them to the assumption that they are indeed communicating with Alice. However, the agent should always examine the user record directly to see if the email identity is verified. The agent can also trigger an email verification flow to help prevent a potential identity impersonation.

Now suppose the real Alice later signs in using a JWT issued to her, containing her verified email address. Zendesk notices that the email identity has already been claimed. Because the email identity is unverified, Zendesk resolves the conflict by removing that identity and attaching a verified identity to Alice’s legitimate user record.

Allowing unauthenticated users to claim verified email addresses

This option is the least secure and most susceptible to impersonation attacks. With this approach, the following is true:

In the case of a conflict, verified email identities supersede unverified email identities.
Agents can still rely on the green check mark in the essentials card and converation log to verify whether the end user's session is authenticated.
End user can assume the identity of any authenticated user by typing in that person’s email address when prompted by the bot flow.
The verification state of email identities collected from messaging channels is no longer trustworthy because an impostor can show up after a user is authenticated and take possession of their email status in a later messaging interaction.
When any user provides an email address to a bot flow, the agent always sees it reflected in the essentials card.
Impersonation attacks are more likely to succeed and agents have limited means of knowing whether the end user is who they claim to be.

For example, suppose an impostor enters Alice’s email address in a bot flow. Zendesk attributes their ticket and interaction history to Alice’s existing user record.

The impostor won't have a verified green check mark in the essentials card because the email address they provided is unverified.

Suppose Alice isn't in the system and an impostor uses her email address in a bot flow.

When the real Alice later authenticates herself, the conflict resolves by creating a new user record for Alice with a verified email identity and removes the email identity from the imposter record.

However, there is nothing to stop the imposter from starting a new messaging interaction and claiming Alice's email address as they had done before. In this case, Zendesk again attributes their ticket and interaction history to Alice's existing user record.

Configuring email identities

To select the type of email identity to use:

In Admin Center, click Channels in the sidebar, then select Messaging and social > Messaging.
Click Manage settings.
Select the appropriate option and click Save.

Resolving email conflicts

If the email address presented in a JWT was already associated with a different external_id, then the JWT is rejected and the end user’s login attempt fails. Instead, the Web Widget initializes in an unauthenticated state.

There are two ways to correct this issue:

Change the external_id or email in the issued JWT to a value that doesn't conflict with existing users.
Delete the user holding the conflicting external_id via the Sunshine Conversations Delete User API.