Remote Authentication

Remote authentication allows you to authenticate Zendesk users using a locally hosted script. In order to enable remote authentication, go to the "Integrations" menu under the "Account" tab - 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 can Zendesk can 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

Zendesk accepts 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+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 but no such user exists in Zendesk, the user gets created on the fly. If a user exists by this unique id, he gets updated with the transmitted name and email values. Be aware, that emails are unique per Zendesk account and if the email 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. 		—

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 an error parameter in case the user could not be logged in or created. For example: http://yourcompany.com/logout/?email=someone@someone.foo&error=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.

Full use case example

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

Setting up Zendesk

Go to "Integrations" under the "Account" menu and 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 http://wifflewibble.zendesk.com/access/normal/ 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. http://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, http://wifflewibble.zendesk.com/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 http://zendesk.wifflewibble.com/auth/?timestamp=1218898837 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 https://wifflewibble.zendesk.com/access/remote/?name=Roger%20Wilco&email=roger.wilco@wifflewibble.com&external_id=4&timestamp=1218898837&hash=fca9944ea6e0e37ad33e49ba9b48021f

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 http://zendesk.wifflewibble.com/logout/?email=roger.wilco@wifflewibble.com&external_id=4 where your logout script resides, and writes a nice logout message.