Setting up single sign-on using Active Directory with JWT

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" target="_blank" rel="noopener noreferrer">What's my plan?</a></div>
<div class="article-banner" id="suite_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>All Suites</strong></td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr></tbody></table></figure></div>
<div class="article-banner" id="support_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>Support</strong></td>
<td>Team, Professional, or Enterprise</td>
</tr></tbody></table></figure></div>
</div><div class="note">
<span class="notetitle"><strong>Disclaimer</strong>:</span> This article is provided for instructional purposes only. Zendesk does not support or guarantee the code. Post any issues you have in the comments section or try searching for a solution online.</div><p>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.</p><p>This article covers the following steps:  </p><ul>
<li data-list-item-id="e36e94aa701954319405218f1fb82100d"><a href="#h_01HMA5N4HJ2ZKFWC5FT716P2PG">Step 1. Configuring your Windows server</a></li>
<li data-list-item-id="e2fdc0e27ae4b6056fcb9b010a17f1792"><a href="#h_01HMA5N4HJW996W82WXKKYB8TN">Step 2. Configuring Zendesk</a></li>
<li data-list-item-id="e066da222830d5256305b70d9348b746c"><a href="#h_01HMA5N4HJC93HKDQ9JCA6BQDE">Step 3. Downloading and configuring the authentication script</a></li>
<li data-list-item-id="e80ad8a19ac053027f41caf0350db12ac"><a href="#h_01HMA5N4HJE5HQP4J23R2M81X7">Step 4. Troubleshooting</a></li>
</ul><h2 id="h_01HMA5N4HJ2ZKFWC5FT716P2PG">Step 1. Configuring your Windows server</h2><p>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:</p><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image01.jpg" alt="" width="600"></p><p>For the IIS Role Services, you need the following installed:</p><ul>
<li data-list-item-id="e46c75615e0563650fde6a5fd90f39ab4">Application Development</li>
<li data-list-item-id="e853101f730c185759f63b803a7632ff9">ASP.NET</li>
<li data-list-item-id="e12303fbebf9f79e6f41f7bc63db6d4fd">ASP</li>
<li data-list-item-id="eb14c477ada970d40c15d381826ff2dce">Server Side Includes</li>
</ul><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image03.jpg" alt="" width="600"></p><p>And under Security</p><ul><li data-list-item-id="e12ee475f3082b7facd12b90ce7cc093b">Basic Authentication</li></ul><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image08.jpg" alt="" width="600"></p><p>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.</p><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image06.jpg" alt="" width="600"></p><p><a name="configzendesk"></a></p><h2 id="h_01HMA5N4HJW996W82WXKKYB8TN">Step 2. Configuring Zendesk</h2><p>For instructions, see <a href="https://support.zendesk.com/hc/en-us/articles/4408845838874">Enabling JWT single sign-on in your Zendesk </a>in the article, <a href="https://support.zendesk.com/hc/en-us/articles/4408845838874">Setting up single sign-on with JWT (JSON Web Token).</a> For the <strong>Remote Login URL </strong>value, specify the location where you'll place the ASP authentication script described in the next section.</p><p><a name="configscript"></a></p><h2 id="h_01HMA5N4HJC93HKDQ9JCA6BQDE">Step 3. Downloading and configuring the authentication script</h2><p>Download the ASP authentication script from this page on Github:</p><p><a href="https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bundles">https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bun...</a></p><p>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:</p><p>c:\inetpub\wwwroot\</p><p>For your web browser, files in that folder will appear in this URL:</p><p>http://serveraddress/classic_asp_jwt_with_ad.asp</p><p>Open the script in Notepad or any other text editor. The first part of the script that you need to configure is the following:</p><pre class="wysiwyg-code-block"><code class="language-auto"> ' Credentials for a domain user for LDAP access
sLdapReaderUsername = "domain\username"
sLdapReaderPassword = "password"
</code></pre><p>Enter your username and password of a user that has access to LDAP.</p><p>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:</p><pre class="wysiwyg-code-block"><code class="language-auto">' Set your shared secret and Zendesk subdomain
sKey = ""
sSubdomain = ""</code></pre><p><span style="font-size: 1em; line-height: 1.45em;">Here's the part of the script that does the LDAP lookup of your user account:</span></p><pre class="wysiwyg-code-block"><code class="language-auto">sQuery = "&lt;LDAP://" &amp; sDomainContainer &amp; "&gt;;(sAMAccountName=" &amp; sUsername &amp; "); adspath," &amp; sFields &amp; ";subtree"
Set userRS = oConn.Execute(sQuery)</code></pre><p>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:</p><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image04.jpg" alt=""></p><p>I would update the code with the attribute “info” to look as follows:</p><pre class="wysiwyg-code-block"><code class="language-auto"> sQuery = ";(sAMAccountName=" &amp; strUsername &amp; ");adspath,mail,displayName,sAMAccountName,info;subtree"
Set userRS = oConn.Execute(sQuery)
</code></pre><p>Once we have the attributes being looked up, we can use them. The code below performs the actual translation of the attributes:</p><pre class="wysiwyg-code-block"><code class="language-auto"> 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 = ""
</code></pre><p>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:</p><pre class="wysiwyg-code-block"><code class="language-auto"> 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 = ""
</code></pre><p>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 &gt; Advanced Features:</p><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image00.jpg" alt="" width="600"></p><p>Once that is enabled, if you go to the properties of the user, you will see an “Attribute Editor”:</p><p><img class="img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ad_image05.jpg" alt=""></p><p><strong>Note about passing through organization and tags</strong></p><p>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.</p><p>To successfully pass through tags, the attribute must have them listed as such:</p><p>“tag1, tag2, tag3”</p><p>If you do not include the “,” between the tags, it will fail.</p><p>For more information on the different fields we accept, take a look at this <a href="https://support.zendesk.com/hc/en-us/articles/4408845838874#topic_otw_jfh_3fb" target="_blank" rel="noopener noreferrer">post.</a></p><p>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!</p><p><a name="troublehooting"></a></p><h2 id="h_01HMA5N4HJE5HQP4J23R2M81X7">Step 4. Troubleshooting</h2><p>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:</p><pre class="wysiwyg-code-block"><code class="language-auto">[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</code></pre><p>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.</p><p>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.</p><p>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.</p><p>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.</p><script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408832064922",
"url": "https://support.zendesk.com/hc/en-us/articles/4408832064922-Setting-up-single-sign-on-using-Active-Directory-with-JWT",
"headline": "Setting up single sign-on using Active Directory with JWT",
"description": "You can configure JWT single sign-on authentication for Microsoft Active Directory users by setting up your Windows server, adjusting the authentication script, and troubleshooting connection and permission issues.",
"articleSection": "User sign-in",
"datePublished": "2021-10-16T03:46:16+00:00",
"dateModified": "2025-09-05T23:26:19+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408832064922"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}</script>