Zendesk

Before You Begin

Introduction

This document describes how to configure Oracle Identity Cloud Service to provide Single Sign-On (SSO) and user provisioning for Zendesk.

About Zendesk

Zendesk is a Software-as-a-Service (SaaS) solution used for better customer relationships. It empowers organizations to improve customer engagement and to better understand their customers.

After integrating Zendesk with Oracle Identity Cloud Service:

  • Users can access Zendesk using their Oracle Identity Cloud Service login credentials.
  • Users can launch Zendesk using the Oracle Identity Cloud Service My Apps console.
  • Admins can assign and revoke user access to the Zendesk app using the Oracle Identity Cloud Service administration console.

What Do You Need?

  • An Oracle Identity Cloud Service account with authorization rights to manage apps and users (Identity Domain Administrator or Application Administrator).
  • A Zendesk account with authorization rights to configure federated authentication and user provisioning.
  • Identity Provider metadata. You can use the following URL to access the metadata: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata and save the metadata in a text file. Use this file later to obtain the identity provider certificate in fingerprint format in the "Obtaining the Identity Provider Signing Certificate in Fingerprint Format" section.
  • Team name mentioned while creating an account with Zendesk. This Team name is used as the Domain Name value while configuring Zendesk in Oracle Identity Cloud Service. For more information, see the "Registering and Activating the Zendesk App" section.

Obtaining the Identity Provider Signing Certificate in Fingerprint Format

Use this section to obtain the identity provider signing certificate in a format that is suitable for Zendesk.

  1. Use the following URL to access the identity provider metadata: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata.

  2. In the metadata file, locate the dsig:X509Certificate tags.

  3. Copy the content between the dsig:X509Certificate tags into a text file.

    Image img1.png displays the metadata content with md:IDPSSODescriptor and dsig:X509Certificate tags highlighted.

  4. Add -----BEGIN CERTIFICATE----- at the beginning of the content.

  5. Add -----END CERTIFICATE----- at the end of the content. This content is the Oracle Identity Cloud Service signing certificate.

    Image img2.png displays the text file with the certificate content highlighted.

  6. Access the URL https://www.samltool.com/fingerprint.php to format the certificate. The Calculate Fingerprint page appears.

  7. Paste the certificate that you obtained earlier in the X.509 cert text box.

  8. Select sha256 from the Algorithm drop-down list, and then click CALCULATE FINGERPRINT.

  9. Make note of the fingerprint from the Formatted FingerPrint text box.

    Note: Use this fingerprint later during SSO configuration in the "Configuring SSO for Zendesk" section.

Configuring SSO for Zendesk

  1. Access Zendesk using the URL: https://<Domain_Name>.zendesk.com/access/normal/. The Zendesk Dashboard page appears.

    Note: This is the Domain Name that you specified as Team name while creating an account in Zendesk. For more information, see the "What Do You Need?" section.

  2. Click the grid icon in the upper right corner, and then select Admin Center from the drop-down list. The Zendesk Admin Center page appears in an another tab.

  3. Click Security settings under the Security section. The Staff members page appears.

  4. Click Single sign-on in the left navigation menu. The Single sign-on page appears.

  5. Click Configure next to SAML.

  6. Use the table to update the federated authentication attributes under the SAML section, and then locate and click Save. A success message is displayed stating that the security settings is saved successfully.

    Attribute Value
    Enabled Select the check box.
    SAML SSO URL Enter the Sign-in URL/SSO Endpoint: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/idp/sso.
    Certificate fingerprint Paste the sha256 fingerprint that you obtained in the "Obtaining the Identity Provider Signing Certificate in Fingerprint Format" section.

  7. To enable SSO for Staff members, click Staff members in the left navigation menu. The Staff members page appears.

  8. Select the External authentication check box, locate and then click Single sign-on.

  9. Click Save. A success message is displayed stating that the security settings is saved successfully.

  10. To enable SSO for End users, click End-users in the left navigation menu. The End users page appears.

  11. Locate and select the External authentication check box, and then click Save. A success message is displayed stating that the security settings is saved successfully.

  12. Go back to the previous tab of Zendesk Dashboard page.

  13. In the left navigation menu, hover over and click the Admin icon. The Overview page displays the SYSTEM UPDATES of the company.

  14. In the left navigation menu, locate the CHANNELS section, and then select API. The Zendesk API page appears.

  15. Under the Settings tab, enable Token Access. A success message is displayed stating that the token access is enabled.

  16. Click the + icon next to Active API Tokens. The Create a new token section appears.

  17. Click Copy, and then make note of the API Token.

    Note: It is recommended to note the API Token immediately as the API Token appears only once. Use this API Token value while enabling user provisioning for the Zendesk app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

  18. Click Save. A success message is displayed stating that API token is updated.

