Using SAML for single sign-on (Professional and Enterprise) Follow

professional enterprise plans

Zendesk supports Secure Assertion Markup Language (SAML), which allows you to provide single sign-on (SSO) for your Zendesk using enterprise identity providers such as Active Directory and LDAP. Single sign-on using SAML is available on Professional and Enterprise.

Note: If you're on Team or above, you can set up enterprise single sign-on using JWT (JSON Web Token) remote authentication. See Setting up single sign-on with JWT (JSON Web Token).

Implementing single sign-on via SAML means that the sign in process and user authentication are handled entirely outside of your Zendesk. Your users will not directly visit your Zendesk Help Center to sign in. Instead users sign in to the corporate system (authenticated by Active Directory or LDAP for example) and click a link to access Zendesk and are automatically signed in. No need to enter separate sign-in credentials for Zendesk.

You can build a SAML server in-house (using OpenAM, for example) or choose a SAML service such as Okta, OneLogin, and PingIdentity. You'll need to set these up yourself outside of Zendesk. What you enable in Zendesk is the option to use SAML for single sign-on (see Enabling SAML single sign-on in your Zendesk below).

After you've enabled SAML (by building a SAML server yourself or by using one of the SAML services), all user management and authentication is handled outside of your Zendesk. However, changes made outside of your Zendesk are immediately synced back to your Zendesk. For example, if you add a user in your internal Active Directory or LDAP authentication system, the change is synced back through your SAML provider and the user is added to your Zendesk. If you delete a user in your system, the user will no longer be able to sign in to Zendesk (though their account will still exist in Zendesk).

The only user data that is stored in Zendesk is the user name and email address. However, you can also choose to sync the following user data: organization, phone, tags, given name, surname. You do this with by adding these attributes to your SAML assertion code. See User attributes that can be set in SAML. Zendesk does not store user passwords.

How SAML for Zendesk works

SAML for Zendesk works the way SAML does with all other service providers. The typical use case is that your users belong to a corporation and all user authentication is managed by your corporate authentication system (for example, Active Directory or LDAP), which is referred to generically as an identity provider (IdP). The service provider (SP), in this case of course Zendesk, establishes a trust relationship with IdP and allows that external IdP to authenticate users and then seamlessly sign them in to Zendesk. In other words, a user signs in at work and then has automatic access to the many other corporate applications such as email, your CRM, and so on without having to sign-in separately to those services. Aside from the convenience this provides to users, all user authentication is handled internally by a system that you have complete control over.

After you've enabled SAML as the type of single sign-on for your Zendesk, users who visit your Zendesk and attempt to sign in are redirected to your SAML server for authentication. Your users' identities can be stored either on the SAML server or can be validated by an identity directory such as Microsoft Active Directory or LDAP. Once authenticated, users are redirected back to your Zendesk and automatically signed in.

Another supported workflow is having the user sign in to your own website directly rather than to your Zendesk instance. The website sends a request to the identity provider to validate the user. The website then sends the provider's response to the SAML server, which forwards it to your Zendesk, which grants a session to the user.

Returning visitors are automatically authenticated if their SAML assertions are cached. Assertions are packets of security information that are used to make access-control decisions.

Note: To access your Zendesk account from many of the Zendesk integrations, or to do any development work with the Zendesk API or App framework, you will need a Zendesk password. Single sign-on will not work in these cases.

Configuring your Zendesk for new users

A Zendesk user profile is created for any new user who accesses your Zendesk through SAML. Because they're authenticated with a non-Zendesk password, the profile is created without a password. It's not necessary to sign in to Zendesk. However, if you forget to make certain changes in Zendesk, every new user will get an email notifying them to verify their email address and create a username and password.

To prevent this from happening, make sure to uncheck the following options on the End-users (Customers) page of the Zendesk admin interface (Admin > Customers):
  • "Also send a welcome e-mail when a new user is created by an agent or admin"
  • "Allow users to change their passwords"

Configuring your SAML implementation

