How To
ForgeRock Identity Cloud
Integrations

Zendesk SSO integration with Identity Cloud as SAML identity provider

Last updated Jan 17, 2023

The purpose of this article is to provide information on how to configure ForgeRock Identity Cloud to integrate with Zendesk® using SAML2 federation for Single Sign-On (SSO). It assumes Identity Cloud is acting as the identity provider (IdP) and Zendesk as the service provider (SP).


Overview

This article describes how to enable your users to sign into Zendesk with Identity Cloud using SAML2 SSO in an SP-initiated flow. It assumes Identity Cloud is acting as the SAML IdP and Zendesk as the SP. Once configured, Zendesk end users will be presented with the ForgeRock Sign In screen to authenticate before being redirected to the Zendesk help center. 

Steps involved:

  1. Create a Circle of Trust (COT)
  2. Create the hosted IdP in Identity Cloud
  3. Configure Zendesk 
  4. Create the remote SP in Identity Cloud
  5. Test the end user experience

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have a Zendesk administrator account.
  • You have created a test user in Identity Cloud that corresponds to an end user in Zendesk, including a matching email address. See Manage identities for further information on creating users in Identity Cloud.
  • You have activated your Zendesk help center for end users. See Getting started with Guide for your help center: Setting up for further information.

Creating a Circle of Trust (COT)

  1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Circles of Trust and click Add Circle of Trust.
  2. Enter a name (no spaces) for your new COT, for example, ForgeRockCOT, and click Create.
  3. Add a description for the COT and click Save Changes.

Creating the hosted IdP in Identity Cloud

This step involves creating the hosted IdP in Identity Cloud and then generating the IdP metadata. The metadata contains information about the IdP which is required when configuring Zendesk.

Create a hosted IdP

  1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Hosted.
  2. Complete the following configuration:
    • Entity ID: Enter an ID (no special characters or spaces) for your hosted identity provider, for example, ForgeRockIDP.
    • Entity Provider Base URL: Verify the default URL is correct. This URL is used for all SAML2 related endpoints, so ensure other entities in your SAML deployment are able to access the specified URL.
    • Identity Provider Meta Alias: Enter a URL-friendly value to identify the identity provider, for example, idp.
    • Service Provider Meta Alias: Leave blank because we're only creating a hosted IdP.
    • Circles of Trust: Select the COT you created, for example, ForgeRockCOT.
  1. Click Create.

Generate the hosted IdP metadata

You'll use the IdP metadata when you configure SAML SSO in Zendesk.

To access the IdP metadata, navigate to the metadata URL in your browser, in the following format:

https://<tenant-env-fqdn>/am/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/[realmname]

In our example, the [entityID] is ForgeRockIDP and the [realmname] is alpha.

See How do I export and import SAML2 metadata in Identity Cloud? for further information.

Configuring Zendesk

Disclaimer

ForgeRock assumes no responsibility for errors or omissions in the third-party software or documentation.

The following steps describe how to configure SAML SSO so that end users can sign in to your Zendesk help center using Identity Cloud. You'll need to enter some details from the hosted IdP metadata that you generated previously. Once you have configured the SAML SSO you'll need to enable it for end users.

You must be logged into Zendesk as an Administrator to complete these steps.

Configure SAML SSO

  1. In Zendesk, go to Account > Security > Single sign-on.
  2. Click Edit next to SAML.
  3. Use the hosted IdP metadata that you generated previously to get the required values:
    • SAML SSO URL: Enter the single sign-on URL for the binding HTTP-POST, for example, https://<tenant-env-fqdn>/am/SSORedirect/metaAlias/alpha/ForgeRockidp.
    • Remote logout URL: Enter the single logout URL for the binding HTTP-POST, for example, https://<tenant-env-fqdn>/am/IDPSloPOST/metaAlias/alpha/ForgeRockidp.
    • Certificate fingerprint: Copy the X509 signing certificate from the IdP metadata and create a formatted hash. To do this, you can use OneLogin's Format a X.509 certificate tool to format the certificate. Then copy the value in “X.509 cert with header” and paste it into OneLogin's Calculate Fingerprint tool to get a Formatted Fingerprint, specifying sha256 as the hashing algorithm.

The values you enter should look similar to this:

  1. Click Save.

Enable SAML SSO for end users

  1. In Zendesk, go to Account > Security > End user authentication.
  2. Select the External authentication check box.
  3. Click Save.
Note

As a backup, end users will still be able to log into Zendesk directly by using this URL: https://<your-zendesk-instance>.zendesk.com/access/normal.

Creating the remote SP in Identity Cloud

Zendesk does not provide a file or URL for retrieving SP metadata, so you'll need to create one manually before you can configure the remote SP in Identity Cloud. 

Create the SP metadata XML file 

  1. Create an XML file, similar to this: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <EntityDescriptor entityID="https://<your-zendesk-instance>.zendesk.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">    <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">         <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>         <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<your-zendesk-instance>.zendesk.com/access/saml"/>     </SPSSODescriptor> </EntityDescriptor>

replacing <your-zendesk-instance> (in two places) with your Zendesk instance name.

  1. Save the file.

Configure the remote SP

  1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > Federation > Entity Providers and click Add Entity Provider followed by Remote.
  2. Import the metadatata .xml file that you created in the previous step, and select the COT (for example, ForgeRockCOT).
  1. Click Create.
  2. Select the Assertion Processing tab and configure the following attribute mappings for your assertion:
SAML Attribute Local Attribute
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname givenName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname sn

The Attribute Map appears similar to this:

  1. Scroll down and click Save Changes.

Testing the end user experience

Make sure you are logged out of Identity Cloud and Zendesk before running this test.

  1. Go to: https://<your-zendesk-instance>.zendesk.com/access.

The ForgeRock Sign In screen should appear.

  1. Enter the username and password for your test user (this is the matching user that exists in both Identity Cloud and Zendesk), and then click Next.

The Zendesk help center screen will appear after successful sign-in. 

See Also

SAML 2.0 federation in Identity Cloud

Configuring IDPs, SPs, and CoTs

Zendesk and ForgeRock Identity Cloud SAML based SSO in 5 minutes (blog post)


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.