Configuring Zendesk in Oracle Identity Cloud Service

Use this section to register and activate Zendesk, and to enable provisioning and synchronization for Zendesk.

Registering and Activating the Zendesk App

  1. Access the Oracle Identity Cloud Service administration console, select Applications, and then click Add.

  2. Click App Catalog.

  3. Search for Zendesk, and then click Add.

  4. In the App Details section, enter your Zendesk Domain Name, and then click Next.

    Note: This is the Domain Name that you specified as Team name while creating an account in Zendesk. For more information, see the "What Do You Need?" section.

  5. Click Next to enable provisioning and synchronization for Zendesk. Oracle Identity Cloud Service displays the Provisioning page.

Enabling Provisioning and Synchronization for Zendesk

Use this section to enable provisioning and synchronization for managing user accounts in Zendesk through Oracle Identity Cloud Service.

Enabling Provisioning

  1. On the Provisioning page, select Enable Provisioning.

  2. Under the Configure Connectivity section, enter the Administrator Username.

  3. Enter the API Token.

    Note: This is the API Token that you obtained while performing the steps in the "Configuring SSO for Zendesk" section.

  4. Click Test Connectivity. A success message is displayed stating that the connection is successful.

  5. To view predefined attribute mappings between the user account fields defined in Zendesk and the corresponding fields defined in Oracle Identity Cloud Service, click Attribute Mapping, and then click OK.

    Note: To add a new attribute for provisioning, click Add Row, specify the attributes in the User and Zendesk Account columns, and then click OK. For example, if you want to add the External ID field, enter $(user.externalId) in the User column, and then select the corresponding field from the drop-down list in the Zendesk Account column.

  6. Specify the provisioning operations that you want to enable for Zendesk:

    Note: By default, the Create Account, Update Account, De-activate Account and Delete Account check boxes are selected.

    Create Account: Automatically creates a Zendesk account when Zendesk access is granted to the corresponding user in Oracle Identity Cloud Service.

    Update Account: Automatically updates a Zendesk account when the corresponding user account is edited in Oracle Identity Cloud Service.

    De-activate Account: Automatically suspends or activates a Zendesk account when the Zendesk access is deactivated or activated for the corresponding user in Oracle Identity Cloud Service.

    Delete Account: Automatically removes an account from Zendesk when Zendesk access is revoked from the corresponding user in Oracle Identity Cloud Service.