You have a number of options when considering a SAML service, including building a SAML server in-house (for example, OpenAM) or choosing a SAML service such as Okta, OneLogin, and PingIdentity.

To set up SAML in your Zendesk, you'll need the following:

  • A SAML server with provisioned users or connected to an identity repository such as Microsoft Active Directory or LDAP

  • The Remote Login URL for your SAML server (sometimes called SAML Single Sign-on URL)

  • The SHA1 or SHA2 fingerprint of the SAML certificate from your SAML server. X.509 certificates are supported and should be in PEM or DER format. There is no upper limit on the size of the SHA fingerprint.

After you have your SAML server properly configured, you use the remote login URL and the SHA fingerprint to configure SAML within your Zendesk.

Other SAML servers may require additional information

Other SAML servers may ask for the following information when configuring an integration with Zendesk:

  • The Access Consumer Service (ACS) URL is https://accountname.zendesk.com/access/saml (case sensitive)
    Note: In the URL above, replace 'accountname' with your Zendesk subdomain.
  • Redirects to SAML Single Sign-on URL are HTTP POST

  • Hashing algorithm (ADFS): Zendesk supports the SHA-1 and SHA-2 algorithm when using Active Directory Federation Services (ADFS)

Integration with Active Directory Federation Services (ADFS)

Currently, we only support Forms Based Authentication for ADFS. Integrated Windows Authentication is not supported.

User attributes that can be set in SAML

You can set the following user attributes for users signing in via SAML:

Table 1. Supported attributes
Attribute Description
organization Name or id of an organization to add the user to. The external_id attribute of an organization is not supported. If the organization doesn't exist in Zendesk, it won't be created. The user will still be created, but they won't be added to any organization.
organizations Comma separated values such as org1, org2, org3
organization_id Example: 134211213
organization_ids Comma separated values such as 23423433, 234324324, 23432
ou Name of an organization unit. Specify it as an organization attribute.
phone A phone number, specified as a string.
tags Tags to set on the user. The tags will replace any other tags that may exist in the user's profile.
remote_photo_url URL for a photo to set on the user profile.
locale (for end-users)

locale_id (for agents)

The locale in Zendesk, specified as a number. To get a list of valid numbers, see Locales in the API docs.
role The user's role. Can be set to "user", "agent", or "admin". Default is "end-user".
custom_role_id Applicable only if the value of the role attribute above is "agent". You can get the ids of your custom roles with the Custom Roles API.
external_id A user id from your system if your users are identified by something other than an email address, and if their email addresses are subject to change. Specified as a string.

You set these attributes using an attribute statement in your SAML assertion. Example:

<saml:AttributeStatement>
   <saml:Attribute Name="organization">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">Organization name</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="tags">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">tag1 tag2</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="phone">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">555-555-5555</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">Zack</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">Doe</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="role">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">agent</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="custom_role_id">
      <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">12345</saml:AttributeValue>
   </saml:Attribute>
</saml:AttributeStatement>

Zendesk supports a series of InCommon Federation Attributes to set user attributes as part of the sign in. Examples:

Table 2. Attribute names
Friendly name SAML2 formal name
ou (organization unit) urn:oid:2.5.4.11
displayName urn:oid:2.16.840.1.113730.3.1.241

Configuring the identity provider

Table 3. Identity provider attributes
Attribute Value
entityID https://your_subdomain.zendesk.com/
AudienceRestriction your_subdomain.zendesk.com

where your_subdomain is your Zendesk subdomain.

Zendesk enforces the AudienceRestriction attribute. See the code snippet at the end of this article.

Enabling SAML single sign-on in your Zendesk

With your SAML server configured and the information you need for setting up SAML in Zendesk at hand, sign in to your Zendesk as an administrator and follow this procedure.

