Enabling JWT single sign-on

Sign-in driven by your own application. Mostly for customers, where your product already knows who they are.

Sign-in driven by your own application. Mostly for customers, where your product already knows who they are.

What it is for

A customer signed in to your product clicks Help and arrives in the help centre already signed in. No second account, no second password, no drop-off.

That is the case JWT handles well, and it is usually about customers rather than staff.

Set it up

1. In Admin Center, click Account in the sidebar, select Security > Single sign-on, click Create SSO configuration and choose JSON Web Token.
2. Enter a Configuration name and the Remote Login URL: the address people are sent to when they try to reach your Zendesk. Zendesk appends a brand_id parameter to it.
3. Optionally set a Remote logout URL and IP ranges, and decide whether to show the button when users sign in.
4. Take the shared secret and give it to whoever builds the endpoint.
5. Build the endpoint in your application that signs the token.
6. Test with one account, then enable it for end users.

The four claims the token must carry

All four are required. jti is the one people leave out or reuse, and reusing it is exactly the case the check exists to catch.

It is development work

Your application has to generate and sign tokens correctly. This is not a configuration task, and it needs whoever owns that application.

The shared secret is a credential

Anybody holding it can assert who a user is. Zendesk puts it plainly: if the shared secret is compromised, all the data in your Support account is at risk. It belongs wherever your application keeps its secrets, never in client-side code and never in a repository, and you can generate a new one from the options menu if it ever leaves that place.

Email decides identity

Same rule as everywhere. If your application sends a different address from the one on the ticket history, the customer arrives as a new user with none of their tickets.

Plan what happens outside your product

Somebody arriving at the help centre from a search engine is not signed in to your application. Decide whether they can sign in another way or are sent to your product first.

For staff, use SAML instead

JWT works, and SAML integrates with the identity provider that already governs joining and leaving. For agents that is the better arrangement.

See also

• Sign-in options for end users
• Enabling SAML single sign-on
• Managing your SSO configurations