Single sign-on is a mechanism that allows you to authenticate users in your systems and subsequently tell Zendesk that the user has been authenticated. The user is then allowed to access Zendesk without being prompted to enter separate login credentials.
At the core of single sign-on is a security mechanism that allows Zendesk to trust the login requests it gets from your systems. Zendesk only grants access to the users that have been authenticated by you. Zendesk SSO relies on a technology called JSON Web Token (JWT) for securing the exchange of user authentication data.
The actual JWT implementation is straight forward and most modern languages have libraries available. Zendesk provides a series of examples for various stacks in the following JWT SSO GitHub repository:
Once you enable single sign-on, login requests are routed to a remote login URL (a login page that is external to your Zendesk).
Here are the steps of the single sign-on authentication process:
An unauthenticated user (not already logged in) navigates to your Zendesk URL (for example, https://mycompany.zendesk.com/).
The Zendesk SSO mechanism recognizes that SSO is enabled and that the user is not authenticated.
The user is redirected to the remote login URL configured for the SSO settings (for example, https://mycompany.com/zendesk/sso).
A script on your side authenticates the user using your proprietary login process.
Your script builds a JWT request that contains the relevant user data.
You redirect the customer to the Zendesk endpoint at https://mycompany.zendesk.com/access/jwt with the JWT payload.
Zendesk parses the user detail from the JWT payload and then grants the user a session.
As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct connection between Zendesk and your systems, so you can keep your authentication scripts safely behind your corporate firewall.
Configuring your JWT implementation
If you're upgrading from an earlier version of Zendesk SSO (referred to as Zendesk Remote Authentication) to JWT, it's okay to have multiple SSO implementations enabled at the same time. Zendesk recognizes if a request is meant for JWT or another type of SSO and will handle the request accordingly. This means that you can enable and test JWT before deactivating your previous SSO implementation.
To perform SSO for a user, you need to send several required user attributes to Zendesk as a hash (hash table, dictionary). Most importantly, Zendesk requires an email address to uniquely identify the user. Beyond the required attributes, which are shown in the table below, you may optionally send additional user profile data. This data is synced between your user management system and your Zendesk.
Table 1. Supported attributes
Issued At. The time the token was generated, this is used to help ensure that a given token gets used shortly after it's generated. The value must be the number of seconds since UNIX epoch. Zendesk allows up to two minutes clock skew, so make sure to configure NNTP or similar on your servers.
JSON Web Token ID. A unique id for the token, used by Zendesk to prevent token replay attacks.
Email of the user being signed in, used to uniquely identify the user record in Zendesk.
The name of this user. The user in Zendesk will be created or updated in accordance with this.
If your users are uniquely identified by something other than an email address, and their email addresses are subject to change, send the unique id from your system. Specify the id as a string.
locale (for end-users)
locale_id (for agents)
The locale in Zendesk, specified as a number.
The name of an organization to add the user to.
A phone number, specified as a string.
This is a JSON array of tags to set on the user. These tags will replace any other tags that may exist in the user's profile.
URL for a photo to set on the user profile.
The user's role. Can be set to "user", "agent", or "admin". Default is "user". If the user already exists in Zendesk, the existing role is not changed.
Applicable only if the role of the user is agent.
A JSON hash of user field key and values to set on the user. The user field must exist in order to set the field value. Each user field is identified by its field key found in the user fields admin settings. The format of date values is yyyy-mm-dd.
If a user field key or value is invalid, updating the field will fail silently and the user will still login successfully. For more information about custom user fields, see Adding custom fields to users.
Most JWT implementations take a hash and a secret, and return a plain string payload to send to the other side. For context, here's an example in Ruby:
When Zendesk redirects a user to your login script, it will also pass a return_to parameter in the URL. This parameter contains the page that Zendesk will return the user to after the authentication succeeds. For example:
All your script needs to do, is take the return_to value from the invoked URL and pass it back to Zendesk when submitting the JWT token. In other words, upon authentication on your side, your script redirects the user to:
The return_to parameter is an absolute URL for the agent interface and the Web portal, and a relative one for Help Center.
Whether you pass in the return_to parameter or not is optional, but we recommend it for the smoothest user experience.
Note: If your return_to address contains its own URL parameters, make sure that your script URI-encodes the entire return_to value when submitting the JWT token.
If Zendesk encounters an error while processing a JWT login request, it will report a message that explains what the issue is. If you have a return URL configured for your JWT integration, it will redirect to that and pass a "message" and a "kind" parameter. In case of error, the "kind" parameter will always have the value "error". We recommend having a return URL as well as logging messages from Zendesk alongside the type, most of the errors that can happen are ones that you will want to fix (for example, clock drifts, rate limits being hit, invalid tokens, and so on).
Enabling JWT single sign-on in your Zendesk
To start using JWT single sign-on, you need to enable and configure it in your Zendesk account.
To enable JWT single sign-on
Click the Admin icon () in the sidebar, then select Settings from the Security category.
Zendesk Classic: Select the Setting menu, then select Security.
Select the Admins & Agents or End-users tab.
You can enable JWT single sign-on only for end-users, only for agents, or for both groups. You can't enable JWT for one group if the SAML SSO option is enabled for the other group. If you want to use single sign-on for both groups, both must be JWT or both must be SAML. If you started using Zendesk on or after August 21, 2013, the End-users tab is not available until you activate the Help Center. See Getting started with the Help Center.
Zendesk Classic: Select the Single Sign-On tab.
Select the JSON Web Token option.
Zendesk Classic: Next to the JSON Web Token option, click Edit, and then select Enabled.
Enter the Remote Login URL. This is where your user will be redirected when they attempt to access your Zendesk URL.
Enter the Remote Logout URL. This is the URL that Zendesk will return your users to after they log out.
You can optionally restrict access to users within a range of IP addresses.
If you use external_IDs for your users, you can update these in your Zendesk by selecting Allow update of external ids?.
Finally, you need to generate a shared secret by clicking Generate a new token. Copy the shared secret because you'll need to use it in your JWT implementation.
Important: You must keep the shared secret safe because if that gets compromised all the data in your Zendesk account is at risk.
When you're done configuring JWT, click Save.
Additional information about JWT
JWT is a recent open standard that is being driven by the international standards body IETF and has top-level backers from the technology sector (for example, Microsoft, Facebook, and Google).
The fundamental building blocks of JWT are very well understood components and the result of this is a fairly simple spec, which is available here http://tools.ietf.org/html/draft-jones-json-web-token-10. There are a lot of open source implementations of the JWT spec that cover most modern technologies. This means that you can get JWT single sign-on set up without much difficulty.
One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don't put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. It then base 64 encodes that string and then makes an HMAC of the base 64 string which depends on the shared secret. This produces a signature that the recipient side can use to validate the user.