Remote Authentication

Authenticate your helpdesk users using remote authentication in Zoho Support. Read further to know what is remote authentication and how it works.

1. What is Remote Authentication?
2. How to activate Remote Authentication in Zoho Support?
3. How does it work?
4. What parameters need to be sent when a user signs-in or signs-up?
5. Can I skip a routing step for authentication?
6. I got an error while setup. Help?
7. Locked myself out of Zoho Support! Help?

Remote Authentication

Remote Authentication allows you to incorporate your user management system with Zoho Support, so that your customers do not have to manage two separate logins for access. This ensures a seamless experience for your customers without forcing them to sign-up for a separate account on your Zoho Support website.

Activating Remote Authentication

Setting up Remote Authentication for your Zoho Support helpdesk is very simple. Follow the steps mentioned below:

1. Go to Setup >> Rebranding >> Remote Authentication
2. In the Remote Authentication page, provide your Login URL. This is the URL to which your users would be redirected when they try to access Zoho Support
3. Provide the Logout URL. This is the URL to which your users would be redirected when they attempt to logout of Zoho Support
4. Provide your Support Domain URL. This is the URL of your domain mapped to Zoho Support
5. Provide an IP range so that only requests from them would be authenticated using Remote Authentication process. Requests from IPs outside the range would be directed to the regular login page in Zoho Support. You can provide multiple IP range as comma separated value.
6. Click Save
7. Click OK to save your Remote Authentication settings. Remember that you need to logout of Zoho Support on clicking Ok.
8. In the following Remote Authentication Key page, you can find your secret key which needs to be used in writing your authentication script on your webserver. A copy of this Remote Authentication key will be sent to your e-mail inbox for reference.

Working of Remote Authentication

To authenticate users on Zoho Support portal you pass a one-way encrypted hash(API Key Computation), containing the unique “Remote Authentication Key” and other user information. The hash would be used by Zoho Support to check the authenticity of the user. On approval an associated user record is created and the user would be successfully logged in with the information provided in the hash.

Steps involved in Remote Authentication are discussed in detail below:

1. A user tries to log on to Zoho Support account enabled for Remote Authentication from an IP range pre-defined in Zoho Support.
2. The user would be redirected to the Remote Login URL along with a time stamp.
3. The Request is sent to the authentication script running on your web server which ensures that the user is logged on.
4. The authentication script recovers the user’s name and e-mail address and creates a hash of it which includes the Remote Authentication Key, time stamp and a set of parameters.
5. The authentication request would be redirected back to Zoho Support.
6. On receiving the request, Zoho Support scans the hash containing the parameters using the Remote Authentication Key.
7. If the hash is found to be matching, Zoho Support considers that the user has been authorized by your authentication script and allows logging in.

Now to get started you need to write the authentication script which would help Zoho Support to determine the authenticity of the user sending the login request.

Parameters to be passed for Sign-In Operation

The sign-in parameters are as listed below:

operation = signin

email = Email id of the user

ts = Current time on GMT 0:0/UTC in milliseconds in numeric format Ex.1341224998301

apikey = hexdigest(MD5(operation+email+remoteauthkey*+ts))

Note that the API Key computation should strictly adhere to the order mentioned above as it would be used to check whether the account token is valid.

View Sample Script

Parameters to be passed for Sign-Up Operation

The sign-up parameters are as listed below:

operation = signup

email = Email id of the user

ts = Current time on GMT 0:0/UTC in milliseconds in numeric format Ex.1341224998301

loginname = Login name for the user (Should be between 6 to 30 characters containing letters & numbers and if required underscores and dot (.) Ex. john.b)

fullname = User name (First Name(Max-length:50) + Last Name (Max-length :50) Ex. John Abraham Thomas)

utype = portal | supportrep ('portal' if Customer Portal User or 'supportrep' if user is a Support Representative. Ex. portal)

role = Role of the User (is optional and when not specified 'CEO' role is default. Ex. Manager. Also it is applicable only when 'utype' is 'supportrep'.)

profile = Profile of the User (is optional and when not specified 'Administrator' profile is default. Ex. Standard. Also it is applicable only when 'utype' is 'supportrep'.)

apikey = hexdigest(MD5(operation+email+loginName+fullName+utype+role+profile+remoteauthkey*+ts)) or hexdigest(MD5(operation+email+loginName+fullName+utype+remoteauthkey*+ts)) when role & profile are not specified

redirect = 0 | 1 (On successful signup: '0' to get the JSON response, "1" to redirect the user to Zoho Support)

When redirect is '0' and on successful sign-up, the JSON response would be - {"result":"success","info":"User Added"}

Note that the API Key computation should strictly adhere to the order mentioned above as it would be used to check whether the account token is valid. Also the remoteauthkey* mentioned in the 'apikey' is the Remote Authentication key for your account.

If in case you're trying to add an existing user in Zoho Support portal, the user would either be taken inside the application or would receive a success JSON response based on the "redirect" parameter. We would not throw any exception or duplicate the user in your Portal.

View Sample Script

Avoiding Redirection

Users can login into Zoho Support using remote authentication without the need to go through the login page and be redirected back to your authentication script. For this, you can simply compute and send "ts" param with current time in GMT 0:0 /UTC (Ex. 1341224998301) along with the required parameters, for Zoho Support to directly authenticate and allow users to log in.

Error Messages

There may be instances when Zoho Support cannot login a user by remote authentication. Reasons may be that you configured a wrong domain or the e-mail id of the user doesn't exist. On an error, you would be displayed with the result folllowed by the reason. The follwing are the sample error messages for your reference.

{"result":"failure","cause":"Unauthorized Access"} = Configured a wrong domain or the domain name mentioned needs to be checked for error.

{"result":"failure","cause":"Unauthorized Access"} - Licensing issue or the edition doesn't support the feature.

{"result":"failure","cause":"Unauthorized Access"} - Have provided an invalid apikey.

{"result":"failure","cause":"Invalid Username"} - Check the username provided.

{"result":"failure","cause":"LoginName already exists"} - The login name is already existing. Provide a different login name.

{"result":"failure","cause":"No Such User or User Deactivated"} - The e-mail id provided doesn't exist or the associated user has been deactivated.

{"result":"failure","cause":"Operation not supported"}" - Operation parameter is other than signin/signup or there is no such domain configured.

{"result":"failure","cause":"Request Delayed"} - The ts parameter is incorrect.

Safe Access URL

Should by any chance you lock yourself out of Zoho Support, you can login to your portal the regular way, by accessing the following URL - https://support.zoho.com/support/<your-portal-name>/RLConfig.do