Remote Authentication - Zoho Desk Knowledgebase

Setting up Remote Authentication


The authentication method described here will be deprecated soon.
We recommend using the SAML single sign-on method for increased security.

Remote authentication allows you to incorporate your user management system with Zoho Desk. It allows your end users to log in to your help desk using the credentials of your own web application without having to create a separate account for your help desk.

Note:

Enabling Remote Authentication
You must login to your help desk with administrator credentials to enable remote authentication in your Zoho Desk.
  1. Click the Setup icon (  ) in the top bar.
  2. Click Help Center under the Channels menu.
  3. Select the Help Center for which you want to set up remote authentication.
  4. Click User Authentication under the Help Center sub-menu.
  5. Select the Remote Authentication tab at the top of the page.
  6. In the Remote Authentication page, provide the following details:
    • Support Domain URL: The support domain URL is pre-filled.
      Note: Make sure that you point the CNAME record from your subdomain to desk.cs.zohohost.com.
    • Remote Login URL: Enter the URL to which Zoho Desk will redirect the users when they log in to your help desk.
    • Remote Logout URL: Enter the URL to which Zoho Desk redirects the users when they attempt to log out of your help desk.
  7. Click Submit.
On receiving the above details, we will generate and provide a unique authentication key which should be pasted into the authentication script on your web server. You will receive the key via email and within Zoho Desk in 2-3 working days.

Tip:
  • Enter the IP addresses to have the users authenticated against your user management system. Requests received from other IPs will be directed to the standard log in page in Zoho Desk. You can enter multiple IPs separated by a comma. Please note that you must wait until you receive the authentication key to enter the allowed IPs.

How it Works
To authenticate users against Zoho Desk, you must pass a one-way encrypted hash (API key computation), that contains your unique authentication key and the user information. This hash will be used by Zoho Desk to determine the authenticity of the user. On successful validation, the user's record (from the hash) will be created
and is granted access to your help desk.

Here is a more detailed explanation:
  1. An end user wants to log in to Zoho Desk enabled for remote authentication from an allowed IP.
  2. The user will be redirected to the remote "Login URL" along with a time stamp.
  3. The user enters his login credentials.
  4. A validation request is sent to the authentication script running on your web server, which ensures that the user is logged in.
  5. The authentication script recovers the user’s name and email address and creates a hash. The hash will include the remote authentication key, timestamp and a set of other parameters.
  6. The authentication request will be redirected back to Zoho Desk.
  7. On receiving the authentication request, Zoho Desk will scan the hash and its content using the remote authentication key.
  8. If they match, Zoho Desk will consider that the user was authorized by you and grants access to your help desk.

Writing an Authentication Script
You are required to write the authentication script for sign-in and sign-up operations, which will help Zoho Desk to determine the authenticity of the users. You may need the assistance of a developer to write these scripts. Please make sure that you pass the following parameters for the operations as listed below:

Sign-in Operation
Sample Script Attached

Method: GET

Parameter
Properties
operation
Provide as "signin"

Note:
 This applies to existing Help Center users of your Zoho Desk account. Please use the Sign-up Operation for new users.
email
Email ID of the user
ts
Current time in GMT 0:0/UTC in milliseconds in numeric format Ex.1603339725252
apikey
hexdigest(MD5(operation+email+remoteauthkey*+ts))


Sign-up Operation Sample Script Attached

Method: GET
Parameter
Properties
operation
Provide as "signup"
email
Email ID of the user
ts
Current time in GMT 0:0/UTC in milliseconds in numeric format Ex.1603339725252
loginname
Login name of the user. It should be between 6 and 30 characters long and must contain letters & numbers. You may use underscore[_] and period[.]. Ex: john.b)
fullname
User name. (First Name(Max-length:50) + Last Name (Max-length :50). Ex: Stephanie Shane Snyder)
utype
Provide as "portal"
apikey
hexdigest(MD5(operation+email+loginName+fullName+utype+remoteauthkey*+ts))
redirect
On successful sign up: "0" to get the JSON response. Else: "1" to redirect the user to Zoho Desk. On successful sign up, the JSON response will be - {"result":"success","info":"User Added"}