Enabling Synchronization

  1. On the Provisioning page, select Enable Synchronization.

  2. From the User Identifier drop-down list, select the Oracle Identity Cloud Service user attribute that you want to match with the corresponding record fetched from Zendesk:

    Note: By default, the Primary Email Address option is selected from the drop-down list. It is recommended to leave this default attribute for accurate synchronization of user records.

    Primary Email Address: Primary email address of the Oracle Identity Cloud Service user.

    User Name: User name of the Oracle Identity Cloud Service user.

  3. To match a Zendesk account attribute with the existing Oracle Identity Cloud Service user, select an attribute from the Application Identifier drop-down list.

    Note: By default, the Email option is selected that represents the Email attribute of the Zendesk account. It is recommended not to change this default option.

  4. From the When exact match is found drop-down list, select one of the following actions to be performed when a matching Oracle Identity Cloud Service user is found for an account:

    Link and confirm: Automatically links and confirms the matched account to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. 

    Link but do not confirm: Automatically links all the matched accounts to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. You need to manually confirm the linked accounts. 

  5. In the Max. number of creates field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be created during the synchronization run.

  6. In the Max. number of deletes field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be deleted during the synchronization run.

    After enabling provisioning and synchronization for Zendesk, you can synchronize the existing account details from Zendesk and link them to the corresponding Oracle Identity Cloud Service users. For more information on performing synchronization tasks, see the Importing User Accounts from a Software as a Service Application section in Administering Oracle Identity Cloud Service.

    You can also manage Zendesk accounts through Oracle Identity Cloud Service. For more information on performing provisioning tasks, see the Managing Oracle Identity Cloud Service Users and Managing Oracle Identity Cloud Service Groups sections in Administering Oracle Identity Cloud Service.

  7. Click Finish, and Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Verifying the Integration

Use this section to verify that SSO works when initiated from Oracle Identity Cloud Service (IdP initiated SSO) and Zendesk (SP initiated SSO).

Verifying Identity Provider Initiated SSO from Oracle Identity Cloud Service

  1. Access the Oracle Identity Cloud Service My Profile console using the URL: https://<IDCS-Service Instance>.identity.oraclecloud.com/ui/v1/myconsole.

  2. Log in using credentials for a user that is assigned to the Zendesk app. Oracle Identity Cloud Service displays a shortcut to Zendesk under My Apps.

  3. Click Zendesk. The Zendesk Home page appears.

  4. In the upper-right corner of the header menu, confirm that the user that is logged in is the same for both Zendesk and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Oracle Identity Cloud Service works.

Verifying Service Provider Initiated SSO from Zendesk

  1. Access Zendesk using the URL: https://<Domain_Name>.zendesk.com/. The Zendesk website page appears.

    Note: This is the Domain Name that you specified as Team name while creating an account in Zendesk. For more information, see the "What Do You Need?" section.

  2. In the upper-right corner, click Sign in. You are redirected to the Oracle Identity Cloud Service login page.

  3. Log in using credentials for a user that is assigned to the Zendesk app. The Zendesk Home page appears.

  4. In the upper-right corner of the header menu, confirm that the user that is logged in is the same for both Zendesk and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Zendesk works.

Troubleshooting

Use this section to locate solutions to common integration issues.

Known Issues

Zendesk displays the message, "Cannot sign in suspended user #(auto generated error value)"

Cause 1: The user account assigned to Zendesk is suspended in Zendesk under the People page, and the user attempts to initiate single sign-on.

Solution 1: Ensure that the user account is activated under the People page in the Zendesk app.

Oracle Identity Cloud Service displays the message, "You are not authorized to access the app. Contact your system administrator."

Cause 1: The SAML 2.0 integration between the Oracle Identity Cloud Service Zendesk app and Zendesk is deactivated.

Solution 1:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select Zendesk.
  • In the App Details section, click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Cause 2: The administrator revokes access for the user at the same time that the user tries to access the Zendesk app using Oracle Identity Cloud Service.

Solution 2:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select Zendesk.
  • In the App Details section, select Users, and then click Assign to re-assign the user.

Cause 3: The user account assigned to Zendesk is deactivated in Oracle Identity Cloud Service under the Zendesk application's Users tab, and the user attempts to initiate single sign-on from Zendesk.

Solution 3: Ensure that the user account is activated under the Users tab of the Zendesk application in Oracle Identity Cloud Service.

Unknown Issues

For unknown issues, contact Oracle Support:

  1. Go to https://support.oracle.com.

  2. Select Cloud Support, and then sign in with your support credentials.

  3. In the Cloud Dashboard, confirm that there are no planned outages in Oracle Identity Cloud Service, and then click Create Service Request.

  4. Select Oracle Identity Cloud Service as the service type.

  5. Complete your service request.