VLT-Website-Heading

How to set up SSO for Zoho Directory with Okta

Oct 30, 2021 8:45:00 AM / by Vu Long Tran

This is a step by step guide on how to set up SSO for Zoho Directory on Okta.
zoho-directory-add-okta
 
 
  The key steps we will be going through will be:

Prerequisites

Before you can start setting up Single Sign On (SSO) for Zoho Directory and Okta, we need to check the following:

  • Access to Zoho Directory Console - Confirm that you have administrator access to Zoho Directory Admin Console, https://directory.zoho.com/.
  • Access to Okta Admin Console - Confirm that you have administrator access to Okta's Admin Console. If you do not have an Okta account, you can create a free Okta Trial account or Okta Developer account.
  • (Recommended) Use the same email address for your Zoho Directory administrator account as your Okta administrator account. This will make it easier for you to administer the accounts.

 

1. Add Zoho Directory app to your Okta instance

Log in to your Okta account as an administrator (with administrator access).

Under Applications> Applications, search for the Zoho Directory app in the Okta Integration Network (App Integration Catalog). 

zoho-directory

Add Zoho Directory app in.

Fill in the Add Zoho Directory options. 

  • Application label - Name your Zoho Directory app.
For now, leave the default settings and click Done.

add-zoho-directory

Then click on the "Sign On" tab.  

zoho-directory-sign-on-settings

Click on "View Setup Instructions".

zoho-directory-sign-on-settings2

You will then be sent to View Setup Instructions for Zoho Directory. 

 

2. Set up SSO settings on Zoho Directory

Log into your Zoho Directory account

In a new browser tab, log in to your Zoho Directory account as an administrator (with administrator access), https://directory.zoho.com.

Open Single Sign-On Settings

In Zoho Directory, open your Single Sign-On (SSO) settings. 

Zoho Directory> Security> "Custom Authentication" tab.

zoho-directory-security

zoho-directory-security2

If you have trouble finding it, you can try this direct link to Custom Authentication, just add in your Zoho Directory name in the URL. https://directory.zoho.com/directory/yourzohodirectorydomainname/adminhome#/security/customauthentication

You should see something like this "Single Sign-On" section on Zoho Directory.

zoho-directory-settings

Add in your Okta Single Sign-On settings into Zoho Directory settings and click Save. 

  • ACS URL - Make a copy of this value from Zoho Directory, you will copy and paste this into Okta https://accounts.zoho.com/signin/samlsp/88889999
  • Sign-in URL - https://oktadomainname.okta.com/app/zohodirectory/oktasinglesignonlinkid/sso/saml
  • Sign-out URL (Optional) - This is optional.
  • Change Password URL (Optional) - This is optional.
  • Verification Certificate (okta.cert) - For the "Verification Certificate" (okta.cert) you will need download this from Okta. 

In Zoho Directory, click Browse and upload your okta.cert certification file into the "Verification Certificate" section.

upload-vertication-certificate

You will find your unique link from your "View Setup Instructions" for Zoho Directory from earlier. You will find that it looks something like this: https://oktadomainname.okta.com/admin/org/security/oktasinglesignonlinkid/cert

zoho-directory-okta-cert0

Make sure you download the .cert file, and give it a name. You can use "okta.cert" if you like. 

zoho-directory-okta-cert

Click Update

upload-vertication-certificate2

You will then get a "SAML configuration has been updated successfully" notification once it has been successfully set up in Zoho Directory. 

zoho-directory-settings2

3. Set up SSO settings on Okta

In Okta Admin Console, you will see the details you need to fill in your Zoho Directory "SSO Provider details". (Under "Sign On" tab).

Add in your Zoho Directory Single Sign-On settings into Okta.


zoho-directory-okta-acs-link-1

You can add the ACS URL from Zoho Directory, and put it in Okta under the "Advanced Sign-on Settings" section (Under "Sign On" tab).

zoho-directory-relay-state

zoho-directory-sign-on-settings3

 

4. Test that SSO is working on Zoho Directory

When you are ready, let's test that it works.

In Okta Admin Console, let's assign a user to the application. (Applications> Applications> Zoho Directory app)

Go to "Assignments" tab. (Applications> Applications> Zoho Directory app> "Assignments)

Select "Assign" and "Assign to People".

assign-test-user

Select our test user, click "Assign" and then "Done".

Now let's log into our Okta instance as a test user. You may need to refresh your browser if you had the browser window already open.

Then click on "Zoho Directory" application icon (chiclet).

okta-add-zoho-directory

When I click on it, it takes me to Zoho Directory. 

zoho-directory-add-okta-success

Success, you will be logged in successfully to your Zoho Directory account!

 

Troubleshooting:

User doesn't exist
The email address yyy@yyyy.com cannot be found. Contact your admin yyy@yyyy.com to resolve the issue.

user-does-not-exist

If your users see this error message, make sure that:

  1. User has been created and added in Zoho Directory.
  2. User has activated their account on Zoho Directory.

1. User has been created and added in Zoho Directory. You will find the ability to add users under Zoho Directory> Users> Add User. 

user-does-not-exist3

2. User has activated their account on Zoho Directory. That is, they have been "invited to join Zoho Directory" and they will need to "Confirm" their new Zoho Directory account and join your Zoho Directory organisation. 

user-does-not-exist2

user-does-not-exist4

zoho-directory-sign-up-account1

 

 

More information:

Topics: okta, sso

Vu Long Tran

Written by Vu Long Tran

Solutions Engineer APAC. ex-@Forrester consultant. Writing on #cloud #howto guides and #tech tinkering!