OpenID Connect

Authenticate users through an identity provider based on OpenID.

Plugin Configuration

To enable this plugin, you need to:

Go to the Integrations / Plugins page.
Select the Security category.
Locate the OpenID Connect card.
Click on the card switch to activate the plugin.
Configure the plugin properties and save.

Here is the list of all the properties that can be used in the plugin configuration.

	PROPERTIES
Identity Provider Name	The name of the identity provider supporting the OpenID Connect protocol. Type: STRING \| Mandatory
Grant Type	Define the way the client interacts with the OpenID server. Type: SELECTION \| Mandatory \| Default: AUTHORIZATION_CODE
Authorization URL	The endpoint of the authorization server, used to get the authorization code. Type: STRING \| Mandatory
Access Token URL	The endpoint of the authentication server that is used to exchange the authorization code for an access token, and if needed, refresh it. Type: STRING \| Mandatory
Client ID	The client identifier provided during the registration process in the target identity provider. Type: STRING \| Mandatory
Client Secret	The client secret provided during the registration process in the target identity provider. Type: PASSWORD \| Mandatory
Scope	The scope of the access request. It can be a list of space-delimited values (e.g., openid email profile). Type: STRING \| Optional
Client Authentication	The method that client uses to authenticate to the Authorization Server when calling the Token Endpoint Type: SELECTION \| Mandatory \| Default: CLIENT_SECRET_POST
Logout URL	The URL to automatically navigate when the user logs out of the application, in order to trigger the logout also from the remote identity provider system. Type: STRING \| Optional
User Info URL	The endpoint URL called to obtain the details of the authenticated user. Type: STRING \| Optional
User Property Mapping	The mapping between the user details field names and the Servitly user properties. The mapped properties will be automatically updated on each user login. Type: KEY_VALUE \| Optional
Create Missing Users	The flag that indicates whether, during the first login, missing users should be created based on the presence of the user property mapping 'customerCode' or 'partnerCode'. For more details, refer to the paragraph Automatic User Creation. Type: CHECKBOX \| Optional
Login Button Label	The label to display in the application login page (e.g., Login with Google). Type: STRING \| Optional
Login Button CSS Class	The space-delimited list of classes applied to the login button (e.g., bg-blue text-bold). Type: STRING \| Optional

Google OpenID Connect configuration

Grant Type	Authorization Code
Auth URL	https://accounts.google.com/o/oauth2/v2/auth
Access Token URL	https://oauth2.googleapis.com/token
Client Id and Secret	You can configure the Google OAuth 2.0 Client here. https://console.cloud.google.com/apis/credentials
Scope	openid email profile
Client Authentication	Send client credentials in the body
User Info URL	https://oauth2.googleapis.com/tokeninfo
Login Button Label	Login with Google
Login Button CSS Class	bg-blue mt-4

For more details about how to configure the Google OpenID authentication, refer to this guide.
The OpenID requires a redirect URL to return to once the user has logged in to the external authentication system.

https://<TENANT_NAME>.<DOMAIN_NAME>/open-id

In the case you are using the default Servitly Mobile App, you also need to register a redirect URL having the additional appScheme parameter.

<BASE_REDIRECT_URL>?appScheme=servitly

This is needed by a Google security policy, which does not allow invoking auth URLs directly from a mobile app. In order to use OpenID login from a Mobile App, the authentication flow passes through the system browser, and finally, the user is redirected to the installed mobile app responding to a certain scheme. The scheme generally corresponds to the name of the tenant, but for the default Servitly App is just servitly.

Login Experience

With the plugin enabled and configured, the login page is enriched with a new login button (eg., Login with Google).

When the user, who needs to log in, presses the button, it is redirected to the OpenID authentication flow page, and when authenticated, it is redirected back to the application.
Once the callback URL is called during the authentication flow, the system searches for a user having the same email, and if found, the user is automatically authorized to access it.
Note that, when using the Servitly mobile application, for security reasons, the authentication flow passes through the operating system browser.

Automatic User Creation

By selecting the Create missing users option, when a user logs in via OpenID and is not yet registered in the DPS, they are automatically created.
To create the user under the right place (Customer or Partner), it is mandatory to provide the mapping of the parent entity code property.

Therefore, with reference to the image above, the User Information (User Info URL) response must contain one of the fields customer_code or partner_code.
If the code field is missing or there is no customer or partner with the same code, the user creation and, therefore, the login will not be successful.

In addition to connecting the user to the right entity, you can also define the mapping to other user properties. When the DPS user is created, this mapping is used to propagate other information from the User Information response (User Information URL).
Furthermore, these properties are kept up-to-date with each subsequent login.

Please note that users in the organization cannot be created automatically upon login.

Automatic Login

In case you are integrating the DPS in a legacy app with its own SSO, when a user needs to enter the DPS application without performing an explicit login, you can redirect them to a special URL that triggers the authentication flow.

https://acme.servitly-sandbox.com/open-id-start-flow

By navigating this URL, the user experience is the same as if the user clicks on the Login with.... button.
In case the user is already logged in on the external identity provider, the user is automatically authenticated and redirected to the DPS application home page.