You can authenticate users using JWT (JSON web token) single sign-on. This article describes how to configure JWT SSO authentication for Microsoft Active Directory users, and covers the following steps:
1. Configuring your Windows server
3. Downloading and configuring the authentication script
1. Configuring your Windows server
You need IIS and ASP installed on your Windows server. Your IIS server has to be part of your domain and have direct access to your domain controller. The IIS server can be on the domain controller, but that is not required. If using Windows Server 2008, here is what role should be installed:
For the IIS Role Services, you need the following installed:
- Application Development
- ASP.NET
- ASP
- Server Side Includes
And under Security
- Basic Authentication
Once your roles and services are installed properly, you have to configure the authentication of your IIS server. Zendesk works well with Basic Authentication so I usually make that my default. Make sure you disable Anonymous Authentication or else users will not get prompted for their Windows username and password and thus fail to login.
2. Configuring Zendesk
For instructions, see Enabling JWT single sign-on in your Zendesk in the article, Setting up single sign-on with JWT (JSON Web Token). For the Remote Login URL value, specify the location where you'll place the ASP authentication script described in the next section.
3. Downloading and configuring the authentication script
Download the ASP authentication script from this page on Github:
https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bun...
Place the script (and its dependencies which are included in the above bundle) into your wwwroot directory. You can create a subdirectory, but remember that that will just extend the URL for the script. During a new install, IIS will create this directory in:
c:\inetpub\wwwroot\
For your web browser, files in that folder will appear in this URL:
http://serveraddress/classic_asp_jwt_with_ad.asp
Open the script in Notepad or any other text editor. The first part of the script that you need to configure is the following:
' Credentials for a domain user for LDAP access sLdapReaderUsername = "domain\username" sLdapReaderPassword = "password"
Enter your username and password of a user that has access to LDAP.
Next, you need to enter the Shared Secret Token that you got during the JWT Zendesk configuration (labeled sKey in the script) as well as enter your Zendesk subdomain:
' Set your shared secret and Zendesk subdomain
sKey = ""
sSubdomain = ""
Here's the part of the script that does the LDAP lookup of your user account:
sQuery = "<LDAP://" & sDomainContainer & ">;(sAMAccountName=" & sUsername & "); adspath," & sFields & ";subtree"
Set userRS = oConn.Execute(sQuery)
If you look at the code, we are getting the adspath, mail, displayName, and sAMAccountName of the user. If you want to pull more data to be used in your call, include it in that part of the code. For example if I want to include the Notes block below:
I would update the code with the attribute “info” to look as follows:
sQuery = ";(sAMAccountName=" & strUsername & ");adspath,mail,displayName,sAMAccountName,info;subtree" Set userRS = oConn.Execute(sQuery)
Once we have the attributes being looked up, we can use them. The code below performs the actual translation of the attributes:
If Not userRS.EOF and not err then sFullName = userRS("displayName") sEmail = userRS("mail") sExternalID = userRS("sAMAccountName") if sOrg then sOrganization = "" end if sTags = "" sPhotoUrl = ""
You will see that we have already placed in the displayName, mail, and sAMAccountName. If you'd like to call the individual attributes of your user, you would use the “userRS(“nameofattribute”)” object. So for example, if you included the “info” lookup, and I want to use the Notes block for tags, I would update the code to read as follows:
If Not userRS.EOF and not err then sFullName = userRS("displayName") sEmail = userRS("mail") sExternalID = userRS("sAMAccountName") if sOrg then sOrganization = "" end if sTags = userRS("info") sPhotoUrl = ""
So what individual attributes are available? You can see what options you have for attributes here:
http://www.kouti.com/tables/userattributes.htm
Also, if you enable “Advanced Features” in your Active Directory Users and Computers, you can change the individual attributes directly. To enable Advanced Features, go to View > Advanced Features:
Once that is enabled, if you go to the properties of the user, you will see an “Attribute Editor”:
Note about passing through organization and tags
To successfully pass through an organization for a user, an organization already must exist in Zendesk. If an organization does not exist in Zendesk (or the names are not an exact match), Zendesk will not create the organization on the fly like it does the user. You first must create the organizations involved.
To successfully pass through tags, the attribute must have them listed as such:
“tag1, tag2, tag3”
If you do not include the “,” between the tags, it will fail.
For more information on the different fields we accept, take a look at this post.
After you have made your changes in the script, save it. Go to your Zendesk site and click Login. This should redirect you to the script where you will put in your Windows credentials and be sent back to Zendesk logged in!
4. Troubleshooting
So you clicked login and it failed? As part of the script we have included a debugging option. If you turn the Debug flag to 'True' in the script, Debug information will be printed when accessing your script. It will look something like:
[DEBUG] ZENDESK\test - should be of the form DOMAIN\username - if blank, your IIS probably allows anonymous access to this file.
[DEBUG] DomainContainer: DC=zendesk,DC=internal
[DEBUG] Attribute name: Test User
[DEBUG] Attribute email: test@zendesk.com
[DEBUG] Attribute jti: 2968942290171.981
[DEBUG] Attribute iat: 1380123848
[DEBUG] Redirecting to https://subdomain.zendesk.com/access/jwt?jwt=eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpYXQiOjEzODAxMjM4NDgsImp0aSI6Mjk2ODk0MjI5MDE3MS45ODEsIm5hbWUiOiJUZXN0IFVzZXIiLCJlbWFpbCI6InRlc3RAemVuZGVzay5jb20ifQ.QuRC6Ig7x_nK86Wc38u2viIVjshtTDohcgXTYpmU6VY
Here you should get all of your information properly listed. If you configured an Organization, tags, or the PhotoURL, you should see this data. If you are seeing some of the data, but not all of the data, verify the attribute data of the user, along with making sure the code references the proper attribute.
If you are getting to the page but are not getting any data this means that the script is failing to connect to your domain controller or has no permission. Verify on the server that you can access the domain controller by going to the server’s share (\\dcservername\ in the run prompt). Next verify that the user name and password that you placed in the code is correct. Also, if you have anonymous access enabled, you may get a blank page as it never asked for authentication. Ensure that anonymous access is turned off.
If you are unable to get to the page and your browser throws an error, the problem lies within IIS. Confirm that you have installed the needed roles/services on your server and that they are running. If you are still having issues, you may have to consult an IIS Administrator as errors of this kind are outside the scope of this guide.
If you do experience an error, please let us know what your resolution was. I would be happy to update this post with additional tips to problems that people are having and how to resolve them.
13 Comments
I'm curious if this script could be used with the mobile SDK as well I managed to use this to get the web portal JWT auth working but am hitting a brick wall getting it to return the proper stuff for the mobile
Hi Stephen,
The SDK Authentication is completely separate from the SSO configuration in your Zendesk account. As long as the JWT requests are formatted properly, you should be able to authenticate. I see you have a ticket open with us already, but I wanted to be sure to share our documentation for anyone who finds this post in the future:
Hope this helps!
Is it possible to delay the redirection to AD sign-on? Say we wanted to allow non-AD users to be able to access our help page and submit tickets using the form, would that be possible using this?
Also, what might it take to allow both domain\username and name@email.com sign in?
Hey Reese!
I'd like to get more context around what you're trying to achieve. Let me loop you in to a new ticket so we can discuss this further. See you in the ticket!
what modifications to this code are made to pass "user_fields"? I have tries several modifications however I have not been able to correctly pass this hash.
Matthew - check out this pull request here: https://github.com/zendesk/zendesk_jwt_sso_examples/pull/18
It is updated to support passing of all supported fields, including User Fields. Be sure to read the comments.
What are the optimal hardware recommendations?
Hi John,
For Zendesk in general? There are no hardware requirements or recomendations, except for Insights. As a rule - if your hardware can handle Chrome, Firefox or AD - it will handle Zendesk. Have a look at this article for some additional answers - https://support.zendesk.com/hc/en-us/articles/203661786-Zendesk-Support-system-requirements
Regards
For anyone having problems with this code and the server time being out, you will need to modify the utils.asp file to adjust for timezone difference. Zendesk servers are in UTC time, if your server isn't in UTC, then it will pass back the incorrect time and not authenticate with an error of "The supplied iat value is more than 3 minutes off, check your server clock."
To fix this find the following lines
And modify it to the following, making sure you adjust the X in DateAdd("h", X, dtmAdjusted), to how ever many hours you are in front of behind UTC time.
So an example for Sydney, Australia would be -18
I also had a small stumbling block when trying to login as an agent, with agents with multiple sign in options, Zendesk would have another fit. So test the login with an end-user instead.
Hello,
Is this configuration allows us to create and delete people as soon as their LDAP account si created or deleted ?
Thank you !
Hi Jean-Baptiste,
This configuration won't do this, although it might be possible to design custom scripts that would accomplish it alongside the JWT SSO.
Microsoft also does have an Azure integration that is closer to what you describe that you could check out as an alternative.
Hi Matt Sirianni
Is it possible to federate multiple active directory from different companies to one zendesk enterprise platform
Hey Daniel,
I'd recommend taking a look at the following articles:
Multibrand - Using multiple JWT Single Sign-on URL's (Enterprise
Setting up single sign-on using Active Directory with ADFS and SAML
I hope this points you in the right direction!
Please sign in to leave a comment.