'gateway-ng' Service

The 'gateway-ng' service integrates identity providers for OAuth2/OIDC authentication for enaio® webclient and enaio® webclient as a desktop application.

The 'gateway-ng' service does not replace enaio® gateway; however, it must always be installed and integrated in addition to enaio® gateway for such scenarios.

The 'gateway-ng' service is an extension of the Spring Cloud Gateway. Configurations that are relevant for enaio® are described here. General gateway settings can be found in the official Spring Cloud Gateway documentation.

This documentation only applies to the 'gateway-ng' service. You can find the details on how to set up an identity provider in the corresponding documentation, for example, for Entra ID.

The following restrictions currently apply to the integration of identity providers:

• enaio® mobile is still not supported.

• User administration is not available in enaio® webclient. The featureSwitches.userManagement parameter must be disabled.

• The 'Change password' function is not available. The featureSwitches.changePassword parameter must be disabled.

• Offline mode is not available for enaio® webclient as a desktop application.

• It is not possible for the user to enter his or her password in order to confirm subscriptions, follow-ups, or the forwarding of work items, also via a script.

• Web client URL links that are copied and shared by a user who is logged in to enaio® webclient via an identity provider can only be opened by users who are also logged in via the identity provider.

• Access tokens such as the session GUID from the osrest/api/session endpoint or via the parameters from the different integration options cannot be used.

• enaio® Outlook Add-In NG uses an access token (session GUID) to communicate with enaio® webclient as a desktop application and can therefore not be used.

• OAuth2/OIDC authentication cannot be used for enaio® search NG. Only Basic Auth, NTLM, and Kerberos are supported.

The 'gateway-ng' service is not activated during installation. It must be fully configured for authentication using the servicewatcher-sw.yml file, instances: 1, prior to activation. If not, the service cannot start correctly.
If dashlets are integrated into enaio® webclient, the dashlets must be distributed via enaio® service-manager.

Configuration

The configuration is carried out in the gateway-ng-prod.yml configuration file located in the \services\service-manager\config\ directory.

The following must be specified for the configuration:

• the connections to enaio® appconnector, enaio® documentviewer, and enaio® rendition;

• the connections to identity providers;

• integration via enaio® appconnector;

• a profile for enaio® webclient as a desktop application also needs to be created.

Port 80 is the preset port for the 'gateway-ng' service. You can change the port via the servicewatcher-sw.yml file located in the \services\service-manager\config\ directory: If enaio® gateway is installed on the same server and uses port 80, the port must be changed. It can be set to any value between 1025 and 65535.

Connections to enaio® appconnector, enaio® documentviewer, and enaio® rendition

The connection data containing the default port for connections on the same server is auto-populated.

If this is not the case, you will need to edit the connection data.

spring:
  cloud:
    gateway:
      routes:
        - id: osrest_route
          uri: http://localhost:8060
          predicates:
            - Path=/osrest/**
        - id: osdocumentviewer_route
          uri: http://localhost:8070
          predicates:
            - Path=/osdocumentviewer/**
        - id: osrenditioncache_route
          uri: http://localhost:8070
          predicates:
            - Path=/osrenditioncache/**

Connections to Identity Providers

The 'gateway-ng' service works with all OIDC-compatible identity providers.

The installed gateway-ng-prod.yml configuration file contains a connection configuration for Entra ID in version 2 of the Microsoft OIDC implementation with the following parameter:

issuer-uri: https://login.microsoftonline.com/<tenant-id>/v2.0.

You require the following parameter if version 1 of the Microsoft OIDC implementation is used:

issuer-uri: https://sts.windows.net/<tenant-id>/.

Please refer to the documentation of the identity provider for other OIDC-compatible identity providers.

Replace the placeholders with your data: tenant ID, client ID, and client secret.

Example for Entra ID v2.0

  security:
    oauth2:
      resourceserver:
        jwt:
          user-name-attribute: name
          issuer-uri: https://login.microsoftonline.com/<tenant-id>/v2.0
      client:
        registration:
          azure:
            provider: azure
            client-id: <client-Id>
            client-secret: <client-Secret>
            scope: openid
        provider:
          azure:
            issuer-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri} 

Example for Keycloak:

  security:
    oauth2:
      resourceserver:
        jwt:
          user-name-attribute: preferred_username
          issuer-uri: http://<IP:Port>/realms/<tenant-id>
      client:
        registration:
          keycloak:
            provider: keycloak
            client-id: <client-id>
            authorization-grant-type: authorization_code
            scope: openid
            client-secret: <client-secret>
        provider:
          keycloak:
            issuer-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri}
            user-name-attribute: ${spring.security.oauth2.resourceserver.jwt.user-name-attribute}

enaio® User Names

The 'gateway-ng' service receives the enaio® user name from the OAuth2 token attribute 'name' and, if this attribute is not available, the 'sub' attribute is used. The reason for this is that the 'name' attribute usually only contains the user name and not the user principal name (UPN). However, if you log in using an application context, this does not have a user name. The GUID of the application, which is contained in the OAuth2 token by means of the 'sub' attribute, is then used here.

If a different attribute sequence is required, the gateway-ng-prod.yml configuration file can be extended:

gateway:
  oauth2:
    user-name-attribute: name, sub

The attributes of the comma-separated list are evaluated in order from left to right.

The possible attributes for 'user-name-attribute' are based on the configuration of the identity management.

You can obtain the available attributes via the 'DEBUG' log level of the 'com.os.services.enaio.gateway.jwt' logger. The token received from the 'gateway-ng' service is then also logged.

Please also consider the various possible login methods. It may be possible to log in via the browser with the IDM login dialog through forwarding to the desired application or resource. A direct login is also possible using a bearer token as an authorized application. In this case, there is no 'name' or 'email' but only the 'sub' attribute alongside other technical attributes.

Please also note that the OAuth2 token may contain attributes that the user can change independently in identity management. Such attributes should not be used as user names, as they represent a potential security vulnerability and a user could then pick any enaio® user name.

The enaio® user name from the OAuth2 token is validated against enaio® server and its result is cached for five minutes by default.

If you require a longer or shorter cache duration, add the following entry to the gateway-ng-prod.yml configuration file:

gateway:
  cache:
    time-to-live: 300

The value is specified in seconds. Default: 300 seconds.

Gateway Integration

The 'gateway-ng' service is integrated by way of the following parameters in the osrest.properties configuration file.

Routing Services

If you want services to be routed in the project via the 'gateway-ng' service without authentication, add further entries to the comma-separated list in the gateway-ng-prod.yml configuration file according to the same pattern:

gateway:
   endpoints:
     exposed: '/colab/**,/msteamsactions/**'

All accompanying services must always be specified in the comma-separated list. colab and msteamactions are also always required.