WIXLIB

Setting up single signon with Zendesk Remote AuthenticationZendesk Inc.

2 Zendesk Developer Library Introduction

NoticeCopyright and trademark notice Copyright 2009–2013 Zendesk, Inc. All rights reserved.Setting up single sign-on with Zendesk Remote AuthenticationThe information in this document is furnished for informational use only, is subject to changewithout notice, and should not be construed as a commitment by Zendesk, Inc. Zendesk, Inc.assumes no responsibility or liability for any errors or inaccuracies that may appear in thisdocument. The software described in this document is furnished under license and may only be usedor copied in accordance with the terms of such license.Zendesk is a registered trademark of Zendesk, Inc. All other trademarks are the property of theirrespective owners.Zendesk - 989 Market St, Ste 300 - San Francisco - CA 94103 - USAwww.zendesk.com

4 Zendesk Developer Library Copyright and trademark notice

Zendesk Developer Library TOC 5ContentsChapter 1: Setting up single sign-on with Zendesk Remote Authentication.7The principles.7Security notes.8Parameters.8Return URL.11Skipping a routing step. 11Error messages. 11Use cases. 12

6 Zendesk Developer Library TOC

Chapter1Setting up single sign-on with ZendeskRemote AuthenticationAs of 4/29/13, single sign-on using Zendesk Remote Authentication has been deprecated andreplaced with JSON Web Token (JWT). If you've already set up single sign-on with ZendeskRemote Authentication, it will continue to work but we recommend that you upgrade to JWT. SeeSetting up single sign-on with JWT (JSON Web Token).-----Remote authentication allows you to authenticate Zendesk users using a locally hosted script. Inorder to enable remote authentication, go to the Account menu and choose Settings Security – youmust be an Admin in order to do this.The principlesRemote authentication is based on a “shared secret” between your local authenticating script andZendesk. This secret is used to securely generate a hash (one-way encryption) which Zendesk usesto ensure that people who log on to your account using remote authentication, are who they claim tobe, 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:Client attempts to log on to a Zendesk account which has remote authentication enabledClient is from an IP address which Zendesk is configured to authenticate remotelyZendesk redirects client to the remote authentication URL, adding a time stampThe script running at the remote authentication URL (i.e. on your web server) gets a requestThe script routes the client via your local/internal authentication mechanism to ensure that the client islogged 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 stamp7. The script redirects the client back to Zendesk8. Zendesk gets the request, and also hashes the same parameters using the “shared secret”. If the hashesmatch, Zendesk know that this request has been authorized by your local script. The user gets loggedin.1.2.3.4.5.

8 Zendesk Developer Library Setting up single sign-on with Zendesk Remote AuthenticationThis means that the task at hand, is to write the authentication script which Zendesk can then redirectthe login request to, determine the authenticity of the user sending this request, and either display alogin error to the user, or authenticate the user and redirect him back to Zendesk. You can downloada commented sample script for an ActiveDirectory/IIS setup on the page where you configure yourremote authentication setupSecurity notesThe server your users authenticate against does not have to be available via the internet, as long asthey can reach it by their browser. These are simple redirects, there is no inbound connection toyour facilities from Zendesk.ParametersWhen you redirect back to Zendesk, you must hit the URL https://domain.zendesk.com/access/remoteauth and include all the parameters that were sent to you plus the following parameters:ParameterDefinitionnameThe name of the user, minimum2 charactersThis name gets seton the user, whether it’s a newuser or an existing useremailValid email address for theuserUsed to find the user unlessa valid external id is provided(more below). Users get createdon the fly if no user by thisemail address exists in Zendesk.timestampThe timestamp sent to yourauthentication script byZendeskMandatory?

Zendesk Developer Library Setting up single sign-on with Zendesk Remote Authentication 9hashinput name " " email " " external id " " organization " " tags " " remote photo url " " token " " timestamphash md5(input)In the above, use an emptystring for the values thatyou do not make use of orsend to Zendesk, e.g. in caseyou only make use of themandatory parameters name,email, token and timestamp,then the input string will looklike this:input name " " email " " token " " timestampRemember thatorder matters when you buildthe input string. You can see asample Ruby implementationof the hashing mechanism here.Zendesk uses the hash value tovalidate that the account tokenis valid. For the timestamp,you should use the timestampsent to you from Zendesk, orgenerate your own for a directlogin call without having to govia your Zendesk login pagefirst.Since the vertical bar characteris used as a delimiter, Zendeskrequires that you convertany existing vertical bars inother parameters to an escapesequence: %7C. For example,if a user's external id is "123 enduser", then you wouldencode the input string as name " " email " " "123%7Cenduser" " " token " " timestamp . Nospecial handling is necessarywhen sending parameters toZendesk, only when generatinga signature so that Zendesk canverify the input.