To enable SAML in your Zendesk

  1. Click the Admin icon () in the sidebar, then select Security from the Settings category.
  2. Select the Admins & Agents or End-users tab.

    You can enable SAML single sign-on only for end-users, only for agents, or for both groups. You can't enable SAML for one group if the JWT SSO option is enabled for the other group. If you want to use single sign-on for both groups, both must be SAML or both must be JWT.

    If you started using Zendesk on or after August 21, 2013, the End-users tab is not available until you activate the Help Center. See Getting started with the Help Center.

  3. Select the SAML option.
  4. In the SAML SSO URL text box, enter the SAML login URL of your SAML server. Zendesk automatically adds a brand_id parameter to the URL. This is the Zendesk brand the user was on when they attempted to sign in.
  5. (Optional) Enter a logout URL where Zendesk can redirect users after they sign out of Zendesk.

    Zendesk automatically adds email, external_id, and brand_id parameters to the URL. If you prefer not having email and external id information in the URL, specify blank parameters in the logout URL. Example:

    https://www.xyz.com/user/signout/?email=&external_id=

  6. You can optionally restrict access to users within a range of IP addresses.
  7. Enter the Certificate Fingerprint. This is required for us to communicate with your SAML server.

  8. Click Save.
Note: When you enable single sign-on via SAML (and JWT), be aware that passwords do not expire (even if your Zendesk password policy is set to High) because passwords are not stored in Zendesk. Additionally, if agents manually add a Zendesk password to their account, these passwords will not expire.

Troubleshooting your SAML configuration

If you have difficulty setting up SAML, you may find the following information helpful.

Here is the Zendesk SAML 2.0 metadata:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="your_subdomain.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://accountname.zendesk.com/access/saml"/> <!-- Note: replace 'accountname' with your Zendesk subdomain -->
    </SPSSODescriptor>
</EntityDescriptor>

Zendesk expects a SAML assertion that looks like this:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="s2202bbbb
afa9d270d1c15990b738f4ab36139d463" InResponseTo="_e4a78780-35da-012e-8ea7-005056
9200d8" Version="2.0" IssueInstant="2011-03-21T11:22:02Z" Destination="https://accountname.zendesk.com/access/saml"> <!-- Note: replace 'accountname' with your Zendesk subdomain -->
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">myidp.entity.id
    </saml:Issuer>
    <samlp:Status xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        <samlp:StatusCode  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
Value="urn:oasis:names:tc:SAML:2.0:status:Success">
        </samlp:StatusCode>
    </samlp:Status>
    <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion
" ID="s2af6627280d72f061beb9f8b1635bd54cc2892317" IssueInstant="2011-03-21T11:22
:02Z" Version="2.0">
        <saml:Issuer>myidp.entity.id</saml:Issuer>
        <ds:Signature xmlns:ds="htt
p://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                <ds:Reference URI="#s2af6627280d72f061beb9f8b1635bd54cc2892317">

                    <ds:Transforms>
                        <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <ds:DigestValue>ifvqELggmae4/L5uxZF8wp5B9TI=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>
1FHS3gUk6H/aY1hTPeGuV+d4YRXOufDV41YAXmYyd8pIGEuB8TE5snXhi8GYt+GaDuKonlOtuTLF
... my signature value ...
Zj2jLeS6q7nIZMwuQRs=
            </ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
MIIDhzCCAvCgAwIBAgIJAKm2IOKHLajCMA0GCSqGSIb3DQEBBQUAMIGKMQswCQYDVQQGEwJOTzEN
.... The rest of the signing cerrtificate ....
KC0SMAlW99kwISj02MZfdtSGNd4RfR2ybmbAGDqfEBhnE/Tg8mP6/8mjDAbUtBXaKZ42eA==
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" NameQualifier="idp.accountname.com">firstnam.lastname@company.com</saml:NameID> <!-- Note: replace 'accountname' with your Zendesk subdomain -->
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData InResponseTo="_e4a78780-35da-012e-8ea7-0050569200d8" NotOnOrAfter="2011-03-21T11:32:02Z" Recipient="https://accountname.zendesk.com/access/saml"/></saml:SubjectConfirmation> <!-- Note: replace 'accountname' with your Zendesk subdomain -->
        </saml:Subject>
        <saml:Conditions NotBefore="2011-03-21T11:12:02Z" NotOnOrAfter="2011-03-21T11:32:02Z">
            <saml:AudienceRestriction>
                <saml:Audience>subdomain.zendesk.com</saml:Audience>      <!-- Note: Replace 'subdomain' with your Zendesk subdomain -->
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2011-03-21T11:22:02Z" SessionIndex="s25c49ea33a9598e2c930899f528b5f00fde2fe901">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
    </saml:Assertion>
