Service 'gateway-ng'

Der Service 'gateway-ng' bindet Identity Provider für die Authentifizierungsmethode OAuth2/ OIDC für enaio® webclient und enaio® webclient als Desktop-Anwendung ein.

Der Service 'gateway-ng' ersetzt enaio® gateway nicht sondern muss für solche Szenarien immer zusätzlich zu enaio® gateway installiert und eingebunden werden.

Für die Einbindung gelten zurzeit folgende Einschränkungen:

• enaio® mobile wird noch nicht unterstützt.

• In enaio® webclient steht die Benutzerverwaltung nicht zur Verfügung. Der Parameter featureSwitches.userManagement muss deaktiviert werden.

• Die Funktion 'Passwort ändern' steht nicht zur Verfügung. Der Parameter featureSwitches.changePassword muss deaktiviert werden.

• Der Offline-Modus für enaio® webclient als Desktop-Anwendung steht nicht zur Verfügung.

• Bestätigungen durch die Eingabe des Passworts für Abonnements, Wiedervorlagen, das Weiterleiten von Arbeitsschritten und per Skript sind nicht möglich.

• Kopierte Webclient-URL-Links, die ein Benutzer, der über einen Identity Provider in enaio® webclient angemeldet ist, teilt, können nur von Benutzern geöffnet werden, die ebenfalls über den Identity Provider angemeldet sind.

• Access Token wie die Session-GUID vom Endpunkt osrest/api/session oder über die Parameter aus den verschiedenen Integrationsmöglichkeiten können nicht verwendet werden.

• enaio® Outlook Add-In NG verwendet Access Token (Session-GUID) für die Kommunikation mit enaio® webclient als Desktop-Anwendung und kann deshalb nicht verwendet werden.

• Für enaio® search NG kann die Authentifizierungsmethode OAuth2/ OIDC nicht verwendet werden. Möglich sind nur Basic Auth, NTLM und Kerberos.

Der Service 'gateway-ng' wird durch die Installation nicht aktiviert. Er muss vor der Aktivierung über die Datei servicewatcher-sw.yml, instances: 1, vollständig für die Authentifizierung konfiguriert werden, sonst kann der Service nicht richtig starten.
Wenn Dashlets in enaio® webclient eingebunden sind, dann müssen die Dashlets über enaio® service-manager verteilt werden.

Konfiguration

Die Konfiguration erfolgt über die Konfigurationsdatei gateway-ng-prod.yml aus dem Verzeichnis \services\service-manager\config\.

Für die Konfiguration müssen folgende Daten angegeben werden:

• die Verbindungen zu enaio® appconnector, enaio® documentviewer und enaio® rendition,

• die Verbindungen zu Identity Providern,

• die Einbindung über enaio® appconnector,

• für enaio® webclient als Desktop-Anwendung erstellen Sie ein Profil.

Als Port ist 80 für den Service 'gateway-ng' vorkonfiguriert. Der Port kann über die Datei servicewatcher-sw.yml aus dem Verzeichnis \services\service-manager\config\ geändert werden. Wenn enaio® gateway auf dem gleichen Server installiert ist und den Port 80 belegt, dann muss der Port geändert werden. Er kann auf einen beliebigen Wert zwischen 1025 und 65535 eingestellt werden.

Verbindungen zu enaio® appconnector, enaio® documentviewer und enaio® rendition

Voreingetragen sind die Verbindungsdaten mit Standardport für Verbindungen auf dem gleichen Server.

Ist das nicht der Fall, dann müssen die Verbindungsdaten angepasst werden.

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/**

Verbindungen zu Identity Providern

Voreingetragen ist eine Verbindungskonfiguration für Azure / Entra ID mit Platzhaltern.

Die Platzhalter ersetzten Sie durch Ihre Daten: Tenant-ID, Client-ID und Client-Secret.

Beispiel für Azure / Entra ID

  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} 

Beispiel für 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®-Benutzernamen

Der Services 'gateway-ng' erhält den enaio®-Benutzernamen aus dem oAuth2-Token-Attribut 'name' und, falls dieses Attribut nicht vorhanden ist, wird auf das Attribute 'sub' zurückgegriffen. Dies hat den Hintergrund, dass das Attribute 'name' in der Regel nur den Benutzernamen und nicht den User Principal Name (UPN) enthält. Wird sich hingegen mittels eines Application-Kontextes angemeldet, so besitzt dieser keinen Benutzernamen. Hier wird dann auf die Guid der Application zurückgegriffen, die mittels des Attributes 'sub' im oAuth2-Token enthalten ist.

Wenn eine andere Attributreihenfolge benötigt wird, dann kann die Konfigurationsdatei gateway-ng-prod.yml erweitert werden:

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

Die Attribute der kommaseparierten Liste werden in der Reihenfolge von links nach rechts ausgewertet.

Die möglichen Attribute für 'user-name-attribute' basieren auf der Konfiguration des Identitätsmanagements.

Sie können die zur Verfügung stehenden Attribute über das Log-Level 'DEBUG' des Loggers 'com.os.services.enaio.gateway.jwt' beziehen. Dann wird das vom Services 'gateway-ng' erhaltene Token mitgeloggt.

Bitte bedenken Sie ebenfalls die verschiedenen möglichen Anmeldeverfahren. Anmeldungen über den Browser mit Login-Dialog des IDM mit einer Weiterleitung auf die gewünschte Applikation bzw. Ressource können möglich sein. Anmeldungen können auch direkt mit einem Bearer-Token als autorisierte Applikation möglich sein. Im diesem Fall existiert kein 'name' oder 'email' sondern nur das Attribute 'sub' neben anderen technischen Attributen.

Beachten Sie weiterhin, dass im oAuth2-Token Attribute vorhanden sein können, die der Benutzer eigenständig im Identitätsmanagement ändern kann. Solche Attribute sollten nicht als Benutzernamen herangezogen werden, da sie eine potenzielle Sicherheitslücke darstellen und ein Anwender dann jeglichen enaio®-Benutzernamen annehmen könnte.

Gateway-Einbindung

Die Einbindung des Services 'gateway-ng' erfolgt über folgende Parameter der Konfigurationsdatei osrest.properties.

Services-Routing

Falls im Projekt Dienste über den Service 'gateway-ng' ohne Authentifizierung geroutet werden sollen, dann erweitern Sie in der Konfigurationsdatei gateway-ng-prod.yml die kommaseparierten Liste um weitere Einträge nach gleichem Muster:

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

Genannt werden müssen in der kommaseparierten Liste immer alle entsprechenden Dienste. Notwendig sind immer ebenfalls colab und msteamsactions.