'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.

Configuration values such as login name and password can be specified in the encrypted configuration file.

The following must be specified for the configuration:

• 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 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:
          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} 

HTTPS connections are required for Entra ID.

Example for Keycloak:

  security:
    oauth2:
      resourceserver:
        jwt:
          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}

enaio® Login Names

The 'gateway-ng' service receives the enaio® login 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 login name and not the user principal name (UPN). However, if you log in using an application context, this does not have a login 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 login names, as they represent a potential security vulnerability and a user could then pick any enaio® login name.

The enaio® login 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.

enaio® appconnector Gateway Integration

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

Project-specific Services Routing

If project-specific service routes are specified in the gateway-ng-prod.yml configuration file, you must also create 'blacklist' entries for these services:

endpoints:
  blacklist: 'service'

You specify several services using a comma-separated list.

Project-specific Routing Configuration

If routes require specific configurations, such as filters, these can be specified in the gateway-ng-prod.yml configuration file.

Example of the 'applet' service:

- id: applet
  uri: lb://APPLET
  predicates:
    - Path=/applet/**
  filters:
    - RewritePath=/applet/?(?<segment>.*), /$\{segment}
    - RewriteResponseHeader=X-Frame-Options, , SAMEORIGIN, allow-from none

A filter for modifying a response header is added to the 'applet' service here.

The 'applet' service must also be entered in the blacklist in order to overwrite the preconfiguration, as routing is preconfigured for the 'applet' service by default.

Services Routing Without Authentication

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 msteamsactions are also required, if integrated.

Embedding in iFrames of Different Hosts

Embedding the URL from the 'gateway-ng' service in iFrames hosted under a different server is prevented by the 'X-Frame-Options' response header by default.

The header needs to be modified using the gateway-ng-prod.yml configuration file in order to enable embedding:

spring:
  cloud:
    gateway:
      default-filters:
        - RewriteResponseHeader=X-Frame-Options, , ^.*$, ALLOW-FROM https://<host>/ 

Enter the URL of the parent page in which the iFrame is to be imported as the value for ALLOW-FROM. Multiple entries are separated by a comma.

Details can be found on the following page: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options

The cookie from the 'gateway-ng' service is only valid for your own host by default. To change this, the following must be added to the gateway-ng-prod.yml configuration file:

server:
  reactive.session.cookie:
    same-site: 'NONE'

The 'gateway-ng' service needs to be restarted after changes have been made to the configuration file.