</samlp:Response>
Have more questions? Submit a request

Comments

  • 0

    In particular, for folks who are using a SAML provider to provision user accounts in Zendesk, it would be really nice to call out to admins here that if you do this you also need to ensure that in Zendesk the "Also send a welcome e-mail when a new user is created by an agent or admin" and the "Allow users to change their passwords" checkboxes are both unchecked in Customers section of the Zendesk admin console.

    You could probably also call this info out on the Customers section of the Zendesk admin console.

    Otherwise every user created by provisioning from a SAML provider will get an e-mail notifying them to verify their e-mail address and create a username and password.

    Speaking from experience this would have been nice to know.

  • 0

    Hey Alan!

    Thanks for bringing that up! You make a good point. I'm going to pass this along to our Documentation team to see if we can make the docs on this more clear.

  • 0
    I've got the question as Renato Martins [March 24, 2015 14:32]. According to SAML specification my code sends on a logout request from Zendesk, but then Zendesk just sends me another logout request provoking a redirect loop.
  • 0
    Hi Maxim, this might help you if you're using simpleSAMLphp (it's part of the handling of requests, you should be able to find the right place to put it): http://pastebin.com/6eLaF3Rk Good luck!
  • 0
    @Renato, unfortunately I use Java OpenSAML and was hoping that Zendesk has somehow addressed the issue. But anyway it looks like your code will help me to implement my own workaround. Thank you very much! Hopefully Zendesk will fix the issue one day.
  • 0

    Hi guys, as James Peterson mentioned above, the only official, supported way to log a user out is by sending them to the access/logout endpoint. As you have noticed, SLO is not officially supported. One possible workaround might be to set your SSO logout URL to your IDP's logout endpoint, which will redirect the user there after ZD logout and the IDP can take it from there (keeping in mind that the IDP should not redirect back to access/logout, or a redirect loop might occur!)

    As for the issue at hand, I highly recommend letting our product team know about your issue and why you would like to see this functionality in the future. You can do this in our product feedback forum: https://support.zendesk.com/hc/en-us/community/topics/200132066-Product-feedback

    Thanks!

    Sam

  • 0

    The original post about SAML was written in 2011. I'm hoping for an update. Does ZenDesk support true-multilateral federation? This means consuming central federation metadata (such as provided by one of the many national federations here (https://refeds.org/federations/federations-map);  discovery for users where there might be hundreds of Identity Providers to choose from (https://discovery.refeds.org/guide/).

  • 0

    Anyone have success with ZenDesk and multilateral federations like InCommon? Anyone? Bueller?

  • 0

    Hey Jcwk! Sorry we didn't get back to you on this sooner. I'm following up to see what I can find out. :)

  • 0

    Hi Jcwk!

    Zendesk does support InCommon Federation Attributes to set user attributes as part of the sign in process; for example, you can set up the ou (organization unit), or the displayName. You can find more details about these attributes on this page - InCommon Federation Attribute Summary.

    Please let us know if this helps!

  • 0

    Alexander, That's great to hear. Before we can get to attribute release, we need to know if the ZenDesk service provider (SP) is able to consume multi-entity SAML metadata. Most international federations produce an aggregate of IdPs and SPs. Here's an example of InCommon's: https://spaces.internet2.edu/display/InCFederation/Metadata+Consumption .  Does ZenDesk consume multi-entity SAML metadata and provide a way (like a discovery service linked to in my comment above) for more than just 3 or 4 Identity Provider choices? Thanks so far!

  • 0

    @Jcwk - Thank you for your additional questions! I have created this ticket #1675584 to further check your specific workflow. Would it be OK to join us in the ticket? Thank you very much!

Please sign in to leave a comment.

Powered by Zendesk