Using SAML for single sign-on (Plus and Enterprise)

Using SAML for single sign-on (Plus and Enterprise)

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 to Plus and Enterprise accounts.

Note: If you're not on the Plus or Enterprise plans, 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 log in process and user authentication are handled entirely outside of your Zendesk. Your users will not directly visit your Zendesk web portal to log in. Instead users log in to the corporate system (authenticated by Active Directory or LDAP for example) and click a link to access Zendesk and are automatically logged in. No need to enter separate login 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 or delete a user in your internal Active Directory or LDAP authentication system, that change is synced back through your SAML provider, and the user is added to or deleted from your 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 log them in to Zendesk. In other words, a user logs 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 login 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 log 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 logged in.

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. When new users access your Zendesk a user profile created in Zendesk; however, since users are authenticated via SAML their Zendesk profiles do not contain a password.

Note: To access your Zendesk account from the Zendesk mobile app or 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 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 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 SHA1 fingerprint.

After you have your SAML server properly configured, you use the remote login URL and the SHA1 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 currently only supports SHA-1 algorithm when using Active Directory Federation Services (ADFS)

Integration with Active Directory Federation Services (ADFS)

Currently, we only support Forms Based Authentication for ADFS; we do not support Integrated Windows Authentication.

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.
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.
givenname The user's first name.
surname The user's last name.
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.
role The user's role. Can be set to "user", "agent", or "admin". Default is "user". If the user already exists in Zendesk, the existing role is not changed.
custom_role_id Applicable only if the role of the user is agent.

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>

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, log 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.
    Zendesk Classic: Select the Setting menu, then select Security.
  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.

    Zendesk Classic: Select the Single Sign-On tab.
  3. Select the SAML option.
    Zendesk Classic: Next to the SAML option, click Edit, and then select Enabled.
  4. In the SAML SSO URL input, enter the SAML login URL of your SAML server.

    The Remote logout URL and IP ranges are both optional, but the Certificate Fingerprint is required for us to communicate with your SAML server.

  5. 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="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>zendesk.com</saml:Audience>
            </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

  • Avatar
    Archie Montoyo

    Great info!

  • Avatar
    Nick Parker

    Will this allow us to use Google Apps as our Authentication provider?

  • Avatar
    Ben Rohrs

    @Nick: Ping Identity and others claim to let you use Google Apps as the IdP and integrate with SaaS apps over SAML, so I think this would work. If you're looking only for Google Apps authentication integration, I'd suggest maybe waiting a bit as this is in our product pipeline to be delivered soon.

  • Avatar
    Nick Parker

    Thanks very much Ben, I think I'll hold out for the Google Apps Authentication integration :)

  • Avatar
    Fredrik Linnander

    \o/ I just signed on to support.zendesk.com with my Google Apps account, this is great, and I'll also sit in the boat until we can logon to our own domain using Google Apps. great work!

  • Avatar
    John G

    This service again fails to support remote, mobile, or branch office scenarios (with variable IP) for our use.

    It expects 100% of authentication (from customers and techs) from the remote system...so don't plan on using this for just your internal staff if your IP changes.

    I have made suggestions to only have login requests from a special login URL (i.e. Contoso.Zendesk.com/RemoteAuth) be sent for remote authentication, but it has made no progress in over a year in the Zendesk team priority list.

  • Avatar
    Mvozila

    Did anyone get this to work in ADFS 2.0? I added the trust using the SAML 2.0 metadata successfully. However, I now need to create a custom claim so I don't get the issue below. Anyone get around this? If you can send the custom claim xml that would be greatly appreciated.

     

    The SAML authentication request had a NameID Policy that could not be satisfied.

    Requestor: zendesk.com

    Name identifier format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    SPNameQualifier:

    Exception details:

    MSIS1000: The SAML request contained a NameIDPolicy that was not satisfied by the issued token. Requested NameIDPolicy: AllowCreate: True Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress SPNameQualifier: . Actual NameID properties: null.

    This request failed.

    User Action

    Use the AD FS 2.0 Management snap-in to configure the configuration that emits the required name identifier.

  • Avatar
    Morten Primdahl

    Huge thanks to Charles Stephen Thompson of SecondMarket for kindly sending us his write up on configuring ADFS 2.0. See attached PDF. 

  • Avatar
    John G

    It would be nice if Zendesk would support WIA in their SAML request for the 90% of your Enterprise customer's whom use Microsoft Active Directory.

    Also, your SAML SSO for only named IP's (and not a URL based) doesn't work for the 90% of your customer's that need to work outside their company firewall.

    Please fix!  Otherwise, heck of a support ticket system :)

  • Avatar
    Wilson Carey

    Is it possible to update user metadata via the SAML token, as it is with the standard remote authentication?

  • Avatar
    John G

    Nope, uses the email (or UPN) only for SAML assertion token. If you gave it meta data in the claims provider, it would just ignore it.

    PS - You can use Microsoft Forefront Identity Manager with a custom sync source (Zendesk) using their API. Sync is separate then SAML authentication (Same for Office 365 and Google Apps).

    PSS - Zendesk pease fix WIA and support SAML outside of fixed IP addresses.

  • Avatar
    Morten Primdahl

    Wilson/John - you can set certain user attributes on the user during the SAML auth procedure: https://gist.github.com/d72dc6837d9f6eb5d4aa

    John, we'll have to get back to you on the WIA. Also, could you create a ticket on the IP/URL issue, I'm not sure I follow entirely.

    Thanks.

  • Avatar
    Wilson Carey

    Anyone having trouble with SAML logout with ADFS? We're using the following URL for logout:

    https://<our\_domain>/adfs/ls/?wa=wsignout1.0

    The logout appears to be successful, but an error is displayed in the browser and the following is returned in the Windows event logs:

    Encountered error during federation passive sign-out.

    Additional Data

    Exception details:

    Microsoft.IdentityServer.Web.RequestFailedException: MSIS7055: Not all SAML session participants logged out properly. It is recommended to close your browser.

    at Microsoft.IdentityServer.Web.FederationPassiveAuthentication.BuildSamlLogoutResponse(HttpSamlMessage samlMessage)

    at Microsoft.IdentityServer.Web.FederationPassiveAuthentication.SingleLogout(Uri returnUrl, Boolean wsFedInitiated)

     

    Microsoft's documentation offers little assistance with this. I do not have anything defined for the SAML logout end point on the relying trust. Is this my problem? Thanks.

  • Avatar
    Sam Finding

    Two questions:-

    1)What happens to the existing users in Zendesk?

    2)Will users be able to use their original Zendesk password as well as the one from AD?

  • Avatar
    Jbarnett

    I agree 100% with John G. Why don't you allow SAML auth to a specific URL? We have both our company and customers accessing Zendesk and need our clients to use the traditional form based authentication and all of our company to login via SSO. This is 2012 and tons of people work from their home offices that have dynamic IP's. This is critical and needs to be fixed. We can't use SAML for this one reason alone.

  • Avatar
    Craig Morton

    Am I correct in saying that the two URLs are company.zendesk.com/home and company.zendesk.com/access/normal

  • Avatar
    Craig Morton

    I believe that the real requirement to run a mixed enterprise and customer helpdesk is to be able to choose the default authentication mechanism for the straight URL. Maybe this can already be done?

    Use Case 1: I would like the standard URL company.zendesk.com (support.company.com) to provide u/p, google, twitter etc whilst agents/corporate users use a /access/saml login.

    Use Case 2: Other helpdesks that are enterprise focussed might want the straight URL to redirect to their saml provider (most often internal LAN), but have a mechanism "/access/normal" for corporate users at home.

    We might be able to get the Use Case 1 result by using the optional "IP ranges" filter above, set to something stupid like loopback, and direct the internal agents to use a SAML auth to a specific URL as requested above? The technical requirement is to send a 'relay state' to the SAML server to tie back to a zendesk session.

  • Avatar
    Craig Morton

    I've just thought of another limited solution until Zendesk recognise Use Case 1 as becoming more common.

    The hub and spoke model of Enterprise helpdesk solves use Case 1 with ticket sharing. Put customers on the spoke and SSO customers on another spoke. Messes up your branded knowledge base function

    Also - note - the help text on "IP Ranges" Requests from these IP ranges will always be routed via remote authentication. Requests from IP addresses outside these ranges will be routed to the normal login form." The /access/saml redirect fails unless you know the IP exit point on your network for all SSO users - not good for big organisations

    So I think the two new functions/fixes required (as reflected in most contributors comments) are:

    1. Default authentication method for straight URL - SSO yes/no

    2. company.zendesk.com/access/saml - always redirects

  • Avatar
    Armen Martirosyan

    I do want to echo the same from our side as well, we need to have SAML SSO for internal, and use company.zendesk.com for external customers, and using a IP range does not work, since we have agents work from home.

     

    So one more vote to get this "fixed" for the future.

  • Avatar
    Craig Morton

    |

    We want to grow the tenancy in our customer by allowing agents to become established in the branded spoke (light or full). More revenue for zendesk, and lower support costs for us by using service advocates in the branded spoke.

    I really like the move to separate out the user and agent audience - looking forward to it reaching it's logical conclusion

    Modifying / Improving on my earlier posts above and unlikey to be trivial :)

    * I foresee two separate branded URLs for users and agents - allow a second CNAME and SSL

    * The authentication method choice should be tied to URLs to allow various access and business use case.

    |

  • Avatar
  • Avatar
    Veeru As

    Hi there,

     

    Am trying Zendesk since past couple of weeks. I need to know one thing. If

    I have enabled SSO login using SAML type, to what extent does zendesk

    stores the information about the user who logs in using SSO.

    Also what all information does Zendesk requires for authentication using

    SSO?

  • Avatar
    Ben Rohrs

    @Veeru, Zendesk stores the username once they've authenticated via SSO, but does not store any passwords since it only needs an assertion from the SAML service

    This article should define what information is required by Zendesk to setup SSO. If you need more information, please contact us at support@zendesk.com and we'll help you troubleshoot.

  • Avatar
    Luke Jaeger

    We have the Starter version of ZenDesk and I'm considering implementing OneLogin to provide SSO between our AD domain, Google Apps, and ZenDesk. According to your rep Avi W., only the more expensive ZenDesk plans support SAML but we could still use OneLogin for SSO. So there's a way to do SSO without SAML? How does that work? Apparently there's a lot I don't understand about SSO.

  • Avatar
    Jennifer Rowe

    Hi Luke,

    It looks like your question was answered in a ticket. I'm putting some of the info here in case other users need it.

    While we do have SSO options for all plans (for example, Microsoft AD), SAML is limited to our Plus and Enterprise plans. You could take a look at our OneLogin integration as an alternative. If you have any other questions, let us know.

    Thanks for your post.

  • Avatar
    Jeff Bautista

    Is it possible to test SSO in a non-production environment before pushing it live?

  • Avatar
    Ben Rohrs

    @Jeff, you can test in a sandbox

  • Avatar
    Jeff Bautista

    @Ben Thank you!

  • Avatar
    Max VanDuyne

    I have a question in regards to SSO and remote ticket creation. If we are using the API to create tickets, what do we enter in for the userId if we are using Single Sign-On?

  • Avatar
    Ben Rohrs

    @Paul, there are a variety of mechanisms you can use when authenticating via the API. We recently rolled out support for OAuth, or you can authenticate via a token. Check out Channels > API in the admin menu of your account for more info. If you have questions about setting this up, create a ticket and we can help.

Please sign in to leave a comment.