Setting up single sign-on with OpenID Connect (OIDC)

<body>
<p id="docs-hc-snippet" style="display: none;">OpenID Connect (OIDC)is an authentication protocol built on the OAuth 2.0 framework. It enables developers to authenticate users and obtain basic profile information in a secure and standardized manner. OIDC uses ID tokens to verify the identity of users based on the authentication performed by an authorization server, simplifying the process of managing user identities and enhancing the security of interactions between users and applications.</p>
<div class="article-banners">
<div id="docs-wmp-link">
<a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a>
</div>

<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>

<div class="article-banner" id="support_all">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Team, Professional, or Enterprise</td>
</tr>
</tbody>
</table>
</div>

</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">Summary: <span id="up-triangle">◀</span><span id="down-triangle">▼</span></p>
<p id="docs-ai-summary-content">Set up single sign-on with OpenID Connect (OIDC) to let users authenticate via a central identity provider, simplifying login and enhancing security. You can configure OIDC for end users, team members, or both, assign it, and manage user attributes like email and role. OIDC supports standard and custom attributes, requires users to start sign-in at your support URL, and doesn't sync user changes automatically.</p>
</div>

<div class="body">

<div class="note fastpath" id="ac_security_sso_OIDC__note_kqc_xsm_pcc">
<span class="fastpathtitle">Location: </span> <span class="ph">Admin Center &gt; Account &gt; Security &gt; Single
sign-on</span>
</div>
<p class="p"><a class="xref" href="https://openid.net/developers/how-connect-works/" target="_blank">OpenID Connect (OIDC)</a> is an authentication protocol built on
the OAuth 2.0 framework. It enables developers to authenticate users and obtain basic
profile information in a secure and standardized manner. OIDC uses ID tokens to verify
the identity of users based on the authentication performed by an authorization server,
simplifying the process of managing user identities and enhancing the security of
interactions between users and applications.</p>
<p class="p">OIDC single sign-on (SSO) with Zendesk streamlines the authentication process by allowing
users to sign in using a central identity provider (IdP) like Google or Okta rather than
managing separate login credentials for Zendesk.</p>
<div class="p">This article contains the following topics:<ul class="ul" id="ac_security_sso_OIDC__ul_zxz_tnp_tcc">
<li class="li"><a class="xref" href="#topic_dcx_h5m_pcc">How OIDC SSO for Zendesk works</a></li>
<li class="li"><a class="xref" href="#topic_e5n_1ym_pcc">Important considerations</a></li>
<li class="li"><a class="xref" href="#topic_j1d_fym_pcc">Creating the OIDC SSO configuration</a></li>
<li class="li"><a class="xref" href="#topic_wxq_hym_pcc">Assigning OIDC SSO to users</a></li>
<li class="li"><a class="xref" href="#topic_wb2_jym_pcc">Managing users in Zendesk after turning on OIDC SSO</a></li>
<li class="li"><a class="xref" href="#topic_m2g_lym_pcc">Switching authentication methods</a></li>
<li class="li"><a class="xref" href="#topic_d1r_523_l3">Attributes supported by Zendesk</a></li>
</ul>
</div>
<p class="p">Related articles:</p>
<div class="p">
<ul class="ul" id="ac_security_sso_OIDC__ul_z11_m1k_my">
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882188570" target="_blank">Managing single sign-on (SSO)
configurations</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883587226" target="_blank">Single sign-on (SSO) options in
Zendesk</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5380943678106" target="_blank">Giving users different ways to sign into
Zendesk</a></li>
<li class="li"><a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882128666" target="_blank">Accessing your Zendesk account when your SSO
service is down</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_dcx_h5m_pcc">
<h2 class="title topictitle2" id="ariaid-title2">How OIDC SSO for Zendesk works</h2>
<div class="body">
<p class="p">OIDC SSO allows a user to authenticate with an IdP using a standard protocol. Once
authenticated, the IdP issues an ID token that is used to verify the user's identity
and access permissions.</p>
<p class="p">Steps of the Zendesk SSO process with OIDC:</p>
<div class="p">
<ol class="ol" id="topic_dcx_h5m_pcc__ol_nqb_zlj_zj">
<li class="li">An unauthenticated user navigates to your Zendesk Support URL. Example:
<strong class="ph b">https://<em class="ph i">yoursubdomain</em>.zendesk.com/</strong>.</li>
<li class="li">Depending on your sign-in workflow, the user clicks a button on the Zendesk
sign-in page to sign in with SSO, directing them to your IdP, or is
automatically redirected to your IdP to sign in.</li>
<li class="li">After the user authenticates successfully, the IdP generates an ID token
that contains user-specific information.</li>
<li class="li">Zendesk receives the token at the callback URL:
<strong class="ph b">https://<em class="ph i">yoursubdomain</em>.zendesk.com/access/oidc/callback</strong>.
The token is validated against the configuration details shared between
Zendesk and the IdP.</li>
<li class="li">After successful validation, Zendesk grants the user access, leveraging the
trust established by the IdP.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_e5n_1ym_pcc">
<h2 class="title topictitle2" id="ariaid-title3">Important considerations</h2>
<div class="body">
<div class="p">
<ul class="ul" id="topic_e5n_1ym_pcc__ul_ovt_tnl_tcc">
<li class="li">OIDC doesn't natively support an IdP-initiated sign-in flow. As a result,
users signing in with OIDC SSO will always start their sign-in workflow by
navigating to your Zendesk Support URL.</li>
<li class="li">It's not possible to use OIDC to authenticate users in messaging.</li>
<li class="li">Zendesk requires all users to have an email address associated with their
profile, but your users might try to sign in without having an email
address. In this scenario, to prevent a loop where the authentication fails
because of a missing email address, Zendesk will display an error
message.</li>
<li class="li">RSA256 is the default JWT decoding algorithm. To use another algorithm (such
as ES256), specify it in your OpenID provider discovery endpoint.</li>
<li class="li">If you want to use OIDC with Entra, a few specific requirements need to be
configured. <ul class="ul" id="topic_e5n_1ym_pcc__ul_rh4_14l_tcc">
<li class="li">The Authentication mode must be <strong class="ph b">PKCE</strong>.</li>
<li class="li">Add the callback URL on the Entra OIDC PKCE configuration form under
<strong class="ph b">Mobile and desktop applications - Redirect URIs</strong>.</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_j1d_fym_pcc">
<h2 class="title topictitle2" id="ariaid-title4">Creating the OIDC SSO configuration</h2>
<div class="body">
<p class="p">Admins can enable OIDC single sign-on only for end users, only for team members
(including light agents and contributors), or for both groups. You can create
multiple OIDC SSO configurations. </p>
<p class="p">The information needed for this step must come from the IdP you're using, so make
sure your IdP is set up before you start. You may have to obtain the information
from your company's IT team.</p>
<p class="p"><strong class="ph b">To create the OIDC SSO configuration in Zendesk</strong></p>
<div class="p">
<ol class="ol" id="topic_j1d_fym_pcc__ol_j5z_4qj_l3">
<li class="li" dir="ltr"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_j1d_fym_pcc__d9e323" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png">
<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">Click <strong class="ph b">Create SSO configuration</strong>, then select <strong class="ph b">OpenID
Connect</strong>.</li>
<li class="li">Enter a unique <strong class="ph b">Configuration name</strong>.</li>
<li class="li">(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 class="p">Users making requests
from the specified IP ranges are routed to the remote OIDC
authentication sign-in form. Users making requests from IP addresses
outside the ranges are routed to the standard Zendesk sign-in form.
Don't specify a range if you want all users to be redirected to the
remote authentication sign-in form.</p>
</li>
<li class="li">In the <strong class="ph b">Client ID</strong> field, enter the Client ID given to you by your
IdP.</li>
<li class="li">Enter the <strong class="ph b">Client secret</strong> if your IdP requires it.<p class="p">Because the client
secret must be kept confidential, you won't see the full secret again
after you save the configuration. If you need to rotate the secret, edit
this SSO configuration to enter and save a new secret.</p>
</li>
<li class="li">In the <strong class="ph b">Scopes</strong> field, list all the scopes you want to request from the
IdP. At a minimum, you must add <code class="ph codeph">openid</code> and
<code class="ph codeph">email</code>. Scopes are separated with spaces and no commas.
For example: <code class="ph codeph">openid email phone</code><p class="p">Supported scopes within
the OIDC standard include <code class="ph codeph">openid</code>,
<code class="ph codeph">profile</code>, <code class="ph codeph">email</code>,
<code class="ph codeph">address</code>, and <code class="ph codeph">phone</code>. You can also
list any custom scopes that have been configured in your
IdP.</p>
<p class="p">Unaccepted scopes that your IdP rejects will cause sign-in to
fail with the error <code class="ph codeph">Unknown error during sign-in</code>.
Zendesk doesn't validate any of the scopes in this field.</p>
</li>
<li class="li">Select <strong class="ph b">Turn on auto discovery</strong> if you only want to provide the Issuer
URL. When this is turned on, Zendesk will automatically extract the
configuration details from the OIDC Configuration Document. You only need to
provide the Issuer URL and Authentication Mode.</li>
<li class="li">Enter the required URLs. <p class="p">Check if your IdP requires a specific format for
the URLs you are using. If the URLs are incorrectly formatted and
rejected by your IdP, you may encounter a sign-in failure accompanied by
the error message <code class="ph codeph">Unknown error during sign-in</code>. Zendesk
doesn't validate the URLs in these fields.</p>
<ul class="ul" id="topic_j1d_fym_pcc__ul_aty_32r_tcc">
<li class="li">
<strong class="ph b">Issuer URL</strong> (also known as the issuer identifier): A unique
identifier for the IdP that performs user authentication and
delivers the ID tokens.</li>
<li class="li">
<strong class="ph b">UserInfo URL</strong>: An endpoint provided by the IdP that, when
accessed with a valid access token, returns attributes about the
authenticated user.</li>
<li class="li">
<strong class="ph b">JWKs URL</strong>: An endpoint provided by the IdP that allows Zendesk
to retrieve the provider's public keys. These keys are used to
verify the signature of JSON web tokens (JWTs) that the IdP
issues.</li>
<li class="li">
<strong class="ph b">Authorization URL</strong>: When users access this URL, they are
prompted to sign in and consent to the requested scopes.</li>
<li class="li">
<strong class="ph b">Access URL</strong> (also known as the token endpoint URL): Used to
exchange an authorization code, client ID, and client secret for an
access token.</li>
</ul>
</li>
<li class="li">Choose an <strong class="ph b">Authentication Mode</strong>. <strong class="ph b">PKCE</strong> is recommended. <ul class="ul" id="topic_j1d_fym_pcc__ul_jdt_y3r_tcc">
<li class="li">Using <strong class="ph b">PKCE</strong> to obtain the access token is best for public
clients, like mobile or Javascript web apps, as it uses dynamically
generated keys to prevent unauthorized token exchange without
needing a client secret.</li>
<li class="li">Choose <strong class="ph b">Authorization code flow</strong> if you want the access token
to be obtained using Authorization code flow. This is best for
server-based apps with secure back-end storage that rely on a client
secret to obtain tokens.</li>
</ul>
</li>
<li class="li">Select <strong class="ph b">Show button when users sign in</strong> if you <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5380943678106" target="_blank">let users choose how they sign in</a>
and want this configuration to be an option they can choose from. If you
select this option, you also need <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882188570#topic_rqg_yw4_2yb" target="_blank">name the button</a> that will be shown
on the Zendesk sign-in page. <p class="p">Clear this box if your users only sign in
using an identity provider because they don't use the Zendesk sign-in
page.</p>
</li>
<li class="li">Click <strong class="ph b">Save</strong>.<p class="p">By default, enterprise SSO configurations are inactive.
You must <a class="xref" href="#topic_wxq_hym_pcc">Assign OIDC SSO
to users</a> to activate it.</p>
</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested1" id="topic_wxq_hym_pcc">
<h2 class="title topictitle2" id="ariaid-title5">Assigning OIDC SSO to users</h2>
<div class="body">
<p class="p">After creating your OIDC 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_wxq_hym_pcc__ol_i5x_ggd_jhb">
<li class="li" dir="ltr">Open the Security settings for team members or end users. <ul class="ul" id="topic_wxq_hym_pcc__ul_vyz_pxr_5qb">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_wxq_hym_pcc__d9e293" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png">
<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"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_wxq_hym_pcc__d9e308" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_account_icon.png">
<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">Select <strong class="ph b">External authentication</strong> to show the authentication options. </li>
<li class="li">Select the name(s) of the SSO configuration(s) you want to use. <p class="p">Single
sign-on might not cover all use cases, so Zendesk authentication remains
active by default. </p>
</li>
<li class="li">Select how you'd like to allow users to sign in. <p class="p"><img class="image img-screenshot" id="topic_wxq_hym_pcc__image_ms1_dy4_2yb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_security_choose-sign_in.png" width="400"></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">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">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">Click <strong class="ph b">Save</strong>.</li>
</ol>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested1" id="topic_wb2_jym_pcc">
<h2 class="title topictitle2" id="ariaid-title6">Managing users in Zendesk after turning on OIDC SSO</h2>
<div class="body">
<p class="p">After enabling OIDC 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>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested2" id="id_nhg_wzm_pcc">
<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_nhg_wzm_pcc__d10e26">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="id_nhg_wzm_pcc__d9e811" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_people_icon.png">
<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">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">In <strong class="ph b">Allow users to change their password</strong>, deselect this option.</li>
</ol>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested1" id="topic_m2g_lym_pcc">
<h2 class="title topictitle2" id="ariaid-title8">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 aria-labelledby="ariaid-title9" class="topic nested1" id="topic_d1r_523_l3">
<h2 class="title topictitle2" id="ariaid-title9">Attributes supported by Zendesk</h2>
<div class="body">
<div class="p">Zendesk supports standard and custom OIDC attributes.<ul class="ul" id="topic_d1r_523_l3__ul_emd_tyx_tcc">
<li class="li">
<em class="ph i">Standard</em> attributes are predefined, widely accepted attributes
specified by the OIDC protocol and ensure a uniform understanding of user
identity across different systems. Zendesk supports the following standard
attributes: <ul class="ul" id="topic_d1r_523_l3__ul_h4f_cmk_h2c">
<li class="li"><code class="ph codeph">sub</code></li>
<li class="li"><code class="ph codeph">email</code></li>
<li class="li"><code class="ph codeph">email_verified</code></li>
<li class="li"><code class="ph codeph">locale</code></li>
<li class="li">
<code class="ph codeph">phone number</code> (maps to Zendesk user attribute
<code class="ph codeph">phone</code>)</li>
<li class="li">
<code class="ph codeph">photo</code> (maps to Zendesk user attribute
<code class="ph codeph">remote_photo_url</code>)</li>
<li class="li">
<code class="ph codeph">preferred_username</code> (maps to Zendesk user attribute
<code class="ph codeph">alias</code>)</li>
<li class="li">
<code class="ph codeph">zoneinfo</code> (maps to Zendesk user attribute
<code class="ph codeph">time_zone</code>)</li>
</ul>
</li>
<li class="li">
<em class="ph i">Custom</em> attributes are additional attributes that extend the standard
set to meet Zendesk-specific requirements. You can pass custom attributes in
the ID token or userinfo claims.</li>
</ul>
</div>
<p class="p">The table below is a complete list of standard and custom attributes supported by
Zendesk. Attribute names are case sensitive, so you must match the exact casing
shown in the table below.</p>
<div class="p">
<table border="1" cellpadding="4" cellspacing="0" class="simpletable" id="topic_d1r_523_l3__simpletable_qg2_dqr_5sb" summary="">
<col style="width:50%">
<col style="width:50%">
<thead>
<tr class="sthead">
<th class="stentry" id="d92e670" style="vertical-align:bottom;text-align:left;">Attribute name</th>
<th class="stentry" id="d92e673" style="vertical-align:bottom;text-align:left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">name</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">The user's full name in displayable form including all name parts,
possibly including titles and suffixes, ordered according to the end
user's locale and preferences. If no name is present, this defaults to
the user's primary email address.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">email</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">The user's primary email address.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">email_verified</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">True if the user's email address has been verified; otherwise
false. When this attribute value is true, this means that the OpenID
Provider took affirmative steps to ensure that this email address was
controlled by the user at the time the verification was performed. When
you use SSO at Zendesk, it's your responsibility to verify your user's
email addresses.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">organization</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">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. <p class="p">If <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408838140314" target="_blank"><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" headers="d92e670" style="vertical-align:top;">organization_id</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">
<p class="p">The organization's <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/" target="_blank">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"><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" headers="d92e670" style="vertical-align:top;">phone</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">A phone number, specified as a string.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">tags</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">Tags to set on the user. The tags will replace any other tags that
may exist in the user's profile.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">remote_photo_url</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">URL for a photo to set on the user profile. </td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">locale (for agents)<p class="p">locale_id (for end users)</p>
</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">The locale in Zendesk.<p class="p">For agents, <code class="ph codeph">locale</code> should
be the full locale string, for example:
<code class="ph codeph">en-us</code></p>
<p class="p">For end users,
<code class="ph codeph">locale_id</code> should be specified as a string. Add
the specified number of a locale in a quoted string, for example:
<code class="ph codeph">"locale_id": "2"</code></p>
<p class="p"> To get a list of valid
numbers, see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/support/locales" target="_blank">Locales</a> in the API docs.</p>
</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">zendesk_role</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">The user's role. Can be set to <strong class="ph b">end-user</strong> , <strong class="ph b">agent</strong>, or
<strong class="ph b">admin</strong>. If you don't pass a zendesk_role, then Zendesk creates
the user as an end user, unless they already exist with another
role.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">custom_role_id</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">Applicable only if the value of the <strong class="ph b">role</strong> attribute above is
<strong class="ph b">agent</strong>. You can get the IDs of your custom roles with the
<a class="xref" href="https://developer.zendesk.com/rest_api/docs/support/custom_roles" target="_blank">Custom Roles API</a>. </td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">external_id</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">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.</td>
</tr>
<tr class="strow">
<td class="stentry" headers="d92e670" style="vertical-align:top;">user_field_&lt;key&gt;</td>
<td class="stentry" headers="d92e673" style="vertical-align:top;">A value for a custom user field in Zendesk Support. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408822051866" target="_blank">Adding custom fields to users</a>.
The &lt;key&gt; is the field key assigned to the custom user field in
Zendesk Support. Example: <code class="ph codeph">user_field_employee_number</code>
where <code class="ph codeph">employee_number</code> is 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. </td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/7957465432474-Setting-up-single-sign-on-with-OpenID-Connect-OIDC",
"url": "https://support.zendesk.com/hc/en-us/articles/7957465432474-Setting-up-single-sign-on-with-OpenID-Connect-OIDC",
"headline": "Setting up single sign-on with OpenID Connect (OIDC)",
"description": "You can set up single sign-on using OpenID Connect (OIDC) to authenticate users through a central identity provider, configure the SSO settings, assign it to users, and manage user access and attributes accordingly.",
"articleSection": "User sign-in",
"datePublished": "2024-09-04T20:43:47+00:00",
"dateModified": "2026-05-19T15:46:04.554980+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/7957465432474-Setting-up-single-sign-on-with-OpenID-Connect-OIDC"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"url": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"url": "https://support.zendesk.com/hc/en-us"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk"
}
}</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>
</body>