OpenID Connect

A description of all authentication options can be found in Authentication overview.

Basics about OpenID Connect

OPEN ID Connect is an application of the OAuth standard with a focus on verifying a user identity (authentication). The implementation is based on Microsoft 365 and Entra ID (formerly Azure AD).

Vertec receives a token from Entra ID. In several steps it is ensured that Vertec and Entra ID can trust each other and that the user has authenticated with Entra ID.

The ID token contains a unique user ID that is a assigned to a specific Vertec user to log that user into Vertec. The advantages of such integration are:

• Single Sign On: A separate login to Vertec is unnecessary if the user is already logged into the other system (Microsoft 365).
• Central credential management: Logins are only maintained in one place. If a Microsoft 365 login is blocked, the login to Vertec will no longer be possible for this user.
• Extended authentication options: The user also has access to the full range of authentication methods offered by Entra ID (2FA, dongle, Windows authentication).

Prerequisite for using Vertec with OpenID Connect

The Vertec instance, and all callback URLs, must be accessible via the internet in order for authentication via OpenID Connect to work.

Registering Vertec with Entra ID

In order for the OpenID Connect integration to work with Entra ID, the Vertec installation must be registered in Entra ID. The procedure is as follows:

1. In the Azure portal, select Microsoft Entra ID (previously: Azure Active Directory).
2. Create a new registration under App registrations:
   • Give a name (e.g. Vertec).
   • Select supported account types Only accounts in this organizational directory.
   • Save the new app registration by clicking on Register.
   • On the overview page of the new registration, write down the application ID (client). This will be required in later steps.
3. Enter a new redirection URI entry for Web on the Authentication page of the app registration. The authentication page can be accessed via the navigation tree or from the overview page via the link next to redirection URIs.
   • Click on Add platform + and select Web.
   • The URL must match the URL under which the Vertec instance can be reached, followed by openidcallback. Example: https://meinefirma.vertec-cloud.com/openidcallback.
   • Click on Add.
4. Enter a new Redirection URI entry for mobile/Desktop:
   • Click on Add platform + and select Mobile device and desktop applications.
   • Enter the callback URL as the custom redirection URI:
     ms-appx-web://Microsoft.AAD.BrokerPlugin/<App-ID>
     wherein the app ID is the application ID (client) of the app registration created under item 2.
   • If the Phone App is to be used, tick the checkbox at the predefined redirection URI for MSAL.
   • Click on Add.
5. Enter a new single-page web application Outlook App record for Outlook App:
   • Click on Add platform +and select Single page web application.
   • The URL must match the URL under which the Vertec instance can be reached, followed by outlookapp. Example: https://meinefirma.vertec-cloud.com/outlookapp.
   • Click on Add.
6. On the Authentication page, under Implicit approval and hybrid flows, tick the checkbox for ID-Token and click Save.

Activating OpenID Connect in Vertec

In System Settings Authentication, the following settings are available for OpenID Connect:

• OpenID Connect active: Controls whether OpenID Connect is active. If so, a login to Vertec is only possible via OpenID Connect.
• OpenID Connect Authority: The unique URL for authentication via OpenID Connect. In the case of Entra ID, this is a URL of the form https://login.microsoftonline.com/some.tenant/v2.0 where the some.tenant part of its own Azure tenant, i.e. the domain under which the Microsoft 365 environment exists, e.g. meinefirma.onmicrosoft.com.
• OpenID Connect Client ID: The client ID under which Vertec was registered with the identity provider.
• OpenID Connect Redirect URL: The Web Callback URL registered with Entra ID with Vertec.

Note: For existing installations, it is possible that users can also log into Vertec without a password. For authentication via OpenID Connect, a Vertec password is not required. In the event that OpenID Connect should be turned off, Vertec can be reached without a password. We therefore recommend turning off the option Login to Vertec without password.

Mapping Entra Object ID to Vertec users

Once OpenID Connect is activated in Vertec, the User field appears on the user details page, instead of the traditional password fields:

The object ID of the user from Entra ID must be assigned here. This can be found as follows:

1. Log into the Azure Portal as an administrator.
2. Microsoft Entra ID (formerly Azure Active Directory) > Select User.
3. Open the desired user in the detail view:

   

4. Copy the object ID with the button and paste it into the field OpenID Connect ID in Vertec.

The corresponding member on the user is called Oidcid.

Please note that the OpenID Connect ID in Vertec must be unique, so the same Entra ID cannot be used for multiple users.

Note: Once OpenID Connect is activated, users without OpenID Connect ID will no longer be able to log into Vertec.

Request new password will display the change password dialog

If Request new password was enabled on a user at the time OpenID Connect was activated, it may happen that the Change password dialog is shown for this user every time Vertec is started. The Request new password option is no longer visible once OpenID Connect is activated, but can be switched off via the Python Console on the user with    argobject.requirenewpassword = False. 

Login to Vertec via OpenID Connect

After authentication via OpenID Connect is activated, the Cloud Server must be restarted, as changes to the system settings in the Cloud App and the Web App will only take effect after a restart of the Cloud Server. Cloud Suite customers can trigger the Restart via customer portal.

After that, when Vertec is started, instead of the traditional login dialog, a Microsoft login dialog appears, in which the user (if he has an OpenID Connect ID in Vertec) can authenticate via OpenID Connect

At the very first login, the user rights for Vertec are also requested:

Further registrations to Vertec then take place directly via OpenID Connect without a login request.

Authentication via OpenID Connect with the Outlook App

If authentication via OpenID Connect is activated in the Vertec System Settings, a Microsoft login dialog appears when using the Outlook App instead of the usual login dialog, where the user can authenticate via OpenID Connect.

After the Outlook App Session Outlook App Session Timeout expires, the re-authentication takes place in the background without a login dialog being shown. However, if the user logs out of the Outlook App, an OpenID Connect login dialog appears again.

Authentication via OpenID Connect with the Phone App

If authentication via OpenID Connect is activated in the Vertec System Settings, a Microsoft login dialog appears when using the Phone App, instead of the usual login dialog, where the user can authenticate via OpenID Connect.

After the Phone App Session has expired (Phone App Session Timeout), the re-authentication takes place in the background without a login dialog being shown. However, if the user logs out of the Phone App, an OpenID Connect login dialog appears again.