Knowledge Base Zoho Desk For Administrators User Access and Security

            Setting up Remote Authentication

            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:
            • You must map your subdomain (e.g., support.bayandco.com) with Zoho Desk to set up remote authentication.

            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. In the Setup Landing page, click Rebranding under Organization.
            3. Under Rebranding menu, click Remote Authentication.
            4. 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.
            5. 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

            Parameter
            Properties
            operation
            Provide as "signin"
            email
            Email ID of the user
            ts
            Current time in GMT 0:0/UTC in milliseconds in numeric format Ex.1341224998301
            apikey
            hexdigest(MD5(operation+email+remoteauthkey*+ts))

            Sign-up Operation Sample Script Attached

            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.1341224998301
            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"}

            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:
            https://support.zoho.com/support/<myportalname>/RLConfig.do?actionName=showRL
            Helpful?  
            Help us to make this article better
            3 2