Response: Either of the following can occur on sign up:
  • If the redirect parameter is empty, or '1' the user gets redirected to the Help Center homepage hosted at https://support.yourdomain.com/portal/home
  • If the redirect parameter is '0' the JSON response is displayed.

Note:
  • The remoteauthkey* mentioned under the "apikey" parameter is the unique remote authentication key specific to your account.
  • The "apikey" computation should strictly adhere to the order mentioned above.
  • When you add an existing user to the Zoho Desk portal, the system will not throw any exception or will create a duplicate user. Usually, existing users will be granted access to the application or will receive a success JSON response, depending upon the "redirect" parameter.

Avoiding Redirection
Your help desk users can log in to Zoho Desk without needing to go to the login page and be redirected back to your authentication script. To avoid this redirection, compute and send the "ts" param with the current time in GMT 0:0 /UTC (Ex. 1341224998301), along with the other parameters. This enables Zoho Desk to authenticate users and grant them access directly.

Error Messages
There are instances when Zoho Desk denies access to users via remote authentication. For example, you may have configured an incorrect domain, or the email address of the user doesn't exist. Here are some of the most common errors and the reasons behind them:

Error Message
Reason
{"result":"failure","cause":"Unauthorized Access"}
Configured an incorrect domain or the domain name must be checked for a typo.
{"result":"failure","cause":"Unauthorized Access"}
It looks like an issue with your Zoho Desk license or your edition doesn't support remote authentication.
{"result":"failure","cause":"Unauthorized Access"}
You must have provided an invalid "apikey".
{"result":"failure","cause":"Invalid Username"}
You must have provided an incorrect username.
{"result":"failure","cause":"LoginName already exists"}
It looks like the "loginname" already exists. Please provide a different Login Name.
{"result":"failure","cause":"No Such User or User Deactivated"}
The e-mail ID doesn't exist or the user associated with the email address has been deactivated.
{"result":"failure","cause":"Operation not supported"}
The operation parameter is neither "signin" nor "signup".  Also, check if the domain name has been configured.
{"result":"failure","cause":"Request Delayed"}
The "ts" parameter is incorrect, or the value is not within the past 3 minutes.

Safe Access URL
If you should get locked out of Zoho Desk while working with remote authentication, you can log in to your portal by accessing this Safe Access URL:


It is the responsibility of the data administrator to provide requisite permissions to their agents.


    Zoho DataPrep Personalized Demo

    If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

    Zoho CRM Training

      Create, share, and deliver

      beautiful slides from anywhere.

      Get Started Now





              Zoho CRM Training Programs

              Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

              Zoho CRM Training



                      Zoho DataPrep Resources

                        Zoho DataPrep Demo

                        Get a personalized demo or POC

                        REGISTER NOW


                          Design. Discuss. Deliver.

                          Create visually engaging stories with Zoho Show.

                          Get Started Now











                                              • Related Articles

                                              • Configuring ADFS for Zoho Desk with SAML

                                                Zoho Desk supports SAML 2.0 (Security Assertion Markup Language 2.0), which allows for the use of SSO (Single Sign-On) using enterprise identity providers such as Active Directory. Enabling SSO via SAML 2.0 means that user authentication is handled ...
                                              • JWT for Authenticating Users in the ASAP Add-Ons

                                                Introduction Based on whether they choose to login to the ASAP add-on or not, end-users can be classified as guest users and authenticated users. Those who choose to not login are called guest users and those who choose to login are called ...
                                              • Adding and Managing User Groups

                                                Groups are a collection of end users, often related to a specific account, geography, brand, or product, that is used to determine access to your knowledge base and community content on the Help Center. For example, you can add a group that includes ...
                                              • Setting up SAML Single Sign-on for Help Center

                                                Security Assertion Markup Language (SAML) is a mechanism used for exchanging authentication and authorization data between applications, in particular, an identity provider (IdP) such as OneLogin, Okta, PingIdentity and a service provider (such as ...
                                              • Setting up Time Tracking

                                                Time management is essential, more so in the context of delivering quality customer service to your end users. When a ticket is received, the customer in question would want it to get resolved at the earliest time possible. Similarly, as a support ...

                                              Resources

                                              Videos

                                              Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                              eBooks

                                              Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                              Webinars

                                              Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                              CRM Tips

                                              Make the most of Zoho CRM with these useful tips.



                                                Zoho Show Resources