Zendesk Integration

®

Overview

This article describes the integration between the Cloud SSO app and the Zendesk® platform.

Features

With Zendesk's Single Sign-on feature, you can authenticate your admins, agents, and users if they have credentials in iMIS. When enabled, the Zendesk password is no longer used; instead, the iMIS password is used to authenticate and allow access into Zendesk.

At this time, the following profile fields are synchronized between iMIS and Zendesk:

iMIS ID
Name (Full Name)
Primary E-mail
Primary Phone Number

Users are matched via their primary e-mail address in iMIS. Regardless of the user's role or access level in iMIS, if there is a matching primary e-mail in Zendesk (this includes agents and admins), they will be signed in.

At this time, customizing which users are allowed to sign in, or customizing the profile fields that are synchronized via the Cloud SSO is not supported.

Note that any users who are not explicitly marked as Agents or Admins in Zendesk will be signed in as end-users and will only be able to access their own tickets (which were previously submitted via that e-mail address).

To send additional profile fields, our iTransfer app (sold separately) can be set up to synchronize iMIS contact/profile information with Zendesk on a regular basis.

The following Zendesk platforms are supported:

Zendesk Support™
Zendesk Guide™

Other Zendesk apps and services may work but are untested at this time.

Configuration

Navigate to your ZenDesk Admin area, located at https://<your-zendesk-subdomain>.zendesk.com/admin/.

Be sure to configure your Zendesk Guide help center, otherwise end-users that sign in will receive a 404 error as this is the default page that loads for end-users after signing in.

Your Zendesk Guide URL is your Zendesk subdomain followed by /hc. If this URL loads correctly in a browser, you're good to go!

Configure JWT SSO

Refer to the Zendesk Support Article: Enabling JWT (JSON Web Token) single sign-on

In the Admin area:

Navigate to Security > Single sign-on.
Next to JSON Web Token, select Configure.
In a new browser tab, navigate to Cloud SSO > App Registrations.
Click on Add App Registration.
- Change the SSO Profile Type to Zendesk Profile.
- Give your integration a friendly name, such as Contoso Helpdesk.
- Under Zendesk Subdomain, enter the subdomain of your Zendesk account (e.g. yourcompanyname.zendesk.com).

Even if you have a custom domain set up through Zendesk, such as support.yourcompany.com, you will still need to enter your account's Zendesk subdomain.

For Zendesk JWT Shared Secret, switch back to the Zendesk Admin Center and copy the value from the Shared secret field into this field.
Press Save App Registration.

Next, navigate to Endpoint Info. Under Specialized Endpoints, you should see a Zendesk® Endpoint field. Press the copy value button to the left of the value.

Then, switch back to the Zendesk Admin Center, and paste this value into the Remote login URL field.

Next, make sure that Update of external IDs? is set to Off.

Turning this option on can result in a potential security issue, as someone could create an account with a staff e-mail address and sign in, causing Zendesk to update the external ID and sign them in with agent or admin priveleges. Always leave this option set to OFF.

Finally, check the Enabled box and press Save at the bottom of the page.

Enable SSO for Staff Users

To enable the new SSO profile for staff members (agents and admins):

Navigate to Security > Staff members.
Check the box next to External authentication.
Change the radio button to Single sign-on. You should see a label that says: "Enabled methods: JSON Web Token".
Finally, press Save.

Any users in iMIS that have credentials and have matching primary e-mail addresses to Zendesk agents or admins, will be able to sign in and access any resources which that Zendesk user has access to.

Ensure that all staff users have credentials and associated External IDs in Zendesk.

Setup Recommendation

During initial setup, either use the iTransfer app (sold separately) to pre-synchronize all staff members so that their External IDs are set, or follow these steps:

Enable SSO only for Staff users.
Have all staff sign in to Zendesk using the SSO. Ensure the "External ID" field is set correctly on all staff profiles in Zendesk.
Finally, enable SSO for end users.

This will ensure that an end user cannot sign in as an agent or admin.

Enable SSO for End Users

To enable the new SSO profile for end users:

Navigate to Security > End users.
Check the box next to External authentication.
You should see a label that says: "Single sign-on Enabled methods: JSON Web Token".
Finally, press Save.

SSO Behavior

The following section describes how user accounts behave between iMIS and Zendesk.

Zendesk SSO standard behavior is to match on primary e-mail address. This is not customizable. Therefore, ensure that your users' primary e-mail addresses are up to date and unique in iMIS.

Sign-in Behaviors

iMIS User Exists, Zendesk User Does Not Exist

If an iMIS user attempts to sign in and a corresponding Zendesk user (via primary email) was not found, a new user will be created and they will be directed to the Help Center. If the Zendesk Guide is not enabled, the user will see a "Not Found" error.

iMIS User Exists, Zendesk User Exists

If an iMIS user attempts to sign in and a corresponding Zendesk user was found via a primary email match, that user is signed in, regardless of the type of user they are (e.g. admin, agent, end user), unless that group type does not have SSO enabled at all (see above).

iMIS User Exists, Zendesk Primary E-mail Found

If an iMIS user attempts to sign in and a corresponding Zendesk user was found via a primary email match, and this is the first time this user has signed in, the account will be matched on the primary e-mail address and the Zendesk profile will be updated with iMIS information.

Any tickets that were previously available to this user's primary e-mail address in Zendesk will be visible to this user. For this reason, it is important that:

iMIS e-mail addresses are kept unique
E-mail addresses are verified as belonging to the corresponding contact record in iMIS
E-mail addresses are not shared between members or assigned to a company which also has sign-in credentials in iMIS

If two or more users share a primary e-mail address in iMIS, and both have sign-in credentials, it is possible that the Zendesk user profile could get updated with incorrect information from iMIS.

iMIS User Doesn't Exist, Zendesk User Exists

If an iMIS user does not exist, does not have credentials on their account, or is otherwise unable to log in to iMIS, the Zendesk account will not be accessible. However, standard ticket e-mail communication will still work.

Profile Sync

The following fields are sent and mapped in Zendesk whenever a user signs in:

iMIS Field	Zendesk Field	Update?
iMIS ID	External ID	No (Only if not exists in Zendesk, otherwise Zendesk value left intact)
Full Name	Name	Yes
Primary E-mail	Primary E-mail	No (Used as key / lookup, or to create a new Zendesk user)
Primary Phone (Optional)	Phone	Yes (Only if exists in iMIS, otherwise Zendesk value left intact)

Remember, you can sync additional profile fields, including an unlimited number of Zendesk user-defined fields, with our iTransfer app.

Fallback Authentication

In the event that the Cloud SSO is not functioning, staff and end users can still access Zendesk.

End Users and Staff Users

End users can sign in directly to Zendesk using this link: https:// <your-subdomain> .zendesk.com/access/normal

Administrators

Zendesk Admins can use the following link to request a one-time sign-in link via e-mail: https:// <your-subdomain> .zendesk.com/access/sso_bypass

Zendesk Support, the Zendesk Support logo, Zendesk Guide, and the Zendesk Guide logo are registered trademarks of Zendesk, Inc.