Enabling JWT single sign-on

<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="body">
<div class="note fastpath">
<span class="fastpathtitle">Location: </span><span class="ph">Admin Center &gt; Account &gt; Security &gt; Single sign-on</span>
</div>
<p class="p">Single sign-on is a mechanism that allows you to authenticate users in your systems and subsequently tell Zendesk that the user has been authenticated. If you use single sign-on with JSON Web Token (JWT), a user is automatically verified with the identity provider when they sign in. The user is then allowed to access Zendesk without being prompted to enter separate sign-in credentials.</p>
<p class="p">As a Zendesk admin, your role consists of enabling the SSO options. This article describes how to enable multiple JWT single sign-on configurations that can be used to authenticate team members (admins and agents, including light agents and contributors), end users, or both.</p>
<p class="p">At the core of single sign-on is a security mechanism that allows Zendesk to trust the sign-in requests it gets from your systems. Zendesk only grants access to the users who have been authenticated by you. Zendesk SSO relies on JWT to secure the exchange of user authentication data.</p>
<div class="note important" id="topic-1__note_fk1_2rq_tyb">
<span class="importanttitle">Important:</span> When you use JWT- or SAML-based SSO, you are responsible for verifying your users' identities, including their email addresses. If you don't verify your users and their email addresses, your account is at risk of unauthorized access, and Zendesk cannot guarantee or warrant the security of your account.</div>
<div class="p">
<p>This article contains the following sections:</p>
<ul class="ul" id="topic-1__ul_n2q_zfd_fy">
<li class="li" data-list-item-id="e65bf7bb58c4b3c13b9f7bab819d19ca5"><a class="xref" href="#topic_xml_kdj_zj">How JWT SSO for Zendesk works</a></li>
<li class="li" data-list-item-id="e599e172805b1f8e99a34b1405763d424"><a class="xref" href="#topic_u54_wc3_z2b">Requirements for enabling JWT SSO</a></li>
<li class="li" data-list-item-id="e5d2204e140f0b32531e783c4f02b63f6"><a class="xref" href="#topic_gds_ydj_zj">Enabling JWT SSO</a></li>
<li class="li" data-list-item-id="e00576019218ff512dbe238fdbc750eb9"><a class="xref" href="#topic_wgb_zsc_jhb">Assigning JWT SSO to users</a></li>
<li class="li" data-list-item-id="e25382af03232e319fc506a5e1d500e17"><a class="xref" href="#topic_tbs_zmb_2lb">Managing users in Zendesk after enabling JWT SSO</a></li>
<li class="li" data-list-item-id="e9c28332a26b2dd6c01876509559b1e68"><a class="xref" href="#topic_bjn_hfd_vhb">Generating a new shared secret</a></li>
<li class="li" data-list-item-id="ebfa691efd8c72d54d7719530e6e20e58"><a class="xref" href="#topic_qn4_tnb_2lb">Switching authentication methods</a></li>
<li class="li" data-list-item-id="eb3300600b418d2b27c39cd6042b7a8c5"><a class="xref" href="#topic_15m_mfj_zj">Additional information about JWT</a></li>
</ul>
</div>
<p class="p">The IT team in a company is usually responsible for setting up and managing the company's JWT authentication system. Their role is to implement SSO for Zendesk on the system. Refer the team to the following topic in this article:</p>
<ul class="ul" id="topic-1__ul_ikd_2tf_bfb"><li class="li" data-list-item-id="ec19552f0ed9fa05797e15c8d029724c0"><a class="xref" href="#topic_wkt_3zg_3fb">Technical implementation worksheet</a></li></ul>
<p class="p">Related articles:</p>
<div class="p"><ul class="ul" id="topic-1__ul_z11_m1k_my">
<li class="li" data-list-item-id="e2da5ca8e3528b86bcaff895be2f09321"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883587226" target="_blank" rel="noopener noreferrer">Single sign-on (SSO) options in Zendesk</a></li>
<li class="li" data-list-item-id="e941d2992c85ade021c0065cc16712b1b"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5380943678106" target="_blank" rel="noopener noreferrer">Giving users different ways to sign into Zendesk</a></li>
<li class="li" data-list-item-id="e25694e774978133025f7ff967060ecce"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882128666" target="_blank" rel="noopener noreferrer">Accessing your Zendesk account when your SSO service is down</a></li>
</ul></div>
</div><div class="topic nested1" id="topic_xml_kdj_zj" aria-labelledby="ariaid-title2">
<h2 class="title topictitle2" id="ariaid-title2">How JWT SSO for Zendesk works</h2>
<div class="body">
<p class="p">Once you enable SSO, sign-in requests are routed to a sign-in page external to Zendesk Support.</p>
<p class="p">Steps of the JWT SSO authentication process:</p>
<div class="p"><ol class="ol" id="topic_xml_kdj_zj__ol_nqb_zlj_zj">
<li class="li" data-list-item-id="ed045fa3b2877f5639c65d808e7d59b5d">An unauthenticated user navigates to your Zendesk Support URL. Example: <strong class="ph b">https://</strong><em class="ph i"><strong class="ph b">yoursubdomain</strong></em><strong class="ph b">.zendesk.com/</strong>.</li>
<li class="li" data-list-item-id="edbaab34aa14fcbddf25735617c6b3529">The Zendesk SSO mechanism recognizes that SSO is enabled and that the user is not authenticated.</li>
<li class="li" data-list-item-id="ef554cd3a0e5efa91d6bfa9672156dd75">Zendesk tries to determine whether the unauthenticated user is an end user or team member and redirects the user to your organization's appropriate remote sign-in page. Example: <strong class="ph b">https://</strong><em class="ph i"><strong class="ph b">mycompany</strong></em><strong class="ph b">.com/zendesk/sso</strong>.</li>
<li class="li" data-list-item-id="e308e279851de8d1c101b9724825052e9">A script on the remote server authenticates the user using your organization's proprietary sign-in process.</li>
<li class="li" data-list-item-id="e1488adb9b8825ef02c8f53c3a5b990af">The authentication system builds a JWT request that contains the relevant user data.</li>
<li class="li" data-list-item-id="ee8c98975535a7564d54cd129c09c3fbe">
<p>The authentication system redirects the user to the following Zendesk endpoint with the JWT payload:</p>
<p class="p"><strong class="ph b">https://</strong><em class="ph i"><strong class="ph b">yoursubdomain</strong></em><strong class="ph b">.zendesk.com/access/jwt</strong></p>
</li>
<li class="li" data-list-item-id="ef976e181a38219556a5a2e9b5a04a120">Zendesk verifies the token and then parses the user details from the JWT payload and grants the user a session.</li>
</ol></div>
<p class="p">As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct connection between Zendesk and your systems, so you can keep your authentication scripts safely behind your corporate firewall.</p>
</div>
</div><div class="topic nested1" id="topic_u54_wc3_z2b" aria-labelledby="ariaid-title3">
<h2 class="title topictitle2" id="ariaid-title3">Requirements for enabling JWT SSO</h2>
<div class="body">
<p class="p">Meet with the team in your company responsible for the JWT authentication system (usually the IT team) to make sure that Zendesk-bound traffic is over HTTPS, not HTTP.</p>
<div class="p">
<p>You'll need the following information to configure a JWT SSO method in Zendesk. Your IT team should be able to provide this to you.</p>
<ul class="ul" id="topic_u54_wc3_z2b__ul_sn2_tm3_z2b">
<li class="li" data-list-item-id="eb0025dae3af0ca8da2350011bb634c4f">The remote login URL where Zendesk users should be redirected when they attempt to access Zendesk</li>
<li class="li" data-list-item-id="e5fc9e1c6c2e1c88974c53e0e7b2e9357">(Optional) The remote logout URL where Zendesk can redirect users after they sign out of Zendesk</li>
<li class="li" data-list-item-id="e60375ff560c658bb04128dddc18459e0">(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 JWT 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.</li>
</ul>
</div>
<p class="p">The IT team may require additional information from Zendesk to configure the JWT implementation. Refer them to the <a class="xref" href="#topic_wkt_3zg_3fb">Technical implementation worksheet</a> in this article.</p>
<p class="p">After you've confirmed that you meet the requirements and have all of the necessary information, you're ready to <a class="xref" href="#topic_gds_ydj_zj">enable JWT SSO</a>.</p>
</div>
</div><div class="topic nested1" id="topic_gds_ydj_zj" aria-labelledby="ariaid-title4">
<h2 class="title topictitle2" id="ariaid-title4">Enabling JWT SSO</h2>
<div class="body">
<p class="p">Admins can enable JWT single sign-on only for end users, only for team members (including light agents and contributors), or for both groups. You can create multiple JWT SSO configurations. Before you start, obtain the required information from your company's IT team. See <a class="xref" href="#topic_u54_wc3_z2b">Requirements for enabling JWT SSO</a>.</p>
<p class="p"><strong class="ph b">To enable JWT single sign-on</strong></p>
<div class="p"><ol class="ol" id="topic_gds_ydj_zj__ol_fml_sqj_zj">
<li class="li" dir="ltr" data-list-item-id="e1f8c3f36e3cc8e20d8a96f2f1847b437">
<span class="ph">In </span><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank" rel="noopener noreferrer"><span class="ph">Admin Center</span></a><span class="ph">, click <img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png" id="topic_gds_ydj_zj__d9e251"> <strong class="ph b">Account</strong> in the sidebar, then select <strong class="ph b">Security &gt; Single sign-on</strong>.</span>
</li>
<li class="li" data-list-item-id="ee6a40ac24ea26012618639345723b424">Click <strong class="ph b">Create SSO configuration</strong> then select <strong class="ph b">JSON Web Token</strong>.</li>
<li class="li" data-list-item-id="e697425f126f82e0aa647b05c9bcc1525">Enter a unique <strong class="ph b">Configuration name</strong>.</li>
<li class="li" data-list-item-id="e953e41dc09b9ef5ff50c8dda82f155b6">
<p>For <strong class="ph b">Remote Login URL</strong>, enter the URL where your users should be redirected when they attempt to access your Zendesk URL.</p>
<p class="p">Zendesk automatically adds a <strong class="ph b">brand_id</strong> parameter to the URL. This is the Zendesk Support brand the user was on when they attempted to sign in.</p>
</li>
<li class="li" data-list-item-id="ec750503d4ec5fff77173f21ed08d97b6">
<p>(Optional) For <strong class="ph b">Remote Logout URL</strong>, a logout URL where users should be redirected after they sign out of Zendesk.</p>
<p class="p">Zendesk automatically adds <strong class="ph b">email</strong>, <strong class="ph b">external_id</strong>, and <strong class="ph b">brand_id</strong> parameters to the logout URL. If you prefer not to have email and external id information in the URL, specify blank parameters in the logout URL. Example:</p>
<p class="p"><strong class="ph b">https://www.xyz.com/user/signout/?email=&amp;external_id=</strong></p>
<div class="note">
<span class="notetitle">Note:</span> If you're using an Ember.js application, you must amend the logout URL to use blank parameters before the hash. For example, <code class="ph codeph">https://somedomain.com/?brand_id=&amp;return_to=&amp;email=#/zendesk-login/</code>.</div>
</li>
<li class="li" data-list-item-id="ec2eb982af068fec742304743173fb50b">
<p>(Optional) For <strong class="ph b">IP ranges</strong>, enter a list of IP ranges if you want to redirect users to the appropriate sign-in option.</p>
<p class="p">Users making requests from the specified IP ranges are routed to the JWT 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 JWT authentication sign-in form.</p>
</li>
<li class="li" data-list-item-id="ef8972920420ac052de3465124b3e584e">If you use external IDs for your users, you can update these in Zendesk Support by selecting <strong class="ph b">On</strong> for <strong class="ph b">Update of external ids?</strong>.</li>
<li class="li" data-list-item-id="e63e637c08bacf129854bf5e155cb663f">
<p>Provide the <strong class="ph b">Shared secret</strong> to your IT team. They'll need it for their JWT implementation.</p>
<div class="note important">
<span class="importanttitle">Important:</span> Keep the shared secret safe. If it's compromised, all the data in your Support account is at risk.</div>
</li>
<li class="li" data-list-item-id="e198218fe7fa5c3c2f6bf06c01880eb5b">
<p>Select <strong class="ph b">Show button when users sign in</strong> to add a <strong class="ph b">Continue with SSO</strong> button to the Zendesk sign-in page.</p>
<p class="p">You can customize the button label by entering a value in the <strong class="ph b">Button name</strong> field. Custom button labels are useful if you add multiple SSO buttons to the sign-in page. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882188570#topic_rqg_yw4_2yb" target="_blank" rel="noopener noreferrer">Adding "Continue with SSO" buttons to the Zendesk sign-in page</a> for more information.</p>
</li>
<li class="li" data-list-item-id="e2af2cc8ab7491a933622beacfd284fc4">Click <strong class="ph b">Save</strong>.</li>
</ol></div>
<p class="p">By default, enterprise SSO configurations are inactive. You must <a class="xref" href="#topic_wgb_zsc_jhb">assign the SSO configuration to users</a> to activate it.</p>
</div>
</div><div class="topic nested1" id="topic_wgb_zsc_jhb" aria-labelledby="ariaid-title5">
<h2 class="title topictitle2" id="ariaid-title5">Assigning JWT SSO to users</h2>
<div class="body">
<p class="p">After creating your JWT SSO configuration, you must activate it by assigning it to end users, team members, or both.</p>
<p class="p"><strong class="ph b">To assign an SSO configuration to team members or end users</strong></p>
<ol class="ol" id="topic_wgb_zsc_jhb__ol_i5x_ggd_jhb">
<li class="li" dir="ltr" data-list-item-id="e0bc741bf82514683f3994dbea47d443a">Open the Security settings for team members or end users.<ul class="ul" id="topic_wgb_zsc_jhb__ul_vyz_pxr_5qb">
<li class="li" data-list-item-id="e620c3a4c335e550ba458dbeae1968ac4">
<span class="ph">In </span><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank" rel="noopener noreferrer"><span class="ph">Admin Center</span></a><span class="ph">, click <img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png" id="topic_wgb_zsc_jhb__d9e221"> <strong class="ph b">Account</strong> in the sidebar, then select <strong class="ph b">Security &gt; Team member authentication</strong>.</span>
</li>
<li class="li" data-list-item-id="e78ca59d874749728bde6832e6e049a2a">
<span class="ph">In </span><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank" rel="noopener noreferrer"><span class="ph">Admin Center</span></a><span class="ph">, click <img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png" id="topic_wgb_zsc_jhb__d9e236"> <strong class="ph b">Account</strong> in the sidebar, then select <strong class="ph b">Security &gt; End user authentication</strong>.</span>
</li>
</ul>
</li>
<li class="li" data-list-item-id="e97bf7be9cd81108d5d2359cda8973c57">Select <strong class="ph b">External authentication</strong> to show the authentication options.</li>
<li class="li" data-list-item-id="ecd0abc77b39908c08d6878bf8cb2dd58">
<p>Select the name(s) of the SSO configuration(s) you want to use.</p>
<p class="p">Single sign-on might not cover all use cases, so Zendesk authentication remains active by default.</p>
</li>
<li class="li" data-list-item-id="ef71c3db1b028722438ab6c67fc2ed6ed">
<p>Select how you'd like to allow users to sign in.</p>
<p class="p"><img class="wysiwyg-image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_security_choose-sign_in.png" width="400" id="topic_wgb_zsc_jhb__image_ms1_dy4_2yb"></p>
<p class="p"><strong class="ph b">Let them choose</strong> allows users to sign in using any active authentication method. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5380943678106" target="_blank" rel="noopener noreferrer">Giving users different ways to sign into Zendesk</a>.</p>
<p class="p"><strong class="ph b">Redirect to SSO</strong> only allows users to authenticate using the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882188570#topic_c55_3sf_vsb" target="_blank" rel="noopener noreferrer">primary SSO configuration</a>. Users don’t see additional sign-in options, even if those authentication options are active. When you select <strong class="ph b">Redirect to SSO</strong>, the <strong class="ph b">Primary SSO</strong> field appears for you to select the primary SSO configuration.</p>
</li>
<li class="li" data-list-item-id="efac2cd76785cbb7471eae5110ead2684">Click <strong class="ph b">Save</strong>.</li>
</ol>
</div>
</div><div class="topic nested1" id="topic_tbs_zmb_2lb" aria-labelledby="ariaid-title6">
<h2 class="title topictitle2" id="ariaid-title6">Managing users in Zendesk after enabling JWT SSO</h2>
<div class="body">
<p class="p">After enabling JWT single sign-on in Zendesk, changes made to users outside Zendesk don't automatically sync to your Zendesk account. Users are updated in Zendesk at the point of authentication. For example, if a user is added to your internal system, the user is added to your Zendesk account when they sign in to Zendesk. If a user is deleted from your internal system, the user will no longer be able to sign in to Zendesk. However, their account will still exist in Zendesk.</p>
<p class="p">By default, the only user data stored in Zendesk when single sign-on is enabled is the user's name and email address. Zendesk does not store passwords. As a result, you should turn off any automated email notifications from Zendesk about passwords.</p>
<p class="p">To provide a better customer experience, you might want to store more than just the user's name and email address in Zendesk. You can do this using <a class="xref" href="#topic_otw_jfh_3fb">additional JWT attributes</a>.</p>
</div>
<div class="topic nested2" id="id_gtl_xzm_pcc" aria-labelledby="ariaid-title7">
<h3 class="title topictitle3" id="ariaid-title7">Turning off password notification emails from Zendesk</h3>
<div class="body">
<p class="p" dir="ltr">A Zendesk user profile is created for any new user who accesses your Zendesk account through SAML, JWT, or OpenID Connect (OIDC) single sign-on. Because users are authenticated through an IdP with a non-Zendesk password, the profile is created without a password because they don't need to sign in to Zendesk directly.</p>
<p class="p" dir="ltr">Because new users who sign in to Zendesk through SSO are verified through an IdP, they don't receive email notifications to verify their account. However, it is still recommended to turn off these automated email notifications to prevent them from being sent if the IdP does not successfully verify the user. In the case of SSO, user verification must always occur through the IdP.</p>
<p class="p"><strong class="ph b">To turn off password notification emails</strong></p>
<ol class="ol" id="id_gtl_xzm_pcc__d10e26">
<li class="li" data-list-item-id="e97320c24b9d07cbd510f81f8cef7f2f8">
<span class="ph">In </span><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank" rel="noopener noreferrer"><span class="ph">Admin Center</span></a><span class="ph">, click <img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_people_icon.png" id="id_gtl_xzm_pcc__d9e718"> <strong class="ph b">People</strong> in the sidebar, then select <strong class="ph b">Configuration &gt; End users</strong>.</span>
</li>
<li class="li" data-list-item-id="e1f5e0a265c42b2d145cf0749f9a8b1fc">In the <strong class="ph b">Account emails</strong> section, deselect <strong class="ph b">Also send a welcome email when a new user is created by an agent or administrator</strong>.</li>
<li class="li" data-list-item-id="e42adeec5d128ab0473969dad7eda3356">In <strong class="ph b">Allow users to change their password</strong>, deselect this option.</li>
</ol>
</div>
</div>
</div><div class="topic nested1" id="topic_bjn_hfd_vhb" aria-labelledby="ariaid-title8">
<h2 class="title topictitle2" id="ariaid-title8">Generating a new shared secret</h2>
<div class="body">
<p class="p">In some cases, like if your secret is compromised, you may need to issue a new JWT shared secret and provide it to your IT team or external identity provider. You can generate a new JWT shared secret from Zendesk Admin Center. This action will create a new secret and invalidate the old one. You'll need to inform your IT team or external identify provider of your new shared secret to keep Zendesk SSO account authentication working.</p>
<div class="note important">
<span class="importanttitle">Important:</span> Users cannot authenticate using JWT SSO until the new secret is in place. Make sure your users have a backup authentication method during this time.</div>
<p class="p"><strong class="ph b">To generate a new shared secret</strong></p>
<ol class="ol" id="topic_bjn_hfd_vhb__ol_d2k_zfd_vhb">
<li class="li" dir="ltr" data-list-item-id="e797bb08c0eb57006f88846a7ad7e2fe9">
<span class="ph">In </span><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank" rel="noopener noreferrer"><span class="ph">Admin Center</span></a><span class="ph">, click <img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png" id="topic_bjn_hfd_vhb__d9e251"> <strong class="ph b">Account</strong> in the sidebar, then select <strong class="ph b">Security &gt; Single sign-on</strong>.</span>
</li>
<li class="li" data-list-item-id="ec12986a0ec5ffe431913b9b341a1ce78">Hover over the JWT configuration you want to create a new shared secret for, then click the option menu icon (<img class="wysiwyg-image" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/uc_options_icon.png" id="topic_bjn_hfd_vhb__image_ggg_glz_5sb">) and select <strong class="ph b">Edit</strong>.</li>
<li class="li" data-list-item-id="e125aa6b9be6ce3e053db4e0fa55f4d7f">
<p>Scroll to <strong class="ph b">Shared secret</strong> at the bottom of the configuration page and click <strong class="ph b">Reset secret</strong>.</p>
<p class="p"><img class="wysiwyg-image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_security_reset_secret.png" width="400" id="topic_bjn_hfd_vhb__image_y23_2pm_vpb"></p>
<p class="p">A confirmation message appears.</p>
<p class="p"><img class="wysiwyg-image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_security_reset_secret_conf.png" width="300" id="topic_bjn_hfd_vhb__image_rgr_mpm_vpb"></p>
</li>
<li class="li" data-list-item-id="e8e261cc2081718a7332075d059b72707">
<p>Click <strong class="ph b">Reset secret</strong> to confirm the reset.</p>
<p class="p">You should see a new <strong class="ph b">Shared secret</strong> in plain text.</p>
<p class="p"><img class="wysiwyg-image img-screenshot" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_security_reset_secret_copy.png" width="400" id="topic_bjn_hfd_vhb__image_nv4_qpm_vpb"></p>
</li>
<li class="li" data-list-item-id="e788b12e69b7ebae9c8150da60748abc7">Click <strong class="ph b">Copy</strong> to make a copy of the new shared secret and give it to your IT team or your external identity provider.</li>
<li class="li" data-list-item-id="e9b793a7dc0161c97f5f21180c298b9d2">
<strong class="ph b">Save</strong> your changes.</li>
</ol>
</div>
</div><div class="topic nested1" id="topic_qn4_tnb_2lb" aria-labelledby="ariaid-title9">
<h2 class="title topictitle2" id="ariaid-title9">Switching authentication methods</h2>
<div class="body"><p class="p">If you use a third-party SSO method to create and authenticate users in Zendesk and 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.</p></div>
</div><div class="topic nested1" id="topic_15m_mfj_zj" aria-labelledby="ariaid-title10">
<h2 class="title topictitle2" id="ariaid-title10">Additional information about JWT</h2>
<div class="body">
<p class="p">JWT is an open standard that is being driven by the international standards body <a class="xref" href="http://en.wikipedia.org/wiki/Internet_Engineering_Task_Force" target="_blank" rel="noopener noreferrer">IETF</a> and has top-level backers from the technology sector (for example, Microsoft, Facebook, and Google).</p>
<p class="p">The fundamental building blocks of JWT are very well understood components and the result of this is a fairly simple spec, which is available here <a class="xref" href="http://tools.ietf.org/html/draft-jones-json-web-token-10" target="_blank" rel="noopener noreferrer">http://tools.ietf.org/html/draft-jones-json-web-token-10</a>. There are a lot of open source implementations of the JWT spec that cover most modern technologies. This means that you can get JWT single sign-on set up without much difficulty.</p>
<p class="p">One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don't put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. The string is Base64 encoded and then JWT makes an HMAC of the Base64 string which depends on the shared secret. This produces a signature that the recipient side can use to validate the user.</p>
</div>
</div><div class="topic nested1" id="topic_wkt_3zg_3fb" aria-labelledby="ariaid-title11">
<h2 class="title topictitle2" id="ariaid-title11">Technical implementation worksheet</h2>
<div class="body">
<p class="p">This section is for the team in the company responsible for the company's JWT authentication system. It provides details about the Zendesk JWT SSO implementation.</p>
<div class="note">
<span class="notetitle">Note:</span> If you're upgrading from an earlier version of Zendesk SSO (referred to as Zendesk Remote Authentication) to JWT, it's okay to have multiple SSO implementations enabled at the same time. Zendesk recognizes if a request is meant for JWT or another type of SSO and will handle the request accordingly. This means that you can enable and test JWT before deactivating your previous SSO implementation.</div>
<p class="p">Topics covered:</p>
<ul class="ul" id="topic_wkt_3zg_3fb__ul_xkt_3zg_3fb">
<li class="li" data-list-item-id="e3798a961af1f17028b80cd11f8869df3"><a class="xref" href="#topic_bt2_x2h_3fb">JWT algorithm</a></li>
<li class="li" data-list-item-id="edd80072a4d15cd7a7e23407e3c1df25b"><a class="xref" href="#topic_w5x_1fh_3fb">Zendesk JWT endpoint</a></li>
<li class="li" data-list-item-id="e31e1bdcdd88c385965e28c05830a40d8"><a class="xref" href="#topic_otw_jfh_3fb">JWT attributes</a></li>
<li class="li" data-list-item-id="e7778e4e0a1fad2f05521e44e4251f401"><a class="xref" href="#topic_hkm_kst_kk">Remote login URL parameter (return_to)</a></li>
<li class="li" data-list-item-id="e93e25db33808b01781dcd5abe094725b"><a class="xref" href="#topic_cff_kst_kk">Error handling</a></li>
<li class="li" data-list-item-id="ec8a611e4fb2e8ccf41899da03fcf3337"><a class="xref" href="#topic_kqp_sps_d1c">Form submission examples</a></li>
<li class="li" data-list-item-id="e6def5d23927d36173f8a83ad632969e1"><a class="xref" href="#topic_wjc_wdj_zj">JWT generation examples</a></li>
</ul>
</div>
<div class="topic nested2" id="topic_bt2_x2h_3fb" aria-labelledby="ariaid-title12">
<h3 class="title topictitle3" id="ariaid-title12">JWT algorithm</h3>
<div class="body">
<p class="p">Specify HS256 as the JWT algorithm in the header of your JWT payload:</p>
<div class="p"><pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">{
"typ":"JWT",
"alg":"HS256"
}</code></pre></div>
<p class="p">HS256 stands for HMAC SHA 256, a 256-bit encryption algorithm designed by the U.S. National Security Agency.</p>
<div class="note">
<span class="notetitle">Note:</span> Zendesk does not support the RS256 and ES256 JWT algorithms.</div>
</div>
</div>
<div class="topic nested2" id="topic_w5x_1fh_3fb" aria-labelledby="ariaid-title13">
<h3 class="title topictitle3" id="ariaid-title13">Zendesk JWT endpoint</h3>
<div class="body">
<div class="note important" id="topic_w5x_1fh_3fb__note_oxm_33t_dfc">
<span class="importanttitle">Important:</span> Using HTTP POST requests (instead of HTTP GET requests) is a best practice for your SSO security. Using HTTP POST, the user data is passed in the body of the request. With HTTP GET requests, data related to the user (like phone numbers or tags) are passed in the URL along with the JWT, which can be stored in a browser’s history or cache, putting it at risk for exposure.</div>
<p class="p">After successfully authenticating the user, create the JWT payload and submit a POST request that contains the JWT payload to the following Zendesk endpoint:</p>
<p class="p"><strong class="ph b">https://</strong><em class="ph i"><strong class="ph b">yoursubdomain</strong></em><strong class="ph b">.zendesk.com/access/jwt</strong></p>
<p class="p">The payload must be base64-encoded and submitted via a form submission from a client. Submitting the payload with a client-side AJAX, fetch, or axios request won't work because the request will be blocked by the client's <a class="xref" href="https://en.wikipedia.org/wiki/Same-origin_policy" target="_blank" rel="noopener noreferrer">same-origin policy</a>. Making a POST request from your server won't work either because it won't correctly set cookies used for authentication on the user's browser.</p>
<p class="p">The JWT payload must be sent to your Zendesk Support subdomain using the https protocol. Example:</p>
<div class="p"><pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">https://yoursubdomain.zendesk.com/access/jwt</code></pre></div>
<p class="p">If you have host mapping in place, you must send the JWT payload to your Zendesk Support subdomain using the HTTPS protocol, not the host-mapped domain.</p>
</div>
</div>
<div class="topic nested2" id="topic_otw_jfh_3fb" aria-labelledby="ariaid-title14">
<h3 class="title topictitle3" id="ariaid-title14">JWT attributes</h3>
<div class="body">
<p class="p">Send JWT attributes using a hash (Ruby) or dictionary (Python). The JWT must be encoded as base64. Example using Ruby:</p>
<pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">payload = JWT.encode({
:email =&gt; "bob@example.com", :name =&gt; "Bob", :iat =&gt; Time.now.to_i, :jti =&gt; rand(2&lt;&lt;64).to_s
}, "Our shared secret")</code></pre>
<p class="p">Zendesk requires an email address to uniquely identify the user. Beyond the required attributes listed in the table below, you may optionally send additional user profile data. This data is synced between your user management system and Zendesk Support.</p>
<p class="p">Attribute names are case sensitive, so you must match the exact casing shown in the tables below.</p>
<div class="p">
<p><strong class="ph b">Required attributes</strong></p>
<figure class="wysiwyg-table wysiwyg-table-align-left"><table class="simpletable" style="border-spacing: 0px;" id="topic_otw_jfh_3fb__simpletable_ork_15y_5sb">
<thead><tr class="sthead">
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e825">Attribute name</th>
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e828">Data type</th>
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e831">Description</th>
</tr></thead>
<tbody>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">iat</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">Numeric date</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">Issued At. The time the token was generated, this is used to help ensure that a given token gets used shortly after it's generated. The value must be the number of seconds since <a class="xref" href="http://en.wikipedia.org/wiki/Unix_time#Encoding_time_as_a_number" target="_blank" rel="noopener noreferrer">UNIX epoch</a>. Zendesk allows up to three minutes clock skew, so make sure to configure NTP or similar on your servers.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">jti</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">JSON Web Token ID. A unique id for the token, used by Zendesk to prevent token replay attacks.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">email</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">Email of the user being signed in, used to uniquely identify the user record in Zendesk Support.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">name</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">The name of this user. The user in Zendesk Support will be created or updated in accordance with this.</td>
</tr>
</tbody>
</table></figure>
</div>
<div class="p">
<p><strong class="ph b">Optional user attributes</strong></p>
<figure class="wysiwyg-table wysiwyg-table-align-left"><table class="simpletable" style="border-spacing: 0px;" id="topic_otw_jfh_3fb__simpletable_nth_d5y_5sb">
<thead><tr class="sthead">
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e896">Attribute</th>
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e899">Data type</th>
<th class="stentry" style="padding: 4px; text-align: left; vertical-align: bottom;" id="d92e902">Description</th>
</tr></thead>
<tbody>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">external_id</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">If your users are uniquely identified by something other than an email address, and their email addresses are subject to change, send the unique id from your system. Specify the id as a string.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">
<p>locale (for end-users)</p>
<p class="p">locale_id (for agents)</p>
</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">integer</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">The locale in Zendesk Support, specified as a number.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">organization</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">
<p>The name of an organization to add the user to. 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.</p>
<p class="p">If <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408838140314" target="_blank" rel="noopener noreferrer"><strong class="ph b">Allow users to belong to multiple organizations</strong></a> is turned on, additional organizations append the original organization and are considered secondary organizations. This does not delete the existing memberships.</p>
<p class="p">If you'd like to pass multiple organization names at the same time, use the <strong class="ph b">organizations</strong> attribute instead. Using the organizations attribute overwrites the existing list of organizations. The organization names must be passed in a string, separated by commas.</p>
</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">organization_id</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">integer</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">
<p>The organization's <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/" target="_blank" rel="noopener noreferrer">external ID</a> in the Zendesk API. If both organization and organization_id are supplied, organization is ignored. 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.</p>
<p class="p">If <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408838140314" target="_blank" rel="noopener noreferrer"><strong class="ph b">Allow users to belong to multiple organizations</strong></a> is turned on, additional organizations append the original organization and are considered secondary organizations. This does not delete the existing memberships.</p>
<p class="p">If you'd like to pass multiple organization IDs at the same time, use the <strong class="ph b">organization_ids</strong> attribute instead. Using the organization_ids attribute overwrites the existing list of organizations. The organization IDs must be passed in a string, separated by commas.</p>
</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">phone</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">
<p>A phone number, specified as a string.</p>
<p class="p">The phone number should comply with the E.164 international <a class="xref" href="https://en.wikipedia.org/wiki/E.164" target="_blank" rel="noopener noreferrer">telephone numbering plan</a>. Example: +15551234567.</p>
<p class="p">E164 numbers are international numbers with a country dial prefix, usually an area code and a subscriber number. A valid E.164 phone number must include a <a class="xref" href="https://en.wikipedia.org/wiki/List_of_country_calling_codes" target="_blank" rel="noopener noreferrer">country calling code</a>.</p>
</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">tags</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">array</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">This is a JSON array of tags to set on the user. These tags will <em class="ph i">replace</em> any other tags that may exist in the user's profile.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">remote_photo_url</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">URL for a photo to set on the user profile.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">role</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">string</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">The user's role. This value can be set to <strong class="ph b">end_user</strong>, <strong class="ph b">agent</strong>, or <strong class="ph b">admin</strong>. The default is <strong class="ph b">end_user</strong>. If the user's role differs from the one in Zendesk Support, the role is changed in Zendesk Support.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">custom_role_id</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">integer</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">Applicable only if the role of the user is agent. When provided, the user's custom role is updated to match this value every time they sign in.</td>
</tr>
<tr class="strow">
<td class="stentry" style="padding: 4px; vertical-align: top;">user_fields</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">object</td>
<td class="stentry" style="padding: 4px; vertical-align: top;">
<p class="p">A JSON hash of custom user field key and values to set on the user. The custom user field must exist in order to set the field value. Each custom user field is identified by its field key found in the user fields admin settings. The format of date values is yyyy-mm-dd.</p>
<div class="p">
<p>If a custom user field key or value is invalid, updating the field will fail silently and the user will still log in successfully. For more information about custom user fields, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408822051866" target="_blank" rel="noopener noreferrer">Adding custom fields to users</a>.</p>
<div class="note">
<span class="notetitle">Note:</span> Sending null values in the the user_fields attribute will remove any existing values in the corresponding fields.</div>
</div>
</td>
</tr>
</tbody>
</table></figure>
</div>
</div>
</div>
<div class="topic nested2" id="topic_hkm_kst_kk" aria-labelledby="ariaid-title15">
<h3 class="title topictitle3" id="ariaid-title15">Remote login URL parameter (return_to)</h3>
<div class="body">
<p class="p">Whether you pass in the <code class="ph codeph">return_to</code> parameter or not is optional, but we recommend it for the best user experience. When Zendesk redirects a user to your remote login page, it can pass a <strong class="ph b">return_to</strong> URL parameter. The parameter contains the page that Zendesk will return the user after your system has authenticated the user. Append the parameter name and value to the Zendesk JWT endpoint.</p>
<p class="p">For example, suppose an agent who is signed out clicks the following link to open a ticket in Support: <strong class="ph b">https://mycompany.zendesk.com/tickets/1232</strong>. The flow is as follows:</p>
<ol class="ol" id="topic_hkm_kst_kk__ol_2mb_pst_kk">
<li class="li" data-list-item-id="ed3ad5b6ed2c4d7f702dab14195c636ce">
<p>On click, Zendesk redirects the user to your remote login URL and appends the following <code class="ph codeph">return_to</code> parameter to the URL: </p>
<pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123</code></pre>
</li>
<li class="li" data-list-item-id="ef0df6827f8ac813f805b4154cb060085">
<p>Your authentication system takes the <code class="ph codeph">return_to</code> parameter from the URL and, after successfully authenticating the user, appends it to the Zendesk JWT endpoint or adds it to the body of the request. Example:</p>
<pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">https://mycompany.zendesk.com/access/jwt?&amp;return_to=https://mycompany.zendesk.com/tickets/123</code></pre>
</li>
<li class="li" data-list-item-id="e84e657ddd25f1543e0fffac3e969d930">Zendesk uses the parameter to open the ticket page for the agent.</li>
</ol>
<p class="p">The <code class="ph codeph">return_to</code> parameter is an absolute URL for the agent interface, and a relative URL for Help Center.</p>
<div class="p"><div class="note">
<span class="notetitle">Note:</span> If your <code class="ph codeph">return_to</code> address contains its own URL parameters, make sure that your script URI-encodes the entire return_to value when submitting the JWT token.</div></div>
</div>
</div>
<div class="topic nested2" id="topic_cff_kst_kk" aria-labelledby="ariaid-title16">
<h3 class="title topictitle3" id="ariaid-title16">Error handling</h3>
<div class="body"><p class="p">If Zendesk encounters an error while processing a JWT login request, it sends a message that explains the issue. If you specified a remote logout URL when you configured the JWT integration, it redirects to that URL and passes a <strong class="ph b">message</strong> and a <strong class="ph b">kind</strong> parameter. In case of error, the <strong class="ph b">kind</strong> parameter always has the value "error". Zendesk recommends specifying a remote logout URL, as well as logging messages from Zendesk alongside the type. Most of the errors that can happen are ones that you'll want to fix. Examples include clock drifts, rate limits being hit, and invalid tokens.</p></div>
</div>
<div class="topic nested2" id="topic_kqp_sps_d1c" aria-labelledby="ariaid-title17">
<h3 class="title topictitle3" id="ariaid-title17">Form submission examples</h3>
<div class="body">
<p class="p">The JWT payload must be submitted using a form submission from a browser to the following Zendesk endpoint:</p>
<div class="p"><pre class="pre codeblock wysiwyg-code-block"><code class="language-auto">https://yoursubdomain.zendesk.com/access/jwt</code></pre></div>
<p class="p">Zendesk provides a series of examples for various technology stacks in the <a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples" target="_blank" rel="noopener noreferrer">Zendesk JWT SSO repository</a> on GitHub. You must submit the JWT payload using a form submission from a browser to ensure cookies can be set correctly on the browser and that the request isn’t blocked by CORS.</p>
<div class="p">
<p>See the following form submission examples:</p>
<ul class="ul" id="topic_kqp_sps_d1c__ul_v13_wsg_ncc">
<li class="li" data-list-item-id="e25a322c084e7e6c524276f27dabe8b9b"><a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/blob/master/form_submission/javascript_jwt.html" target="_blank" rel="noopener noreferrer">JavaScript example</a></li>
<li class="li" data-list-item-id="ee12e1aeafd5f483c4e9884c705f988f2"><a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/blob/master/form_submission/jquery_xhr_jwt.js" target="_blank" rel="noopener noreferrer">jQuery example</a></li>
<li class="li" data-list-item-id="e298c8d63fc1b5d14374fa3e64f3c1f54"><a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/blob/master/form_submission/rails_html_erb_jwt.rb" target="_blank" rel="noopener noreferrer">Rails example</a></li>
<li class="li" data-list-item-id="e5bd619435c07c0595bbe007bfbf79b21"><a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/blob/master/form_submission/react_jwt.jsx" target="_blank" rel="noopener noreferrer">React example</a></li>
</ul>
</div>
<p class="p"><strong class="ph b">Response</strong></p>
<p class="p">The response should be HTML with a <code class="ph codeph">200 OK</code> status. The response format is as follows:</p>
<pre class="pre codeblock wysiwyg-code-block" id="topic_kqp_sps_d1c__codeblock_pkk_2rs_d1c"><code class="language-auto">&lt;html&gt;&lt;body&gt;You are being &lt;a href=""&gt;redirected&lt;/a&gt;.&lt;/body&gt;&lt;/html&gt;</code></pre>
<p class="p">If the <code class="ph codeph">href</code> matches your <code class="ph codeph">return_to</code> value, then the user was successfully authenticated and cookies should be set. If the <code class="ph codeph">href</code> begins with <code class="ph codeph">https://SUBDOMAIN.zendesk.com/access/unauthenticated</code>, then Zendesk was unable to authenticate the user.</p>
</div>
</div>
<div class="topic nested2" id="topic_wjc_wdj_zj" aria-labelledby="ariaid-title18">
<h3 class="title topictitle3" id="ariaid-title18">JWT generation examples</h3>
<div class="body">
<p class="p">The actual JWT encoding is straightforward and most modern languages have libraries that support it. Zendesk provides a series of examples for various stacks in the JWT SSO GitHub repository:</p>
<div class="p"><ul class="ul" id="topic_wjc_wdj_zj__ul_xhn_ndr_2k"><li class="li" data-list-item-id="e9dbd1b95b941a176b055fb5c5cff4b63"><a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/jwt_generation" target="_blank" rel="noopener noreferrer">https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/jwt_generation</a></li></ul></div>
<p class="p">The JWT generation code is for your server implementation. You can pass the generated JWT back to your login page and then initiate the form submission from the browser.</p>
<p class="p">If you implement JWT in any other stack, we would love to feature an example of that there as well. Add a comment to this article to share what you've implemented.</p>
<p class="p">In case you run IIS/AD and don't want to build your own .NET solution, we provide a full implementation in classic ASP, which requires you to adjust only a couple of variables. <a class="xref" href="https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/bundles" target="_blank" rel="noopener noreferrer">Download the ASP authentication script</a> from Github.</p>
</div>
</div>
</div><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/4408845838874",
"url": "https://support.zendesk.com/hc/en-us/articles/4408845838874-Enabling-JWT-single-sign-on",
"headline": "Enabling JWT single sign-on",
"description": "You can enable and configure JSON Web Token (JWT) single sign-on to authenticate users through your own system and grant them access without separate credentials, managing user assignments and security settings accordingly.",
"articleSection": "User sign-in",
"datePublished": "2021-10-16T05:16:29+00:00",
"dateModified": "2025-09-05T23:26:15+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408845838874"
},
"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><script id="fast-path-script">
//<![CDATA[
const fast_path_style = document.createElement('style');
fast_path_style.innerHTML = `#article-body .fastpath{font-size:.9em;background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 8px;margin-bottom:16px}#article-body .fastpath::before{content:none!important}`;
document.head.appendChild(fast_path_style);
//]]>
</script>
<script id="ai-summary-script">
//<![CDATA[
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//]]>
</script>
</p>