Tutorial: Configure Zendesk for automatic user provisioning

Article
10/23/2023

This tutorial describes the steps you need to perform in both Zendesk and Microsoft Entra ID to configure automatic user provisioning. When configured, Microsoft Entra ID automatically provisions and de-provisions users and groups to Zendesk using the Microsoft Entra provisioning service. For important details on what this service does, how it works, and frequently asked questions, see Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra ID.

Capabilities supported

Create users in Zendesk.
Remove users in Zendesk when they do not require access anymore.
Keep user attributes synchronized between Microsoft Entra ID and Zendesk.
Provision groups and group memberships in Zendesk.
Single sign-on to Zendesk (recommended)

Prerequisites

The scenario outlined in this tutorial assumes that you already have the following prerequisites:

A Microsoft Entra tenant.
A user account in Microsoft Entra ID with permission to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).
A user account in Zendesk with Admin rights.
A Zendesk tenant with the Professional plan or better enabled.

Step 1: Plan your provisioning deployment

Learn about how the provisioning service works.
Determine who will be in scope for provisioning.
Determine what data to map between Microsoft Entra ID and Zendesk.

Step 2: Configure Zendesk to support provisioning with Microsoft Entra ID

Sign in to Zendesk Admin Center.
Navigate to Apps and integrations > APIs > Zendesk APIs.
Click the Settings tab, and make sure Token Access is enabled.
Click the Add API token button to the right of Active API Tokens.The token is generated and displayed.
Enter an API token description.
Copy the token and paste it somewhere secure. Once you close this window, the full token will never be displayed again.
Click Save to return to the API page.If you click the token to reopen it, a truncated version of the token is displayed.

Step 3: Add Zendesk from the Microsoft Entra application gallery

Add Zendesk from the Microsoft Entra application gallery to start managing provisioning to Zendesk. If you have previously setup Zendesk for SSO, you can use the same application. However it is recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery here.

Step 4: Define who will be in scope for provisioning

The Microsoft Entra provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following steps to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described here.

Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an attribute based scoping filter.
If you need additional roles, you can update the application manifest to add new roles.

Step 5: Configure automatic user provisioning to Zendesk

This section guides you through the steps to configure the Microsoft Entra provisioning service to create, update, and disable users and/or groups in Zendesk based on user and/or group assignments in Microsoft Entra ID.

Important tips for assigning users to Zendesk

Today, Zendesk roles are automatically and dynamically populated in the Azure portal UI. Before you assign Zendesk roles to users, make sure that an initial sync is completed against Zendesk to retrieve the latest roles in your Zendesk tenant.
We recommend that you assign a single Microsoft Entra user to Zendesk to test your initial automatic user provisioning configuration. You can assign additional users or groups later after the tests are successful.
When you assign a user to Zendesk, select any valid application-specific role, if available, in the assignment dialog box. Users with the Default Access role are excluded from provisioning.

Configure automatic user provisioning for Zendesk in Microsoft Entra ID

Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity > Applications > Enterprise applications
In the applications list, select Zendesk.
Select the Provisioning tab.
Set the Provisioning Mode to Automatic.
Under the Admin Credentials section, input the admin username, secret token, and domain of your Zendesk account. Examples of these values are:
- In the Admin Username box, fill in the username of the admin account on your Zendesk tenant. An example is admin@contoso.com.
- In the Secret Token box, fill in the secret token as described in Step 6.
- In the Domain box, fill in the subdomain of your Zendesk tenant. For example, for an account with a tenant URL of https://my-tenant.zendesk.com, your subdomain is my-tenant.
The secret token for your Zendesk account can be generated by following steps mentioned in Step 2 above.
After you fill in the boxes shown in Step 5, select Test Connection to make sure that Microsoft Entra ID can connect to Zendesk. If the connection fails, make sure your Zendesk account has admin permissions and try again.
In the Notification Email box, enter the email address of the person or group to receive the provisioning error notifications. Select the Send an email notification when a failure occurs check box.
Select Save.
Under the Mappings section, select Synchronize Microsoft Entra users to Zendesk.
Review the user attributes that are synchronized from Microsoft Entra ID to Zendesk in the Attribute Mappings section. The attributes selected as Matching properties are used to match the user accounts in Zendesk for update operations. To save any changes, select Save.
Under the Mappings section, select Synchronize Microsoft Entra groups to Zendesk.
Review the group attributes that are synchronized from Microsoft Entra ID to Zendesk in the Attribute Mappings section. The attributes selected as Matching properties are used to match the groups in Zendesk for update operations. To save any changes, select Save.
To configure scoping filters, follow the instructions in the scoping filter tutorial.
To enable the Microsoft Entra provisioning service for Zendesk, in the Settings section, change Provisioning Status to On.
Define the users or groups that you want to provision to Zendesk. In the Settings section, select the values you want in Scope.
When you're ready to provision, select Save.

This operation starts the initial synchronization of all users or groups defined in Scope in the Settings section. The initial sync takes longer to perform than later syncs. They occur approximately every 40 minutes as long as the Microsoft Entra provisioning service runs.

You can use the Synchronization Details section to monitor progress and follow links to the provisioning activity report. The report describes all the actions performed by the Microsoft Entra provisioning service on Zendesk.

For information on how to read the Microsoft Entra provisioning logs, see Reporting on automatic user account provisioning.

Connector limitations

Zendesk supports the use of groups for users with Agent roles only. For more information, see the Zendesk documentation.
When a custom role is assigned to a user or group, the Microsoft Entra automatic user provisioning service also assigns the default role Agent. Only Agents can be assigned a custom role. For more information, see the Zendesk API documentation.
Import of all roles will fail if any of the custom roles has a display name similar to the built in roles of "agent" or "end-user". To avoid this, ensure that none of the custom roles being imported has the above display names.

More resources

Next steps

Learn how to review logs and get reports on provisioning activity