OpenID Connect

An overview of all authentication options can be found in the article Overview Authentication.

Basics 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 ID of the user that is assigned to a specific Vertec user, which is used 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 in to the other system (Microsoft 365).
• Central credential management: Logins are only maintained in one place. If a Microsoft 365 login is blocked, then 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 thus all callback Url, must be accessible via the Internet 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:
   • A name (e.g. Vertec) awarded.
   • Supported account types Nur Konten in diesem Organisationsverzeichnis select.
   • Save the new app registration by clicking on Registrieren.
   • 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.
   • On Plattform hinzufügen + click and Web select.
   • The URL must match the URL under which the Vertec instance can be reached, followed by openidcallback. Example: https://meinefirma.vertec-cloud.com/openidcallback.
   • On Hinzufügen click.
4. Enter a new Redirection URI entry for mobile/Desktop:
   • On Plattform hinzufügen + click and Mobilgerät- und Desktopanwendungen select.
   • 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, additionally set the checkbox at the predefined redirection URI for MSAL.
   • On Hinzufügen click.
5. Enter a new single-page web application Outlook App record for Outlook App:
   • On Plattform hinzufügen + click and Single-Page-Webanwendung select.
   • The URL must match the URL under which the Vertec instance can be reached, followed by outlookapp. Example: https://meinefirma.vertec-cloud.com/outlookapp.
   • On Hinzufügen click.
6. Then, further down on the authentication page under Implicit approval and hybrid flows the checkbox for ID-Token put on and put on Speichern click.

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 Wherein 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 in to 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 of 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 in to the Azure portal with 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 in to Vertec.

Request new password will display the change password dialog

If the Request Request new password was enabled on an user at the time OpenID Connect was enabledactivated this may result in that editor displaying the Change password dialog on each user time Vertec is startedshow The Request new password option is no longer visible once OpenID Connect is enabledactivated but can be accessed via the Python Console on the editor with    argobject.requirenewpassword = False can be switched off.    

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:

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

Authentication via OpenID Connect with the Outlook 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.