tia® H5 Viewer Authentication via Microsoft OpenID Connect (OIDC)

Introduction:

This article describes how to connect the tia® H5 Viewer to a Microsoft Azure application to enable authentication via a Microsoft user account. OpenID Connect is an open standard based on OAuth2 and enables identity information to be transmitted. Technical details can be found here:

https://openid.net/connect/

Prerequisites:

User account control with Office 365 in Azure
State-of-the-art browser like: Edge, Chrome, Firefox etc. IE11 is not being supported
Tomcat 9 with Java 11 or higher
- iMPORTANT: The web server must be operated with HTTPS, as this is required by Microsoft/OpenID Connect.
Access to the Azure portal and authorizations to create an "app" and provide it with authorizations. These are usually domain administrators of the companies.

Goal:

In order to further optimize access to (sensitive) customer documents in addition to the ArchiveLink secKey procedure, there is an increasing need for standard authentication procedures such as SAML2 or OpenID Connect. These session-based access mechanisms make it easier for a user to log in (once at startup) and at the same time make it more difficult for an attacker to gain unauthorized access to documents.

Flow chart:

Source: https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc

From SAP, the user opens the URL (ArchiveLink) behind which the document is hidden.
The tia® H5 Viewer checks the session to see whether the user has already logged in within a definable period of time using a session cookie. If this is not the case, a redirect to the Microsoft login page takes place. Initially, only information about the client_id (the Azure application), authority and secretKey is transferred to Azure.
Microsoft Azure responds with a login mask:

4. The user logs in with its Microsoft account. The user is also asked whether he/she wishes to remain logged in.

5. Azure validates the user input and responds with an identification token.

6. This token is sent via redirect to the stored redirect URI (and thus to the tia® H5 Viewer).

7. The tia® H5 Viewer validates this token and sets a session cookie.

8. The tia® H5 Viewer delivers the document and session cookie to the user.

Setting up the Azure application

The setup of the Azure application is described here: Register Microsoft Azure application for email delivery

Configuration of the tia® H5 Viewer

It is assumed that a basic installation of the tia® H5 Viewer already exists. Either standalone or as CSV (Content Server including tia® H5 Viewer).

The current tia® H5 Viewer release is delivered and required as a WAR. Authentication via OICD is possible from version 2.3.0 of the tia® H5 Viewer.

Important: There are two authentication bundles in the WAR by default:

KGS Keycloak Authentication (com.software.kgs.plugin.keycloakadapter)
KGS MS Auth Service (com.software.kgs.plugin.msauthneticator)

Only one may be active (depending on which one is to be used).

By default, Keycloak is "Resolved" and therefore not active.

Configuring the MS-Auth service

To be able to log in to the previously created Azure app (Create, see https://kgs-software.atlassian.net/wiki/spaces/WIKI/pages/2203680771 ), this must be configured.

This is done under "OSGi → Configuration → MsAuthConfig"

The following values must be entered: (Also: Register Microsoft Azure application for email delivery

authority: this is the baseURL + directory (tenant) ID.

For instance: https://login.microsoftonline.com/051ebb00-ace6-4a0a-a288-0dec45c505fa

ClientId: This is the application identity. Can be viewed under Azure Portal → "Overview".

Debug: Default: 4

msGraphEndpointHost: This is the Microsoft Graph API endpoint. Can be viewed under "Endpoints" (but it is always "https://graph.microsoft.com/ ")

redirectUriSignin: The address that is sent back to after a successful login. Attached parameters are retained.

For instance:

https://IP-Address:HTTPS-Port/[Applikation]/contentserver (CSV - “ContentServer incl. tia® H5 Viewer”)

https://IP-Address:HTTPS-Port /[Applikation]/viewer (V - “tia® H5 Viewer standalone” and for using the tia® H5 Viewer from within SAP)

secretKey: This is the secret that we have created under "Certificates & secrets". If this can no longer be viewed (because it was forgotten to save), a new one must be created.

Working Directory: Default. The working directory.

Configuring the tia® H5 Viewer

The "External authentication method" must be activated and "Enable Security" must be activated for the Viewer Profile.

If authentication should only take place when the email is sent (and not when the document is called up), this can be controlled using the "Authentication actions" dropdown.

The "Keycloak" tab can be ignored for direct MS authentication via OICD.

In the "Graph Mail" tab, you can configure whether you want to see the Outlook Online window as a "pop-up" or as an "embedded" window.

Popup means that a new tab opens in which only the new email draft with attachment can be seen.

Embedded means that the Outlook Online page is loaded completely (on the left you can see the list of received emails etc.).

Editing the web.xml

Finally, it is necessary to set the filters for authentication. To do this, the following section must be commented in (it is already commented out in the delivery).

Make sure that you turn the <url-pattern>/viewer/content</url-pattern> into a
<url-pattern>/viewer</url-pattern>.

<!-- Microsoft Auth Filter -->
<filter>
  <filter-name>MSAuthFilter</filter-name>
  <filter-class>com.software.kgs.filter.ms.MSAuthFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>MSAuthFilter</filter-name>
   <url-pattern>/contentserver</url-pattern>
   <url-pattern>/viewer</url-pattern>
</filter-mapping>

Likewise, <url-pattern>/viewer/content</url-pattern> of the EquinoxSessionFilter must be adapted to
<url-pattern>/viewer</url-pattern>.

<!-- Session Filter -->
	<filter>
		<filter-name>EquinoxSessionFilter</filter-name>
		<filter-class>com.software.kgs.filter.EquinoxSessionFilter</filter-class>
	</filter>
	<filter-mapping>
		<filter-name>EquinoxSessionFilter</filter-name>
		<url-pattern>/contentserver</url-pattern>
		<url-pattern>/viewer</url-pattern>
	</filter-mapping>

Restarting the web server

After restarting the Tomcat application server, everything should now be ready for use.