OAuth Authentication for Single Sign-On

OAuth is a standard authorization protocol that provides access to a protected resource by using web tokens instead of passwords. With OAuth, resource owners can configure separate permissions for each client requesting access to the same resource and modify/revoke the access at any point of time.

How does OAuth work

Terminologies

Resource Owner: The user who owns the protected resource.
Client: An application or a service requesting access to the protected resource on behalf of the user.
Authorization Server: The server that generates an access token for the client.
Resource Server: The server that hosts the protected resource.

To access a protected resource, the client should obtain an authorization grant from the resource owner and pass it on to the authorization server. The authorization server validates the authorization grant and generates an access token. The client can use this token to access the protected resource hosted by the resource server.

OAuth for Single Sign-On

ServiceDesk Plus acts as the client that requests access and obtains the authorization grant from the user by using their credentials of the authorization server (for example, Microsoft Azure for Azure AD).

This authorization grant is processed through the authorization server to generate an access token. Using this access token, ServiceDesk Plus can access the Azure AD (Resource Server) to retrieve user data and authenticate the user to log in to the application.

We have tested OAuth 2.0 with Microsoft Azure and Google Workspace as authorization servers. To configure OAuth in ServiceDesk Plus, you must register the application in the authorization server.

OAuth Configuration for an Authorization Server

Role Required: SDAdmin

Go to Admin > Users & Permissions > Single Sign On > OAuth SSO.
For ESM setups, go to ESM Directory > User Management > Single Sign On > OAuth SSO. Role Required: OrgAdmin
Click + New.
On the New OAuth Configuration slideout, enter the following details:

Section	Field	Description
OAuth Provider Details	Provider Name	Register the authorization server by clicking Add New in the drop-down. If already registered under Admin > Users & Permissions > OAuth Providers, choose the required authorization from the drop-down.
	Client ID	If Add New is chosen, specify the Client ID, Authorization URL, and the Token URL generated while registering the application in the authorization server. Otherwise, these fields will be auto-populated.
	Authorization URL
	Token URL
OAuth Feature Details	Scope	Specify the scopes required to get the user's data from the Resource URL. The commonly used scopes are openid, profile, and email. openid - Required to initiate OpenID authentication request. profile - To get the user's basic profile information such as name, gender, etc. email - To get the user's email address.
	Client Secret	Specify the client secret generated while registering the application in the authorization server.
	User Property	Specify the required key in the JSON response received from the Resource URL. This key will be used to identify the user during authentication.
	Mapped Property	Choose the ServiceDesk Plus user field to which the User Property must be mapped. Use User Principal Name to map fields for users imported via AD.
	Resource URL	Specify the API endpoint the client calls to get user data after getting the access token. You can obtain the information from the authorization server's REST API documentation.
	Redirect URL	This field is auto-populated with the URL to which the user will be redirected after login. This URL cannot be edited.
Additional Fields	Default Fields	Configure field mapping to create user profile for dynamic users who log in to the application via OAuth SSO. • By using checkboxes, enable the required ServiceDesk Plus user fields under Default Fields and User-Defined fields. • For each enabled field, specify the relevant response JSON property. Note: • This configuration will not be used to update existing user profiles. • Date/Time and Multi-line fields are not supported during dynamic user addition. However, they can be synced via existing AD/LDAP sync.
Additional Fields	User-Defined Fields

After you configure, click Save.

On the list view,
- Enable the OAuth configuration to activate it.
- To implement OAuth for ServiceDesk Plus, enable the OAuth SSO toggle.

To enable OAuth SSO, there must be at least one active configuration.

When enabled, dynamic user addition will be enabled. For existing users, make sure that the login name or email address in the authorization server matches their profile information in the application. Otherwise, for every mismatch, a new user profile will be created.

If you have active AD/LDAP sync, ensure that the login name and domain of the dynamic user match their profile information during import. Otherwise, a new user will be created during the import.

List View Actions

Enable or disable Collapse the login form by default to show or hide the default login form as needed.
Use Actions next to an OAuth configuration to edit or delete it.

Log in to ServiceDesk Plus via OAuth

The login page after enabling OAuth single sign-on will be displayed as shown below:

Users can either log in by using the Local Authentication (enabled by default) or log in using OAuth by clicking the link of the required authorization server above the default login form.

Troubleshooting

Error Code	Description	Solution
6	Authorization Code is null	Ensure if ClientID, scope and Authorisation URL are correct.
60	User not found (during email-based OAuth login)	If the user does not exist in ServiceDesk Plus and dynamic user addition is disabled, create a new user manually and configure the email address. If dynamic user addition is enabled, new user will be added automatically. If the user already exists in the application, configure their email address to match the login email ID in ServiceDesk Plus.
61	Login is disabled for the user.	Enable login for the user.
62	More than one user is configured with the login email ID.	Ensure that the login email address is configured with only one user. This error is thrown if the login email ID is configured as a primary/secondary email address of another user.
52 (In ServiceDesk Plus)	Dynamic user addition is disabled.	If the user does not exist in ServiceDesk Plus, create a new user manually with the login name received in response or enable dynamic user addition from Self-Service Portal settings. If the user already exists in the application, ensure there is no mismatch in the attribute mapping.
52 (In Asset Explorer)	No such user exists in the application or the user is not a technician.	Create a new technician manually with the received property or change the requester into a technician.
3	Invalid client secret	Ensure that the secret value is correctly copied from the provider (not the Secret ID)