Zendesk Support supports Secure Assertion Markup Language (SAML), which allows you to provide single sign-on (SSO) for your Zendesk Support account using enterprise identity providers such as Active Directory and LDAP. If you use SAML, a user is automatically verified with the identity provider when they sign in. The user is then allowed to access Zendesk Support without being prompted to enter separate login credentials.
Single sign-on using SAML is available on Professional and Enterprise.
Implementing single sign-on via SAML means that the sign in process and user authentication are handled entirely outside of Zendesk Support. 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 Support. What you enable in Zendesk is the option to use SAML for single sign-on (see Enabling SAML single sign-on in Zendesk Support 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 Support account. However, changes made outside of Zendesk are immediately synced back to your Zendesk Support account. 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 Support account. 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 Support).
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 Support works
SAML for Zendesk Support 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 Zendesk, establishes a trust relationship with IdP and allows that external IdP to authenticate users and then seamlessly sign them in to Zendesk Support. 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 Zendesk, users who visit your Zendesk Support account 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 account 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.
Configuring Zendesk Support for new users
A Zendesk user profile is created for any new user who accesses your Zendesk Support account through SAML. Because they're authenticated with a non-Zendesk password, the profile is created without a password because they don't need to sign in to Zendesk. However, if you forget to make certain changes in Zendesk Support, every new user will get an email notifying them to verify their email address and create a username and password.
- "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 can use the remote login URL and the SHA fingerprint to configure SAML in Zendesk Support. See Enabling SAML single sign-on in Zendesk Support.
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 support Forms Based Authentication for ADFS. Integrated Windows Authentication is not supported. For information, see Setting up single sign-on using Active Directory with ADFS and SAML.
Supported user attributes in the SAML assertion
If the user successfully signs in, the identity provider sends an assertion to Zendesk. An assertion is a package of information that supplies one or more statements made by a SAML authority. One statement is the authorization decision itself – whether or not the user was granted access. Another statement can consist of attributes describing the signed-in user.
Zendesk supports the following user attributes for users signing in through SAML:
|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
|organization_ids||Comma separated values such as
|ou||Name of an organization unit. Specify it as an
|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.|
|user_field_<key>||A value for a custom user field in Zendesk Support. See Adding custom fields to users. The <key> is the field key asssigned to the custom user field in Zendesk Support. Example:
The attributes are specified in an attribute statement in the 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 also supports a series of InCommon Federation Attributes to set user attributes as part of the sign in. Examples:
|Friendly name||SAML2 formal name (attribute to use)|
|ou (organization unit)||urn:oid:126.96.36.199|
Configuring the identity provider
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 Zendesk Support
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 Zendesk Support
- Click the Admin icon () in the sidebar, then select Security from the Settings category.
- 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.
- Select the SAML option.
- In the SAML SSO URL text box, enter the SAML login URL of your SAML server. Zendesk automatically adds a
brand_idparameter to the URL. This is the Zendesk brand the user was on when they attempted to sign in.
- (Optional) Enter a logout URL where Zendesk can redirect users after they sign out of Zendesk.
Zendesk automatically adds
brand_idparameters to the URL. If you prefer not having email and external id information in the URL, specify blank parameters in the logout URL. Example:
- You can optionally restrict access to users within a range of IP addresses.
- Enter the Certificate Fingerprint. This is required for us to communicate with your SAML server.
- Click Save.
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:Status> </samlp:Response>