Zendesk supports single sign-on (SSO) logins through SAML 2.0. A SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (ADFS) server. ADFS is a service provided by Microsoft as a standard role for Windows Server that provides a web login using existing Active Directory credentials.
Requirements
To use ADFS to log in to your Zendesk instance, you need the following components:
- An Active Directory instance where all users have an email address attribute.
- A Zendesk instance.
- A server running Microsoft Server 2012 or 2008. This guide uses screenshots from Server 2012R2, but similar steps should be possible on other versions.
- A SSL certificate to sign your ADFS login page and the fingerprint for that certificate.
- If you're using host mapping in your Zendesk instance, an installed certificate for hosted SSL.
After you meet these basic requirements, you need to install ADFS on your server. Configuring and installing ADFS is beyond the scope of this guide, but is detailed in a Microsoft KB article.
When you have a fully installed ADFS installation, note down the value for the 'SAML 2.0/W-Federation' URL in the ADFS Endpoints section. If you chose the defaults for the installation, this will be '/adfs/ls/'.
Step 1 - Adding a Relying Party Trust
At this point you should be ready to set up the ADFS connection with your Zendesk account. The connection between ADFS and Zendesk is defined using a Relying Party Trust (RPT).
Select the Relying Party Trusts folder from AD FS Management, and add a new Standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.
- In the Select Data Source screen, select the last option, Enter Data About the Party Manually.
- On the next screen, enter a Display name that you'll recognize in the future, and any notes you want to make.
- On the next screen, select the ADFS FS profile radio button.
- On the next screen, leave the certificate settings at their defaults.
- On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be https://subdomain.zendesk.com/access/saml, replacing subdomain with your Zendesk subdomain. Note that there's no trailing slash at the end of the URL.
- On the next screen, add a Relying party trust identifier of subdomain.zendesk.com, replacing subdomain with your Zendesk subdomain.
Note: If you enter subdomain.zendesk.com, and receive a request failure error, you may need to enter your subdomain as https://subdomain.zendesk.com.
- On the next screen, you may configure multi-factor authentication but this is beyond the scope of this guide.
- On the next screen, select the Permit all users to access this relying party radio button.
- On the next two screens, the wizard will display an overview of your settings. On the final screen use the Close button to exit and open the Claim Rules editor.
Step 2 - Creating claim rules
Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default the claim rule editor opens once you created the trust. If you want to map additional values beyond authentication, refer to our documentation.
- To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.
- On the next screen, using Active Directory as your attribute store, do the following:
1. From the LDAP Attribute column, select E-Mail Addresses.
2. From the Outgoing Claim Type, select E-Mail Address.
- Click on OK to save the new rule.
- Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.
- On the next screen:
1. Select E-mail Address as the Incoming Claim Type.
2. For Outgoing Claim Type, select Name ID.
3. For Outgoing Name ID Format, select Email.
Leave the rule to the default of Pass through all claim values.
- Finally, click OK to create the claim rule, and then OK again to finish creating rules.
Step 3 - Adjusting the trust settings
You still need to adjust a few settings on your relying party trust. To access these settings, select Properties from the Actions sidebar while you have the RPT selected.
- In the Advanced tab, make sure SHA-256 is specified as the secure hash algorithm.
- In the Endpoints tab, click on add SAML to add a new endpoint.
- For the Endpoint type, select SAML Logout.
- For the Binding, choose POST.
- For the Trusted URL, create a URL using:
1. The web address of your ADFS server
2. The ADFS SAML endpoint you noted earlier
3. The string '?wa=wsignout1.0'
The URL should look something like this: https://sso.yourdomain.tld/adfs/ls/?wa=wsignout1.0.
- Confirm you changes by clicking OK on the endpoint and the RPT properties. You should now have a working RPT for Zendesk.
Note: Your instance of ADFS may have security settings in place that require all Federation Services Properties to be filled out and published in the metadata. Check with your team to see if this applies in your instance. If it is, be sure to check the Publish organization information in federation metadata box.
Step 4 - Configuring Zendesk
After setting up ADFS, you need to configure your Zendesk account to authenticate using SAML. Follow the steps in Enabling SAML single sign-on. You'll use your full ADFS server URL with the SAML endpoint as the SSO URL, and the login endpoint you created as the logout URL. The fingerprint will be the fingerprint of the token signing certificate installed in your ADFS instance.
You can get the fingerprint by running the following PowerShell command on the system with the installed certificate:
C:\> Get-AdfsCertificate -Thumbprint
Look for the SHA256 thumbprint of the Token-Signing type certificate.
After you're done, the Security > Single sign-on page in the Zendesk Admin Center should look like this:
You should now have a working ADFS SSO implementation for Zendesk.
Switching authentication methods
Important: If you use a third-party SSO method to create and authenticate users in Zendesk, then switch to Zendesk authentication, these users will not have a password available for login. To gain access, ask these users to reset their passwords from the Zendesk sign in page.
38 Comments
What if you need to do this setup for multiple organizations? Is there a better way to do this? From these instructions, it looks like you can only have 1 organization configured through ADFS?? Thoughts?
Hi Chris,
There is a separate document on how to set up custom mappings between LDAP attributes and Zendesk using ADFS - https://support.zendesk.com/hc/en-us/articles/203663896-Mapping-attributes-from-Active-Directory-with-ADFS-and-SAML-Professional-and-Enterprise-. That document covers connecting both a static text field and a group membership.
Hi Ben,
With the new changes in SAML SSO requirements (https://support.zendesk.com/hc/en-us/articles/219615248), how do we implement this on ADFS end?
Thanks.
Hi Welly,
If you followed this article, chances are this is already configured correctly. For those that need to change it, I have found that going to the Endpoints tab of the Relying Party Trust settings window is where you would find any incorrect URLs that might be causing the wrong audience to be set. I will create a ticket for you so we can check your specific subdomain to see if you are already sending in the proper audience.
We have ADFS up, and working for Zendesk. Is it possible to use this to sync users one time. We wanted to pre-load our users before we went active with Zendesk.
I didnt want to have to setup JTW SSO to do this, since we already have ADFS setup and working.
I tried to search for a document regarding this, but I could not locate one.
Hi Traci,
Both SAML (ADFS) and JWT will only sync users on an individual basis when a user logs in. If you want to preload your users, I would suggest either using our Bulk Import feature or our Users API endpoint.
Hi,
If I go the SAML (ADFS) route and do not submit the role as SAML attribute, will I be able to simply change the role of a user in ZenDesk user administration? We currently have ZenDesk auth, but plan to switch to ADFS. I wouldn't want to lock myself out (as default for SAML role seems to be End-user.
Hi Martin,
If you attempt to log in using SAML SSO as a user that already exists we will keep whatever role they currently have set if you do not pass in a role attribute. If it is a new user being created and you don't send a role attribute, we will default to end-user.
Hi, thanks for your answer. I have been in contact with support for another issue and would also like to add here as a suggestion that it would be great to have a possibility to add mappings from the AD to custom person fields in ZenDesk.
I currently want to add the department and the job title of our end users, as this is handy when supporting our users. We do not want to have that many organisations in ZenDesk to map all the departments, and we use the tags field to assign values manually (so they would be overwritten on ADFS sync on login), so no way to add the job title.
Hi there, I've followed the instructions provided to configured Zendesk SSO with my client's ADFS servers, but the issue that we're running into, is that users once they've entered their login details, are being then forwarded directly to the Sign Out page.
Hi, that happened to me if the AD user had no email attribute (and no mailbox accordingly). Reason being that our admin users have no mail account.
Might be that one can use the UPN instead (which should always be given).
Hi,
I'm adding the https:///adfs/ls/?wa=wsignout1.0 URL as my logout URL. But its not log me out from the ADFS session. do you have any idea on this?
Hi Mohammad!
The logout URL should be set using the same subdomain and domain names which are configured for the SSO login address - i.e. https://sso.domain.tld/adfs/ls/?wa=wsignout1.0 . I hope this helps!
On the step to define the "Relying party trust identifier" the article states "On the next screen, add a Relying party trust identifier of subdomain.zendesk.com, replacing subdomain with your Zendesk subdomain.".
This was not working for me and was generating the following error in my Event Logs for ADFS 2.0.
"A token request was received for a relying party identified by the key 'https://subdomain.zendesk.com', but the request could not be fulfilled because the key does not identify any known relying party trust.
Key: https://subdomain.zendesk.com
This request failed."
To resolve this I had to add https://subdomain.zendesk.com as a relying party trust identifier.
You might consider updating the article and screenshot to include this as well.
-David
Thanks for the heads-up on this, David! I'll let our docs team know right away.
I have done SAML integrations with ADFS before. My question would be more of the communications to the users and the timing of the cut-over. Is this immediate, or do we have time to set this up, test the integration, communicate out to the users, then cut-over?
Hi Jack,
The cut-over would be instant but there are a couple things you could do to test it. First, if you have an Enterprise account, you can set up and test SAML in a sandbox before putting it into production. You can also easily switch back and forth from SAML to whatever authentication you have currently set up should you want to test during a time when users are not heavily using the system or during planned downtime.
Thank you Nick.
Setting up a sandbox sounds ideal, however in following your instructions I do not see Sandbox under Manage. Does this mean that we do not have an enterprise account? Who can I talk to about setting up a limited enterprise account? What type of account do we have now?
Hey Jack -
It looks like you're on a Plus account, which is actually one of our Legacy plans. That is why you are not seeing the Sandbox option. I'm going to find out who your Account Exec is, or if your admin/owner knows, they can reach out directly to get an Enterprise setup going.
Hi there,
It looks like this was written for Windows Server 2012/R2/ADFS 2 as a lot of these screens appear to have changed in Server 2016/ADFS 3 - for example the first question I am asked when adding a relying party trust is whether or not it is Claims aware, however there's no mention of that in the documentation here. Equally I can't see anything like "Choose Profile" or any mention of setting up MFA.
Any chance of an updated version? Or at least a pointer as to whether I should be selecting Claims Aware or not?
Thanks,
Hi Paul -
In this case, you'd configure ADFS to be claims aware as non-claims aware application are for internal networks and intranets. This resource covers the basic setup requirements for integrating ADFS with Zendesk - typically profile and MFA would be ADFS specific configuration steps that are likely better covered in the ADFS documentation.
We do not have a more recent version of this article at this time for Windows Server 2016, but overall the configuration should still be the same apart from the user interface design.
We currently use OneLogin. If we switch over to ADFS (currently used for Office 365), do we lose Provisioning? Meaning with ADFS can we sync the user's other information like which groups they should belong to, office location, department, manager, etc?
Hi Justin,
ADFS supports the attributes mapping such as office location, department, manager, etc. You will need to configure the attributes mapping in the "Claim Rules" of your Zendesk "Relying Party Trusts" in your ADFS settings. This article provides information on how to configure the mapping: https://support.zendesk.com/hc/en-us/articles/203663896-Mapping-attributes-from-Active-Directory-with-ADFS-and-SAML-Plus-and-Enterprise-
The list of supported attributes is available in section "Table 1. Supported attributes" of this article: https://support.zendesk.com/hc/en-us/articles/203663676
Thank you Mathieu. I just thought of it - one thing OneLogin does too is the disabling of users through their provisioning API. How do we disable Zendesk users who are no longer active? Is there an adfs way to do this? Thanks!
Hi Justin,
No, SSO with SAML ADFS is only for user connections. If you want to suspend or delete a non-active users in Zendesk, you will need to use the Zendesk API. More information can be found here:
https://developer.zendesk.com/rest_api/docs/core/users#suspending-a-user
https://developer.zendesk.com/rest_api/docs/core/users#delete-user
Hi, I',m having The same Issue of Dorien “Pango” Takeshi, " I've followed the instructions provided to configured Zendesk SSO with my client's ADFS servers, but the issue that we're running into, is that users once they've entered their login details, are being then forwarded directly to the Sign Out page." the user that I'm testing has email in the field in the AD, but I don't know if there be a mistake in my settings that you already helped somenone before. My principal AD is windows 2008 r2 and I install a w2012 to create the adfs server. can be this the issue? after this I setup directly over w2008r2 enable the ADFS on the server but the same issue, I removed the log out link and I see a message " Authentication error SAML
Hi Alejandro!
Thanks for your comment and sorry you're having ADFS SSO troubles.
This would be best discussed in a ticket since troubleshooting your issue will require account sensitive information.
Please lookout for a ticket from me and I'll look forward to communicating with you from there!
Hello Ben, Good Information Thank you!
Do we require ADFS proxies or can I just deploy an ADFS internal server?
My client wants us to implement SSOgen SPGateway with Azure ADFS for EBS 12.2:
1. https://www.ssogen.com/
2. https://www.ssogen.com/oracle-ebs-sso-adfs/
Any recommendations please?
Hi Mike!
I've pinged Ben to see if he can hop in here to answer your question. :)
Hey Mike!
I talked to Ben, and he said that ADFS proxies and setup should not make a difference for setting up SAML SSO with Zendesk. As long as your users are able to access both the ADFS instance and the Zendesk webpage they should be able to successfully authenticate.
Hope that helps!
Please sign in to leave a comment.