OAuth for Single Sign-On

OAuth Authentication for Single Sign-On (OAuth SSO)

Overview

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

1. Resource Owner: The user who owns the protected resource.
   
2. Client: An application or a service requesting access to the protected resource on behalf of the user.
   
3. Authorization Server: The server that generates an access token for the client.
   
4. 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 

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

OAuth Configuration for an Authorization Server

Role Required: SDAdmin

1. Go to Admin > Users & Permission > Single Sign On > OAuth SSO.
   
2. Click + New.
   
3. 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 & Permission > 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 AssetExplorer 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 AssetExplorer 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 can be synced via existing AD/LDAP sync.
	User-Defined Fields

 

1. After you configure, click Save. 
   

1. On the list view,
   
1. Enable the OAuth configuration to activate it.
   
2. To implement OAuth for AssetExplorer, enable the OAuth SSO toggle.
   

Note:

1. To enable OAuth SSO, there must be at least one active configuration.
   
2. 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.
   

List View Actions 

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

• Related Articles

• OAuth Providers

  OAuth Providers Register and track authorization servers that enable the application to retrieve user data and authorize logins. Register an Authorization Server Go to Admin > Users & Permission > OAuth Providers. Click + New. On the New OAuth ...

• OAuth SSO Troubleshooting

  Troubleshooting Error Code Description Solution 6 Authorization Code is null Ensure if ClientID, scope and Authorization URL are correct. 60 User not found (during email-based OAuth login) If the user does not exist in AssetExplorer, create a new ...

• OAuth for Mail Server

  Role Required: SDAdmin OAuth is a standard authorization protocol designed to provide secure access to protected resources by using web tokens instead of passwords. Using OAuth, resource owners can configure separate permissions for different clients ...

• FAQs on OAuth for Mail Server

  Role Required: SDAdmin Quick Links: OAuth Troubleshoot What are the supported mail servers in OAuth? We have tested OAuth authentication with Microsoft Outlook (office365) and Gmail (Gsuite). Click the respective links to learn how to generate access ...

• Configuring Okta as the Identity Provider

  Role Required: SDAdmin Log in to your Okta domain. Go to the Applications > Add Application. Click Create New App. From the displayed dialog box, choose SAML 2.0 as the sign-on method. Click Create. In the next window, provide a Name for your ...