Setting up Remote Authentication

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 their 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.


    • Related Articles

    • 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 ...

    • How to moderate end user signups in the Help Center?

      Self-signup allows end users to register themselves for an account on your Help Center. All you need to do is direct your customers to your Help Center so that they could register and start using the same immediately. But, there is a caveat. The ...

    • Debugging JWT-Related Errors While Configuring the ASAP Add-On

      While setting up an ASAP add-on for your web/mobile app, you might encounter an error related to JSON Web Token (JWT) configuration. It is essential to debug this error because user authentication in the ASAP add-on is possible only through JWTs.  ...

    • Initiating Remote Assistance Sessions inside Tickets

      Remote assistance allows you to view and take control of remote PCs to resolve customer issues instantaneously. During a remote session, you can transfer files, chat with the customer and even share your own desktop with them. Once the session ends, ...

    • 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 ...