10 Zendesk Developer Library Setting up single sign-on with Zendesk Remote Authenticationexternal idA unique user identifier in—your systemIf your usersare uniquely identified bysomething else than an emailaddress, and their emailaddresses are subject to change,send the unique id from yoursystem.If you send along anexternal id no user is found bythat id, then we try to find theuser by email address. If a usergets found by email address andhas no external id, or updatingexternal id’s is enabled, thenwe set the external id of theuser to the given value. If nouser was found by either emailor external id, we create theuser on the fly.Be aware, thatemail addresses are unique perZendesk account and if theemail address is in use by a userwith different external id, thelogin will fail.organizationOrganization to add the user—toIf you have a logical groupingof users in your current systemwhich you want to retain inZendesk, this can be donesetting the organizationparameter. If you set theparameter in the query string,but do not supply the name ofan existing organization, theuser will be removed from hiscurrent organization (if any). Ifyou do not set the parameter,nothing will happen.tagsTags to be put on the user—profile. This should be in“tag1, tag2, tag3# format andURL encoded.Note: This is aPUT action, meaning any tagsspecified will be used to replaceany existing tags on the user.remote photo urlA profile image of the user.This must be a public image—

Zendesk Developer Library Setting up single sign-on with Zendesk Remote Authentication 11URL, which is not behindany authentication. RemoteAuthentication will not followredirects.Usage of the above parameters is elaborated in the sample script. But don’t hesitate to contact us ifthere’s something that’s unclear to you.User attributes get updated each time you login a user. This means that data from your systemoverrules data in Zendesk. You can disable user access to their profiles to further lock down users toyour system. If a user is found by email, name gets updated. If a user is found byexternal id, nameand email get updated unless the email address is already in use by another user. In this case an errormessage gets displayed to the user.Return URLYou can set a return URL to which the user gets redirected to when logging out of Zendesk orwhen Zendesk rejects the login. This URL gets parameterized with email and external id if asuch exists. Optionally, it will be parameterized with a kind and a messageparameter in casethe user could not be logged in or created. For example: http://yourcompany.com/logout/?email someone@someone.foo&kind error&message Invalid tokenSkipping a routing stepIt’s perfectly possible to log directly into Zendesk using remote authentication, and not having theuser go by the Zendesk login page, only to get redirected back to your authentication script. Allyou need to do, is to set the timestamp parameter on your own, the value should be the number ofseconds since epoch (in UTC). The time stamp must be current.Error messagesIf Zendesk cannot login a user by remote authentication, the user will either get an error messagedisplayed, 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 theURL message and kind. On an error, the value of kind will beerror and the message will be one ofthe following:MessageExplanationInvalid data from remote login mechanism.Missing name, email, hash or timestampOne of the mandatory parameters were missing.Please verify that your local authentication scriptis correct.Remote authentication timestamp expiredThe timestamp was older than 30 minutes.Please create a new as elaborated above, andensure that your servers clock is properlysynchronized.Invalid token for remote authentication, checkthat your security token is up to dateVerify that the token in your local authenticationscript is identical to the one on your Zendeskremote authentication configuration page.

12 Zendesk Developer Library Setting up single sign-on with Zendesk Remote AuthenticationUser exists with different external idHappens if you have not enabled that usercan have their external idupdated via remoteauthentication and the external id in the requestdoes not correspond to the one found on theZendesk user record. If a Zendesk user hasno external idand there is one in the request,the user record will get theexternal id set,irregardless of the aforementioned “allowupdate” setting.Failed to create user with given properties: It was not possible to create the user for thespecified reason (after the colon). Could be aninvalid email address, name or other.Failed to update user with new properties: It was not possible to update the user for thespecified reason (after the colon). Could be aninvalid email address, name or other.Use casesThis section describes how Zendesk acts under different use cases. The use cases revolve around thesubmitted 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’scarried on to the next use case.Auth requestUsers in account / outcomeemail bob@domainexternal id 123NoneThe user gets created with given attributesemail bob@domainexternal id 123email:bob@domainexternal id:456If allow update of external ids is enabled:Theuser bob@domain gets hisexternal id changedto 123If allow update of external idsis disabled:An attempt to create theuser is made. This will fail as the emailaddress is already in use by another user.The request gets redirected to the logoutpage with a kind error parameter anda message parameter.email bob@domainexternal id 123email:bob@domainexternal id:456email:joe@domainexternal id:123An error is returned to the remote auth callingpage stating that the email address is alreadytaken. The remote auth mechanism finds theuser with the given external id 123 and tries to