Authenticating End Users in Messaging for Web Widgets and Mobile SDK – MatrixCloud

Original document: Authenticating End Users in Messaging for Web Widgets and Mobile SDK

Companies using Zendesk can verify the identity of end users through end user authentication before starting messaging conversations. This allows agents to confidently know the identity of the supported user and easily access past conversations, potentially sharing sensitive information more securely. End users can continue conversations across multiple devices, browsers, and channels and view past conversations.

Note: Currently, end user authentication in messaging is only available on web widgets and mobile SDK channels.

This document is for Zendesk administrators. For information on necessary tasks for developers, please refer to Enabling Authenticated Visitors.

The topics covered in this document include:

Information on End User Authentication in Web and Mobile Messaging

End user authentication is simply verifying the identity of the end user. This allows new messaging requests from verified end users to be linked to past conversations, enabling agents to provide better support.

This section covers the following topics:

Understanding Key Elements

To understand how end user authentication works in messaging, it is important to be familiar with the key elements involved in the authentication process.

JSON Web Token (JWT) for authentication: Zendesk uses signed JSON Web Tokens (JWT) for authentication in messaging. These tokens verify the identity of the end user. For more information on JWT, please refer to jwt.io.
Signing key: The signing key is created by the Zendesk administrator in the admin center and shared with developers, who will use it to sign the JWT as needed. Creating and Sharing a Signing Key can be referenced.
Unique user identifier or external ID: An alphanumeric string unique to each user (e.g., username or customer ID number).
Username (optional): Including a name can help agents communicate with the end user. If this information is collected and included in the JWT, it will appear in the agent workspace. However, it is not required.

Overview of the Setup Process

To enable end user authentication, a Zendesk administrator must first create a signing key in the admin center and provide this key (including the secret key) to the developer. The developer then needs to implement a service in the business's backend that creates a signed JWT to return to the website or mobile app upon request (see steps 1 and 2 in the image below). Each time a user logs into the website or app, the developer must call the equivalent login API provided in both the Zendesk web widget and mobile SDK. The JWT is passed to Zendesk to verify the claimed identity of the user upon login (see step 3 in the image below).

Impact on End User and Agent Experience

Once authentication in messaging is implemented, there will be some changes in the user experience for both end users and agents.

End users: When end users are authenticated and their identity is verified with Zendesk, they will not be prompted to enter their name and email address by the messaging bot as part of the default messaging response.
Agents: Verified end users will be identified by an authentication icon in the agent workspace. Agents can see the external ID as part of the end user's profile.

If the external ID provided via the API matches an existing user's external ID, the messaging ticket will reference the existing end user.

When end user authentication occurs:

A new end user is created. Messaging tickets for anonymous users are linked to the newly created user by external ID.
If the authenticated end user has any open messaging tickets, those tickets will be updated with the new message.
When an end user logs out, a new end user and new messaging ticket will be created for subsequent conversations.

For example:

End user A sends a message without logging in. User 1 and ticket 1 are created.
End user A logs in during the conversation. User 2 is created with an external ID (if no user exists with that external ID).
The conversation continues on ticket 1, and the requester is updated to user 2.

For authenticated returning users, background ticket merging ensures continuity of the conversation. For example:

End user A opens ticket 1 as an authenticated user.
End user A logs out.
End user A sends a message without logging in. User 2 and ticket 2 are created.
End user A logs back in during the conversation. Authenticated user A is retrieved via the external ID, and the anonymous and authenticated conversations are merged.
The conversation continues on ticket 1, and ticket 2 is closed. Working with Authenticated End Users in the Zendesk Agent Workspace can be referenced.

Creating and Sharing a Signing Key

As mentioned in the section above, a Zendesk administrator must create a signing key and share it with developers for use in the JWT. You can store up to 10 keys. When you create a signing key, the messaging metadata variables will also be enabled in the flow builder.

To create and share a signing key, follow these steps:

In the admin center, click on Account, then select Security > End User Authentication.
Click the messaging tab, then click the Create Key button. If this is your first time creating a key, this button will appear at the bottom of the page, and if you have created keys previously, it will appear at the top right.
In the Create New Key dialog, enter a name to identify the key, then click Next.
In the Copy Shared Secret Key dialog, click Copy to save the secret key to your clipboard, then click Hide Key Permanently.

Return to the messaging tab, and a new key will appear in the signing key list with the first 6 characters of the secret key displayed.
Encrypt and send the key ID and shared secret key to the developer for use in creating the JWT. For more details, refer to Enabling Authenticated Visitors.

If you generate a new key but have reached the limit of 10 keys, you will be prompted to delete unused keys.

To delete unused keys, follow these steps:

In the admin center, click on Account, then select Security > End User Authentication.
Click the messaging tab.
Hover over the key you want to delete, click the options menu icon, and select Delete.
Click Delete Key to confirm the action.

Current Limitations

The current version of end user authentication in messaging has the following limitations.

Limited Guide documents: Guide documents that require authentication will initially not be accessible even if the user has been authenticated. We plan to implement additional enhancements to the messaging product to allow users to view Guide documents that require authentication. Documents that do not require user authentication will not be affected.
Email address in the agent workspace: Initially, the end user's email address will not be visible in the agent workspace. We are actively working to remove this limitation. Once this limitation is removed, businesses that want to see the user's email address in the agent workspace should include this data in the JWT payload to prevent future development, but it is not mandatory. Alternatively, if the email address is the unique identifier for the customer, the email address can be displayed using the external ID.