Configuring ADFS for Zoho Desk with SAML

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 entirely outside of Zoho Desk.

ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials. This article explains how to configure the single sign-on integration of a self-hosted Active Directory Federation Services (ADFS) server and Zoho Desk.

Prerequisites
You must work closely with your IT team to ensure all of the following prerequisites are met:
  1. A Zoho Desk org on the Standard, Professional or Enterprise plan
  2. Administrator level access to your help desk
  3. Log into your Zoho Desk account and keep the SAML setup page open
  4. An Active Directory instance has been set up, where all users under your account in Zoho Desk have an account, with the same email address
  5. You know your ‘SAML 2.0/W-Federation’ URL (found in ADFS Endpoints)
After you meet these prerequisites, you need to install ADFS on your server. Configuring and installing ADFS is beyond the scope of this help article, but is detailed in a Microsoft KB article here.

Step 1 - Adding a Relying Party Trust
The connection between ADFS and Zoho Desk is defined using a Relying Party Trust (RPT). The first step is to select the Relying Party Trusts folder from AD FS Management, and add a new Relying Party Trust from the Actions sidebar.
  1. Log in to the server where ADFS is installed.
  2. Launch the ADFS Management Console.
  3. On the left hand tree view, select “Relying Party Trusts”.
  4. Right click and select “Add Relying Party Trust…”.
  5. Select the Relying Party Trusts folder from AD FS Management, and add a new Add Relying Party Trust from the Actions sidebar on the right.
  6. On the Select Data Source screen, click Enter data about the relying party manually and click Next.
  7. Provide information for each screen in the Add Relying Party Trust wizard.
    1. Enter a Display name that you will recognize in the future (e.g. Zoho Desk Help Center Login), select AD FS profile, and then click Next.
    2. Skip the Configure Certificate screen by clicking Next.
    3. On the Configure URL, check the box labeled: Enable support for the SAML 2.0 WebSSO protocol. Copy-paste the SAML Response URL from the SAML screen of Zoho Desk as the service URL.
      Note: There’s no trailing slash at the end of the URL.
    4. On the Configure Identifiers screen, enter the Relying party trust identifier. Enter "zoho.com" and then click Add. If your data is currently being hosted in the EU DC enter "zoho.eu." If in IN DC enter "zoho.in" and similarly for AU DC enter "zoho.au". Click Next.
    5. Skip the Configure Multi-factor Authentication screen (unless you want to configure this) by clicking Next.
    6. Skip the Choose Issuance Authorization Rules screen by clicking Next.
    7. On the Ready to Add Trust screen, review your settings and then click Next.
    8. On the final screen use the Close button to exit. This opens the Claim Rules editor.

Step 2 - Creating Claim Rules
After you create the relying party trust, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard.
  1. By default, the Claim Rules editor opens.
    Click on Add Rule to create a new rule.
  2. In the Claim rule template list, select the Send LDAP Attributes as Claims template, and then click Next.
  3. On the next screen, using Active Directory as your attribute store, create the following rule:
    1. Enter a descriptive rule name
    2. Attribute Store: Active Directory
    3. Add the following mapping:
    4. From the LDAP Attribute column, select E-Mail Addresses.
    5. From the Outgoing Claim Type, select E-Mail Address.
    6. Click OK to save the new rule.
  4. Create another new rule by clicking Add Rule. This time select Transform an Incoming Claim as the template and then click Next.
  5. On the next screen do the following:
    1. Enter a descriptive rule name
    2. Select E-mail Address as the Incoming Claim Type.
    3. For Outgoing Claim Type, select Name ID.
    4. For Outgoing Name ID Format, select Email.
    5. Leave the rule to the default of Pass through all claim values.
    6. Finally, click OK to create the claim rule, and then OK again to finish creating rules.

Step 3 - Adjusting the Trust Settings
Some settings on your Relying Party Trust (RPT) will need to be adjusted. To access these settings, select Properties from the Actions sidebar on the right while you have the RPT selected.
  1. Go to AD FS Management window.
  2. In the Relying Party Trusts list, double-click the relying party object that you created
    (or select     Actions > Properties while you have the Relying Party Trust selected).
  3. Click the Advanced tab.
  4. Make sure SHA-256 is specified as the secure hash algorithm.
  5. In the Endpoints tab, click add SAML to add a new endpoint.
  6. For the Endpoint type, select SAML Logout.
  7. For the Binding, choose POST.
  8. For the Trusted URL, create a URL using:
    1. The web address of your ADFS server.
    2. The ADFS SAML endpoint you noted earlier.
    3. The string ‘wa=wsignout1.0’
    4. The Trusted URL should look something like this: https://sso.yourdomain.tld/adfs/ls/?wa=wsignout1.0
  9. Leave the Response URL blank.
  10. Click OK twice. You should now have a working relying party trust for Zoho Desk.

Step 4 - Exporting Certificate from the AD FS Server
You must now export the token-signing certificate as base-64 encoded. This certificate is used when configuring SAML authentication in Zoho Desk.
  1. Open AD FS 2.0 MMC and navigate to Service > Certificates.
    Here, you will find the Token-signing certificate for your AD FS server that is used to authenticate your SAML connection from Zoho Desk.
  2. Under Token-signing, right-click the certificate and select View Certificate.
  3. Click the Details tab and then click Copy to File.
    The Certificate Export Wizard opens.
  4. Click Next.
  5. In the Export File Format window, select the Base-64 encoded X.509 (.CER) option and click Next.
  6. Specify a name for the file you want to export and click Next. For example, TokenSigningCert.cer
    Entering a new file name will not impact the setup.
  7. Click Finish to export the file.
    A message is displayed stating "The export was successful".
  8. Click OK to dismiss the message.
  9. Close the MMC.

Note:
  1. The token-signing certificate is downloaded in .cer format. Since Zoho Desk does not accept certificates in this format, kindly save it to a .txt file.

Step 5 - Configuring for use with Zoho Desk
After setting up ADFS, you need to configure your Zoho Desk to authenticate using SAML 2.0.
  1. Click the Setup icon (  ) in the top bar.
  2. Click Help Center under the Channels menu.
  3. Select the Help Center in which you want to authenticate users using SAML.
  4. Click User Authentication under the Help Center sub-menu.
  5. On the SAML page, provide the following details:
    • Remote Login URL: Enter the remote login URL as https://sso.yourdomain.tld/adfs/ls
    • Remote Logout URL: Enter the remote logout URL as https://sso.yourdomain.tld/adfs/ls/?wa=wsignout1.0
    • Reset Password URL: Enter the reset password URL as https://sso.yourdomain.tld/adfs/ls
    • Public Key: Upload the base-64 encoded X.509 certificate in the text format. Refer, Step 4. 
    • Algorithm: Select RSA from the drop-down menu.
  6. Click Save.
You should now have a working ADFS SSO implementation for Zoho Desk.

    • Related Articles

    • Configuring Active Directory SSO for Agents

      Active Directory (AD) by Microsoft is a centralized and standardized system that automates network management of user data, security, and distributed resources. In other words, it allows the management and storage of information and provides ...

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

    • GoToWebinar for Zoho Desk

      Webinars help give product demos and make a great tool for customer support. The GoToWebinar extension for Zoho Desk helps support agents explain their product efficiently through webinars, allowing them to resolve support tickets faster. With this ...

    • Highrise for Zoho Desk

      View customer details and deals from Highrise in Zoho Desk. Manage contacts, deals, and activities between Highrise and Zoho Desk. Add new customers and deals to Highrise from Zoho Desk. This integration makes it easy to understand customer's details ...