Zendesk supports enterprise single sign-on access to Zendesk accounts via Secure Assertion Markup Language (SAML) andJSON Web Token (JWT). With SSO, users can sign in once using their company sign-in form to gain access to multiple systems and service providers, including Zendesk products.
As a Zendesk admin, your role consists of enabling the SSO options. This article describes how to enable multiple SAML single sign-on configurations that can be used to authenticate team members (admins and agents, including light agents and contributors), end users, or both.
This article contains the following topics:
- How SAML SSO for Zendesk works
- Requirements for enabling SAML SSO
- Enabling SAML SSO
- Assigning SAML SSO to users
- Managing users in Zendesk after enabling SAML SSO
- Switching authentication methods
The IT team in a company is usually responsible for setting up and managing the company's SAML authentication system. Their role is to implement SSO for Zendesk on the system. Refer the team to the following topic in this article:
Related articles:
How SAML SSO for Zendesk works
SAML for Zendesk works the way SAML does with all other service providers. A common use case is a company where all user authentication is managed by a corporate authentication system such as Active Directory or LDAP (generically referred to as anidentity providerorIdP). Zendesk establishes a trust relationship with the identity provider and allows it to authenticate and sign in users to Zendesk accounts.
A common use case is a user who signs in to their corporate system at the beginning of the work day. Once signed in, they have access to other corporate applications and services (such as email or Zendesk Support) without having to sign in separately to those services.
If a user attempts to sign in directly to a Zendesk account, they are redirected to your SAML server or service for authentication. Once authenticated, the user is redirected back to your Zendesk account and automatically signed in.
Another supported workflow is giving users access to Zendesk after they sign in to your company's website. When a user signs in to the website using their website credentials, 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 account, which grants a session to the user.
Requirements for enabling SAML SSO
Meet with the team in your company responsible for the SAML authentication system (usually the IT team) to make sure your company meets the following requirements:
The company has a SAML server with provisioned users or connected to an identity repository such as Microsoft Active Directory or LDAP. Options include using an in-house SAML server such as OpenAM, or a SAML service such as Okta, OneLogin, or PingIdentity.
If using an Active Directory Federation Services (ADFS) server, forms-based authentication must be enabled. Zendesk does not support Windows Integrated Authentication (WIA). For more information, seeSetting up single sign-on using Active Directory with ADFS and SAML.
- Zendesk-bound traffic is over HTTPS, not HTTP.
- The remote login URL for your SAML server (sometimes called SAML Single Sign-on URL)
- (Optional) The remote logout URL where Zendesk can redirect users after they sign out of Zendesk
- (Optional) A list of IP ranges to redirect users to the appropriate sign-in option. Users making requests from the specified IP ranges are routed to the remote SAML authentication sign-in form. Users making requests from IP addresses outside the ranges are routed to the normal Zendesk sign-in form. If you don't specify a range, all users are redirected to the remote authentication sign-in form.
- The SHA2 fingerprint of the SAML certificate from your SAML server. X.509 certificates are supported and should be in PEM or DER format, but you'll still need to provide a SHA2 fingerprint for the X.509 certificate. There is no upper limit on the size of the SHA fingerprint.
The IT team may require additional information from Zendesk to configure the SAML implementation. Refer them to theTechnical implementation worksheetin this article.
After you've confirmed that you meet the requirements and have all of the necessary information, you're ready toenable SAML SSO.
Enabling SAML SSO
Admins can enable SAML single sign-on only for end users, only for team members (including light agents and contributors), or for both groups. You can create multiple SAML SSO configurations. Before you start, obtain the required information from your company's IT team. SeeRequirements for enabling SAML SSO.
To enable SAML single sign-on in Zendesk
- InAdmin Center, click
Accountin the sidebar, then selectSecurity > Single sign-on. - ClickCreate SSO configurationthen selectSAML.
- Enter a uniqueConfiguration name.
- ForSAML SSO URL, enter the remote login URL for your SAML server.
- Enter the SHA-256Certificate fingerprint. This is required for us to communicate with your SAML server.
- (Optional) ForRemote logout URL, enter a logout URL where users should be redirected after they sign out of Zendesk.
- (Optional) ForIP ranges, enter a list of IP ranges if you want to redirect users to the appropriate sign-in option.
从speci用户发出请求fied IP ranges are routed to the remote SAML authentication sign-in form. Users making requests from IP addresses outside the ranges are routed to the normal Zendesk sign-in form. Don't specify a range if you want all users to be redirected to the remote authentication sign-in form.
- SelectShow button when users sign into add aContinue with SSObutton to the Zendesk sign-in page.
You can customize the button label by entering a value in theButton namefield. Custom button labels are useful if you add multiple SSO buttons to the sign-in page. SeeAdding "Continue with SSO" buttons to the Zendesk sign-in pagefor more information.
- ClickSave.
By default, enterprise SSO configurations are inactive. You mustassign the SSO configuration to usersto activate it.
Assigning SAML SSO to users
After creating your SAML SSO configuration, you must activate it by assigning it to end users, team members, or both.
To assign an SSO configuration to team members or end users
- Open the Security settings for team members or end users.
- InAdmin Center, clickAccountin the sidebar, then selectSecurity > Team member authentication.
- InAdmin Center, clickAccountin the sidebar, then selectSecurity > End user authentication.
- InAdmin Center, click
- If you're assigning an SSO configuration to team members, selectExternal authenticationto show the authentication options.
These options are already displayed for end users.
- Click theSingle sign-on (SSO)option in theExternal authenticationsection, then select the name(s) of the SSO configuration(s) you want to use.
Single sign-on might not cover all use cases, so Zendesk authentication remains active by default.
- Select how you'd like to allow users to sign in.
Let them chooseallows users to sign in using any active authentication method. SeeGiving users different ways to sign into Zendesk.
Redirect to SSOonly allows users to authenticate using the主要SSO反对figuration. Users don’t see additional sign-in options, even if those authentication options are active. When you selectRedirect to SSO,Primary SSOfield appears for you to select the primary SSO configuration.
- ClickSave.
Managing users in Zendesk after enabling SAML SSO
After enabling SAML single sign-on in Zendesk, changes made to users outside Zendesk sync to your Zendesk account. For example, if a user is added to your internal Active Directory or LDAP system, the user is automatically added to your Zendesk account. If a user is deleted in your internal system, the user will no longer be able to sign in to Zendesk. However, their account will still exist in Zendesk.
By default, the only user data stored in Zendesk when single sign-on is enabled is the user's given name, surname, and email address. Zendesk does not store passwords. As a result, you should disable any automated email notifications from Zendesk about passwords. SeeDisabling password notification emails from Zendesk.
To provide a better customer experience, you might want to store more than just the user's name and email address in Zendesk. SeeObtaining additional user data.
Disabling password notification emails from Zendesk
When a user is added to a Zendesk account, an automatic email notification may be sent to the user asking them to verify their email address and to create a username and password.
Ze亚博ndesk用户创建新用户who accesses your Zendesk account through SAML or JWT. 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, by default every new user gets an email notifying them to verify their email address and create a username and password.
- InAdmin Center, click
Peoplein the sidebar, then selectConfiguration > End users. - In theAccount emailssection, deselectAlso send a welcome e-mail when a new user is created by an agent or admin
- InAllow users to change their passwords, deselect this option.
Switching authentication methods
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.
Technical implementation worksheet
This section is for the team in the company responsible for the company's SAML authentication system. It provides details about the Zendesk SAML SSO implementation.
Topics covered:
Required user data to identify the user being authenticated
When you implement SAML SSO access to Zendesk accounts, you specify certain user data to identify the user being authenticated.
These topics describe the data you need to provide:
Specifying the user's email address in the SAML subject's NameID
Zendesk uses email addresses to uniquely identify users. You should specify the user's email address in the SAML subject's name ID.
For example:
stevejobs@yourdomain.com If the givenname and surname attributes aren't provided, Zendesk will use the username of the email address provided in the
If the email's username has a period character in it, then we will use it to parse out a first name and last name. If there is no period character, then the whole username becomes the name of the user in Zendesk. For example, if the email address
Specifying two required user attributes in the SAML assertion
If you specify thegivennameandsurnameattributes, you must use the full namespace rather than the friendly names. For example: where the friendly name might be 'surname', the actual value you need to specify for the attribute ishttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
| Concept | Attribute | Description | Example value |
|---|---|---|---|
| first name | givenname | The given name of this user. You must specify the full namespace for this attribute. | |
| last name | surname | The surname of this user. A user in Zendesk is created or updated in accordance with this user's given name and surname. See example below. You must specify the full namespace for this attribute. | |
Given name and surname example:
James Dietrich Zendesk supportsadditional user attributes. Talk to your Zendesk Support admin about their data requirements in Support.
Obtaining additional user data
The only user data required by Zendesk from your authentication system is the user's given name, surname, and email address. The given name and surname are the only attribute names you should use to capture information about a user's name. However, you can get more data by asking your IT team to add user attributes to the SAML assertions the identity provider sends to Zendesk when users sign in.
ASAML assertioncontains one or more statements about the user. 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.
| 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 asorg1,org2,org3 |
| organization_id | Example:134211213 |
| organization_ids | Comma separated values such as23423433, 234324324, 23432 |
| ou | Name of an organization unit. Specify it as anorganizationattribute. |
| 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 agents) locale_id (for end users) |
The locale in Zendesk, specified as a number. To get a list of valid numbers, seeLocalesin the API docs. |
| role | The user's role. Can be set toend-user,agent, oradmin. Default isend-user. |
| custom_role_id | Applicable only if the value of theroleattribute above isagent. You can get the ids of your custom roles with theCustom Roles API. |
| external_id | A user id from your system if your users are identified by something other than an email address or if their email addresses are subject to change. Specified as a string. |
| user_field_ |
A value for a custom user field in Zendesk Support. SeeAdding custom fields to users. The user_field_employee_numberwhereemployee_numberis the field key in Zendesk. Sending a null value or an empty string in the attribute value will remove any custom field value set in Zendesk Support. |
| 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 for Zendesk
| Attribute | Value |
|---|---|
| entityID | https://yoursubdomain.zendesk.com |
| AudienceRestriction | yoursubdomain.zendesk.com |
For both values, replaceyour_subdomainwith the Zendesk Support subdomain. If you're unsure of the subdomain, ask your Zendesk admin.
Zendesk enforces theAudienceRestrictionattribute.
Configuring the SAML server for Zendesk
Some SAML servers may require the following information when configuring an integration with Zendesk:
Access Consumer Service (ACS) URL: Specifyhttps://yoursubdomain.zendesk.com/access/saml(case sensitive), where 'accountname' with your Support subdomain
Redirects to SAML Single Sign-on URL: UseHTTP POST
Hashing algorithm (ADFS): Zendesk supports the SHA-2 algorithm when using Active Directory Federation Services (ADFS)
Parameters returned to your remote sign-in and sign-out URLs
When redirecting users to your authentication system, Zendesk appends the following parameters to the remote sign-in and remote sign-out URLs.
| Attribute | Description |
|---|---|
| brand_id | The brand of the Help Center the user was on when they attempted to sign in. For more information, seeCreating a Help Center for one of your brands. |
| Attribute | Description |
|---|---|
| Email of the user signing out. | |
| external_id | A unique identifier from your system stored in the Zendesk user profile. |
| brand_id | The brand of the Help Center the user was on when they signed out. For more information, seeCreating a Help Center for one of your brands. |
If you prefer not to receive email and external id information in the sign-out URL, ask your Zendesk admin to specify blank parameters in theRemote logout URLfield in the admin interface. SeeEnabling SAML SSO. For example:https://www.yourdomain.com/user/signout/?email=&external_id=.
Troubleshooting the SAML configuration for Zendesk
Here is Zendesk's SAML 2.0 metadata:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress Zendesk expects a SAML assertion that looks as follows:
myidp.entity.id Note: Replace 'accountname' in theDestinationattribute with your Zendesk subdomain.
Zendesk expects user attributes to be specified in an assertion's attribute statement (
< saml: AttributeStatement > < saml:属性名称=”或ganization"> Acme Rockets tag1 tag2 555-555-1234 agent 12345 For the names and descriptions of the user attributes supported by Zendesk, see the table inObtaining additional user dataabove. Note that the full namespace isn't supported for optional user attributes.
39 Comments
Great post & thank you for sharing, one of the good blogs to read about enabling SAML single sign on
Hi
I am setting up SAML SSO with Azure and when testing I am getting an error that identifier is wrong. I have configured according to guidelines (https://subdomain.zendesk.com) as indicated in table 6 of the page. Any ideas what might be wrong.
Thanks
Hello Aggelos!
I understand you've chatted with our colleague regarding this issue and was able to resolve it on your own. If you have any tips on what you did to resolve it, we'd love to know!
I had to remove the https part from the URL. Then a little hack to land in the correct page for sign in. In Azure use the target of the Sign In button as the sign on URL.
Thank you for this information!
Can we update the End users alias via the SSO JWT flow?
It allows for updating any custom field but since the Alias isn't custom it's almost the only thing the documentation is missing.
I have set up SAML SSO with my IdentityProvider4 and am able to sso in fine. Is there a way to use my system's GUID to identity a zendesk user, instead of email?
I see API PUT/POST calls to update/add User Identity type to email, twitter, etc., but nothing regarding a generic ID.
Possibly external_id, but how can I specify Zendesk to accept this?
Hi James,
Users in Zendesk are identified with email by default and email attribute is required when we talk about SSO authentication.
external_id will accept any values (numbers and characters) and you can pass this attribute in your SAML assertion payload (see above section of "Obtaining additional user data"), but it cannot be used as users primary identity.
Hello. We are using okta to sign-in into Zendesk. I also wanted to pass on 3 fields from okta profile onto Zendesk profile for users (manager, manager email, department) so i made 3 user fields with those names. When setting up in Okta admin, do i need to map manager to manager, or manager to user_field_manager (as per this passage :
user_field_employee_numberwhereemployee_numberis the field key in Zendesk. Sending a null value or an empty string in the attribute value will remove any custom field value set in Zendesk Support.Hey Victor! You'll want to map manager touser_field_managerassuming thatmanageris the key associated with the user field.
Hi SAbra, so we are doing provisioning from okta and we are running into a problem. Okta is trying to push Role , Custom Role and Ticket Restriction to Zendesk and its not passing on (we are getting error). Is there a way to turn this off (is is needed to edit the saml insertion for this)?
I wonder is it possible to arrange a video call with Zendesk and Okta support to help us figure this out?
I suggest that you capture aharfile with timestamp and initiate aconversationwith us so we can further check your SSO set up.
Hi, We need to update our SSO SAML config/Cert. Do you know if saving an update to the config will negatively impact anyone logged in currently?
For example would it kick agents out of the system and force them to re-authenticate?
Hi Andrew,
As documentedhere,浏览器使用cookie(文件包含用户数据) placed in your computer’s cache (temporary data storage space) to store website information on your computer, so web pages and components can load quickly. Zendesk uses this ability as well to deliver the best possible performance.
When you update your SSO SAML config/Cert, your cache and cookies can become outdated, which may cause issues and unwanted behavior when your browser tries to use older versions. To fix this, you just need toclear your cache and cookies.
Hi,
Does Zendesk support multiple sites from a Single Federation?
Thanks,
Stefan
Hi,
While setting up SAML SSO with Azure, I am getting the error that Identifier(Entity ID) in Azure doesn't match the Issuer attribute sent from the application(Zendesk).
Can you please confirm the Issuer attribute Zendesk is sending so I can match in Azure? The Issuer attribute doesn't appear in Zendesk console so I cannot find.
Thanks.
It seems that you have already contacted us through Messaging and the value has already been provided. Please check the ticket#10173395for more information.
We have SAML set up with Azure and are getting the error AADSTS650056 - we have the SAML configured as per this guide, but cannot use it to get authenticated?
Error AADSTS650056 is a Misconfigured application as per thisMicrosoft documentation. I would suggest that you follow the suggested solution from the said article
We have followed the guides to enable SSO into Zendesk from our application. We have an additional requirement to allow SSO from another application with a different user store to SSO into Zendesk. Is this currently possible ? We may also have a third. Wondering how we can support multiple SSO
It is advisable to use just one SSO for your Zendesk login. However, you can follow the workaround discussed inHow can I set up two Zendesk SSO integrations?to have a maximum of 2.
Hello,
1 - Does Zendesk support using the UPN instead of the email address as the unique identifier? Sometimes user's email address doesn't match their username (UPN), and can make SSO logins confusing for them. We're using Azure AD for SSO.
2- If it does not support UPN as the unique identifier, when configuring the App in Azure AD, the Name ID defaults to user.userprincipalname (UPN). Should this be changed on the Azure AD side to user.mail instead? Seems like this should default to user.mail in Azure AD if Zendesk is using email address as the unique Identifier.
I have the assertionhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/organization:"someCompany" in my SAML however users are not being added to the organization. What am I doing wrong?
Also, what does "Note that Zendesk only recognizes these additional user attributes if the attribute names outlined in the table below are used in the assertion's attribute statement; if you try to use the full namespace for these attributes, they'll be ignored." mean? What is a full namespace attribute versus user attribute?
I have found this statement to be incorrect under #3 of heading "Assigning SAML SSO to users"
Please confirm and update documentation.
"For end users, selecting the SSO option automatically deselects the Zendesk Authentication option if enabled."
This is incorrect - I have enabled SSO for end users in my Sandbox, and Zendesk Auth remains checked off (it does not auto disable). I have also confirmed I'm able to log into Zendesk as a regular end user with SSO (primary) and with Zendesk Auth by going to the backdoor URLhttps://domain.zendesk.com/access/normal.
SSO is the primary method, since when going to our Zendesk URL and clicking "Sign In" it auto redirects to SSO (we use Azure AD). So basically, the "Sign In" no longer provides a pop up for the user to log in whether it's a regular user or Agent. But, Zendesk auth is still enabled and can be logged into if the end user (or agent) knows the backdoor URL.
HiCarmelo LoPresti-
Thank you for reporting the issue with the documentation. Our team is investigating.
Are we able to delete a SSO configuration? I am not seeing that option. It's not assigned to any users making it inactive, but there is no option to delete.
Sam Larson
We currently don't allow Deletion of SSO configurations, we want to allow that in future combined with logs and restoration feature to deal with accidental deletes.
As others have already discovered and commented here, Zendesk's requirement that the identity provider use an email address to uniquely identify its users in the SAML subject's NameID element is problematic and a source of much frustration.
This requirement is bad practice because as an identityconsumer, it's not Zendesk's role to determine the type or format of the user identifier. This decision actually belongs to the identity provider and Zendesk should be flexible enough to accept/use whatever type of unique identifier the IdP chooses to use. (For example, they may prefer to use some other type of unique identifier such as a GUID so that a user's account can persist if they ever change email addresses. Under your requirements a user must unnecessarily create a new account if they change email addresses.)
I better approach would be if Zendesk requires that an email address be provided as one of the user properities, but it shouldn't expect that the email address will be used as the IdP's unique identifier.
Has anybody managed to get this setup using Azure AD to create agents with a custom role?
We have added mappings for role (set to 'agent') and custom_role_id (set to the id of the custom role to assign) but users are always created as end-user rather than as agent.
Any ideas?
Thanks
Pleasesign into leave a comment.