Remote authentication allows you to authenticate Zendesk users using a locally hosted script. In order to enable remote authentication, go to the “Account” tab and click “Security” from the menu – you must be an Admin in order to do this.

The principles

Remote authentication is based on a “shared secret” between your local authenticating script and Zendesk. This secret is used to securely generate a hash (one-way encryption) which Zendesk uses to ensure that people who log on to your account using remote authentication, are who they claim to be, and have been pre-approved to do so by implicitly knowing the “shared secret”.

That was a somewhat abstract explanation, here’s what happens in simple steps:

1. Client attempts to log on to a Zendesk account which has remote authentication enabled
2. Client is from an IP address which Zendesk is configured to authenticate remotely
3. Zendesk redirects client to the remote authentication URL, adding a time stamp
4. The script running at the remote authentication URL (i.e. on your web server) gets a request
5. The script routes the client via your local/internal authentication mechanism to ensure that the client is logged on (to e.g. the domain)
6. The script retrieves the client email address and name and creates a hash value of this alongside the “shared secret” and time stamp
7. The script redirects the client back to Zendesk
8. Zendesk gets the request, and also hashes the same parameters using the “shared secret”. If the hashes match, Zendesk know that this request has been authorized by your local script. The user gets logged in.

This means that the task at hand, is to write the authentication script which Zendesk can then redirect the login request to, determine the authenticity of the user sending this request, and either display a login error to the user, or authenticate the user and redirect him back to Zendesk. You can download a commented sample script for an ActiveDirectory/IIS setup on the page where you configure your remote authentication setup.

Security notes

The server your users authenticate against does not have to be available via the internet, as long as they can reach it by their browser. These are simple redirects, there is no inbound connection to your facilities from Zendesk.

Parameters

When you redirect back to Zendesk, you must include all the parameters that were sent to you plus the following parameters:

Parameter	Definition	Mandatory?
name	The name of the user, minimum 2 characters This name gets set on the user, whether it’s a new user or an existing user
email	Valid email address for the user Used to find the user unless a valid external_id is provided (more below). Users get created on the fly if no user by this email address exists in Zendesk.
timestamp	The timestamp sent to your authentication script by Zendesk
hash	hexdigest(MD5(name+email+external_id+organization+remote_photo_url+token+timestamp)) The hash used to validate that the account token is valid, if external id’s are not employed, this should be an empty string (i.e. left out). The timestamp is the timestamp sent to you by Zendesk. Note, what you hash depends on what you send. If you do not send eg. an organization parameter don’t include that in the hash either. Order matters when hashing.
external_id	A unique user identifier in your system If your users are uniquely identified by something else than an email address, and their email addresses are subject to change, send the unique id from your system. If you send along an external_id no user is found by that id, then we try to find the user by email address. If a user gets found by email address and has no external_id, or updating external id’s is enabled, then we set the external_id of the user to the given value. If no user was found by either email or external_id, we create the user on the fly. Be aware, that email addresses are unique per Zendesk account and if the email address is in use by a user with different external_id, the login will fail.	—
organization	Organization to add the user to If you have a logical grouping of users in your current system which you want to retain in Zendesk, this can be done setting the organization parameter. If you set the parameter in the query string, but do not supply the name of an existing organization, the user will be removed from his current organization (if any). If you do not set the parameter, nothing will happen.	—
tags	Tags to be put on the user profile. This should be in “tag1, tag2, tag3″ format and URL encoded. This should not be included in the hash. Note: This is a PUT action, meaning any tags specified will be used to replace any existing tags on the user.	—
remote_photo_url	A profile image of the user. This must be a public image URL, which is not behind any authentication. Remote Authentication will not follow redirects.	—

Usage of the above parameters is elaborated in the sample script. But don’t hesitate to contact us if there’s something that’s unclear to you.

User attributes get updated each time you login a user. This means that data from your system overrules data in Zendesk. You can disable user access to their profiles to further lock down users to your system. If a user is found by email, name gets updated. If a user is found by external_id, name and email get updated unless the email address is already in use by another user. In this case an error message gets displayed to the user.

Return URL

You can set a return URL to which the user gets redirected to when logging out of Zendesk or when Zendesk rejects the login. This URL gets parameterized with email and external_id if a such exists. Optionally, it will be parameterized with a kind and a message parameter in case the user could not be logged in or created. For example: https://yourcompany.com/logout/?email=someone@someone.foo&kind=error&message=Invalid token

Skipping a routing step

It’s perfectly possible to log directly into Zendesk using remote authentication, and not having the user go by the Zendesk login page, only to get redirected back to your authentication script. All you need to do, is to set the timestamp parameter on your own, the value should be the number of seconds since epoch (in UTC). The time stamp must be current.

Error messages

If Zendesk cannot login a user by remote authentication, the user will either get an error message displayed, or – if you have entered a return URL, an error will get sent back to that.

If we send an error to the return URL, there will be set two parameters on the URL message and kind. On an error, the value of kind will be error and the message will be one of the following:

Use cases

This section describes how Zendesk acts under different use cases. The use cases revolve around the submitted email and external_id’s, and the current state of the users in the Zendesk account.

These use cases should be read independently of one another, i.e. there’s no “resulting state” that’s carried on to the next use case.

Full use case example

Your new hot SaaS startup is going to offer remote authentication for your Zendesk account at https://wifflewibble.zendesk.com/.

Setting up Zendesk
Go to the “Account” tab and click the “Security” menu item to edit “Remote authentication”.

Save. Now click the “ASP script for IIS/AD” link to the right, and download a preconfigured sample script for an IIS/AD setup. Since you left the IP Ranges blank, remote authentication will henceforth be enabled for all users, no matter where they come from.

Should you get unlucky and somehow lock yourself out of Zendesk, you make a mental note that the /access/normal/ URL at will let you use the regular login at any time.

Setting up your IIS/AD
You begin by reading the script downloaded, and skim the functionality.

  ' USAGE:
  '
  ' 1. Place this script in a folder on your IIS, and disable anonymous access for the script.
  ' 2. Add a valid user/password for the LDAP lookups by setting the variables sLdapReaderUsername
  '    and sLdapReaderPassword below.
  '
  ' For debugging, call this script with debug=1 as a parameter (e.g. https://yourserver/sso.asp?debug=1)

You’re going for external_id authentication, it doesn’t get more exciting than this. You configure the vital parts of the script, and you’re ready to go.

Logging in
You add a link to your intranet with the Zendesk login, and click the link.
Zendesk recognizes that the login request comes from an IP address for which remote authentication is enabled, and promptly redirects the request to where it hits your authentication script.

The authentication script gets the request, and validates the current domain login. The user is okay to to send to Zendesk. The user then gets redirected to

Once the redirect hits Zendesk, the values get verified. This includes checking that the timestamp is recent and that the hash value is correct. These pass. There’s no user by external_id=4 in Zendesk at this point, so the user found by email address roger.wilco@wifflewibble.com gets this set, and the name gets updated in case they differ.

You’ve now logged in using remote authentication. You solve the tickets in your view, and logout. Zendesk terminates your Zendesk session and redirects you to the return URL defined under the “Remote authentication” page where your logout script resides, and writes a nice logout message.