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

Set up single sign-on with OpenID Connect (OIDC) to simplify user authentication using a central identity provider, like Google or Okta. This enhances security and reduces the need for multiple login credentials. Consider key points like the need for email addresses and managing users post-setup. Customize configurations for end users or team members and manage attributes like roles and organizations.





Location: Admin Center > Account > Security > Single
sign-on

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.
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.
This article contains the following topics:
How OIDC SSO for Zendesk works
Important considerations
Creating the OIDC SSO configuration
Assigning OIDC SSO to users
Managing users in Zendesk after turning on OIDC SSO
Switching authentication methods
Attributes supported by Zendesk


Related articles:


Managing single sign-on (SSO)
configurations
Single sign-on (SSO) options in
Zendesk
Giving users different ways to sign into
Zendesk
Accessing your Zendesk account when your SSO
service is down




How OIDC SSO for Zendesk works

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.
Steps of the Zendesk SSO process with OIDC:


An unauthenticated user navigates to your Zendesk Support URL. Example:
https://yoursubdomain.zendesk.com/.
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.
After the user authenticates successfully, the IdP generates an ID token
that contains user-specific information.
Zendesk receives the token at the callback URL:
https://yoursubdomain.zendesk.com/access/oidc/callback.
The token is validated against the configuration details shared between
Zendesk and the IdP.
After successful validation, Zendesk grants the user access, leveraging the
trust established by the IdP.





Important considerations



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.
It's not possible to use OIDC to authenticate users in messaging.
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.
RSA256 is the default JWT decoding algorithm. To use another algorithm (such
as ES256), specify it in your OpenID provider discovery endpoint.
If you want to use OIDC with Entra, a few specific requirements need to be
configured.
The Authentication mode must be PKCE.
Add the callback URL on the Entra OIDC PKCE configuration form under
Mobile and desktop applications - Redirect URIs.







Creating the OIDC SSO configuration

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.
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.
To create the OIDC SSO configuration in Zendesk


In Admin Center, click
Account in the sidebar, then select Security > Single sign-on.
Click Create SSO configuration, then select OpenID
Connect.
Enter a unique Configuration name.
(Optional) For IP ranges, enter a list of IP ranges if you want to
redirect users to the appropriate sign-in option. 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.

In the Client ID field, enter the Client ID given to you by your
IdP.
Enter the Client secret if your IdP requires it. 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.

In the Scopes field, list all the scopes you want to request from the
IdP. At a minimum, you must add openid and
email. Scopes are separated with spaces and no commas.
For example: openid email phone Supported scopes within
the OIDC standard include openid,
profile, email,
address, and phone. You can also
list any custom scopes that have been configured in your
IdP.
Unaccepted scopes that your IdP rejects will cause sign-in to
fail with the error Unknown error during sign-in.
Zendesk doesn't validate any of the scopes in this field.

Select Turn on auto discovery 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.
Enter the required URLs. 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 Unknown error during sign-in. Zendesk
doesn't validate the URLs in these fields.


Issuer URL (also known as the issuer identifier): A unique
identifier for the IdP that performs user authentication and
delivers the ID tokens.

UserInfo URL: An endpoint provided by the IdP that, when
accessed with a valid access token, returns attributes about the
authenticated user.

JWKs URL: 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.

Authorization URL: When users access this URL, they are
prompted to sign in and consent to the requested scopes.

Access URL (also known as the token endpoint URL): Used to
exchange an authorization code, client ID, and client secret for an
access token.


Choose an Authentication Mode. PKCE is recommended.
Using PKCE 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.
Choose Authorization code flow 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.


Select Show button when users sign in if you let users choose how they sign in
and want this configuration to be an option they can choose from. If you
select this option, you also need name the button that will be shown
on the Zendesk sign-in page. Clear this box if your users only sign in
using an identity provider because they don't use the Zendesk sign-in
page.

Click Save. By default, enterprise SSO configurations are inactive.
You must Assign OIDC SSO
to users to activate it.






Assigning OIDC SSO to users

After creating your OIDC SSO configuration, you must activate it by assigning it to
end users, team members, or both.
To assign an SSO configuration to team members or end users

Open the Security settings for team members or end users.
In Admin Center, click
Account in the sidebar, then select Security > Team member
authentication.
In Admin Center, click
Account in the sidebar, then select Security > End user
authentication.


Select External authentication to show the authentication options.
Select the name(s) of the SSO configuration(s) you want to use. Single
sign-on might not cover all use cases, so Zendesk authentication remains
active by default.

Select how you'd like to allow users to sign in.
Let them choose allows users to sign in using any active
authentication method. See Giving users different ways to sign into
Zendesk.
Redirect to SSO only allows users to
authenticate using the primary SSO configuration. Users
don’t see additional sign-in options, even if those authentication options
are active. When you select Redirect to SSO, the Primary SSO
field appears for you to select the primary SSO configuration.

Click Save.




Managing users in Zendesk after turning on OIDC SSO

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.
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.


Turning off password notification emails from Zendesk

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.
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.
To turn off password notification emails

In Admin Center, click
People in the sidebar, then select Configuration > End users.
In the Account emails section, deselect Also send a welcome email
when a new user is created by an agent or administrator.
In Allow users to change their password, deselect this option.





Switching authentication methods

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.



Attributes supported by Zendesk

Zendesk supports standard and custom OIDC attributes.

Standard 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:
sub
email
email_verified
locale

phone number (maps to Zendesk user attribute
phone)

photo (maps to Zendesk user attribute
remote_photo_url)

preferred_username (maps to Zendesk user attribute
alias)

zoneinfo (maps to Zendesk user attribute
time_zone)



Custom 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.


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.






Attribute name
Description




name
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.


email
The user's primary email address.


email_verified
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.


organization
Name or ID of an organization to add the user to. The external_id
attribute of an organization is not supported. If the organization
doesn't exist in Zendesk, it won't be created. The user will still be
created, but they won't be added to any organization. If Allow users to belong to
multiple organizations is turned on, additional
organizations append the original organization and are considered
secondary organizations. This does not delete the existing
memberships.
If you'd like to pass multiple organization names
at the same time, use the organizations attribute instead.
Using the organizations attribute overwrites the existing list of
organizations. The organization names must be passed in a string,
separated by commas.



organization_id

The organization's external ID 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.
If Allow users to belong to
multiple organizations is turned on, additional
organizations append the original organization, and are considered
secondary organizations. This does not delete the existing
memberships.
If you'd like to pass multiple organization IDs at the same time, use
the organization_ids 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.



phone
A phone number, specified as a string.


tags
Tags to set on the user. The tags will replace any other tags that
may exist in the user's profile.


remote_photo_url
URL for a photo to set on the user profile.


locale (for agents) locale_id (for end users)

The locale in Zendesk, specified as a number. To get a list of
valid numbers, see Locales in the API docs.


zendesk_role
The user's role. Can be set to end-user , agent, or
admin. If you don't pass a zendesk_role, then Zendesk creates
the user as an end user, unless they already exist with another
role.


custom_role_id
Applicable only if the value of the role attribute above is
agent. You can get the IDs of your custom roles with the
Custom Roles API.


external_id
A user ID from your system if your users are identified by
something other than an email address or if their email addresses are
subject to change. Specified as a string.


user_field_<key>
A value for a custom user field in Zendesk Support. See Adding custom fields to users.
The &lt;key&gt; is the field key assigned to the custom user field in
Zendesk Support. Example: user_field_employee_number
where employee_number 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.