enaio® gateway

enaio® gateway ist die zentrale Authentifizierungskomponente für enaio® webclient und die Kommunikationsschnittstelle zwischen den Kerndiensten und Microservices.

enaio® gateway sollte in Produktivsystemen immer durch Firewalls bzw. Reverse Proxies gesichert sein. Ebenfalls möglich ist eine Ende-zu-Ende-SSL-Verschlüsselung für alle Komponenten im System.

Als Beispiel ist die Installation und Konfiguration von NGINX dokumentiert.

Konfigurationen werden in der Datei application-prod.yml aus dem Verzeichnis …\services\OS_Gateway\apps\os_gateway\config\ gespeichert. In diesem Verzeichnis dürfen sich keine weiteren YML-Dateien befinden, auch nicht in Unterverzeichnissen. enaio® gateway würde beim Starten diese Daten mergen, was zu ungewollten und fehlerhaften Verhalten führen kann.

Konfiguration

Für das Einrichten der Authentifizierungsmethode muss enaio® gateway konfiguriert werden.

Authentifizierung

Für die Authentifizierung von enaio® webclient und enaio® webclient als Desktop-Anwendung können mehrere Anmeldefilter aktiviert werden. Wenn die Anmeldung dann über einen Filter scheitert, wird versucht, die Anmeldung mit dem nächsten Filter durchzuführen. Dafür gilt folgende Reihenfolge:

• Session-Guid

• Simple
• Authentifizierung per HTTP-Header

• Formularbasiert

• NTLM

• Basic

Die Anmeldefilter aktivieren oder deaktivieren Sie in der Konfigurationsdatei application-prod.yml, die sich im Verzeichnis …\services\OS_Gateway\apps\os_gateway\config\ befindet.

Mit NTLM als Anmeldefilter wird empfohlen, für den technischen Benutzer eine Anmeldung über die alternative LoginPipe einzurichten. Je nachdem wie das Anmeldesystem konfiguriert ist, könnten anderenfalls eingerichtete Abwehrmaßnahmen (Teergruben) dafür sorgen, dass die Anmeldung des technischen Benutzers verzögert oder verhindert wird.

Bei der Authentifizierung über NTLM muss die URL-Adresse zu enaio® gateway in den Internet-Sicherheitseinstellungen der Zone 'lokales Intranet' hinzugefügt werden. Für eine automatische NTLM-Authentifizierung muss 'formularbasiert' - form - deaktiviert sein. Für Zugriffe aus einer anderen Domäne ist dann eine weitere enaio® gateway-Installation notwendig.

Wenn bei Wiedervorlagen, Abonnements, Workflows oder per Skript vom Benutzer eine Bestätigung durch das Passwort gefordert wird, dann muss als Standard auch bei aktivierter NTLM-Authentifizierung das enaio®-Passwort eingegeben werden.

Wenn die NTLM-Authentifizierung mit einer Reihenfolge der Anmeldung kombiniert wird, dann werden für die Bestätigung die dort aufgeführten Anmeldetypen in dieser Reihenfolge verwendet. Ist dort 'A' an erster Stelle eingetragen, dann kann für die Bestätigungen in enaio® client das Windows-Passwort verwendet werden.

Für enaio® webclient muss die Bestätigung spezifisch konfiguriert werden.

Für alle Clients, die NTLM unterstützen gilt:
Falls NTLM scheitert, wird Basic, auch wenn aktiviert, nicht ausgeführt.

Einstellungen für enaio® webclient

Für enaio® webclient ist folgende Ergänzung in der Konfigurationsdatei …\os_gateway\config\application-prod.yml im Abschnitt ossecurity notwendig:

ossecurity:
	exposedEndpoints: '/osweb/**'

Ebenfalls muss dort 'NTLM' deaktiviert sein:

ntlm: {
	enabled: false
}

Wenn NTLM aktiviert ist, dann wird Basic, auch wenn aktiviert, nicht ausgeführt.

Weitere enaio® gateway-Installation

Ist enaio® gateway für automatische NTLM-Authentifizierung konfiguriert, dann können Zugriffe aus einer anderen Domäne über eine weitere enaio® gateway-Installation erfolgen.

Die Installation erfolgt über das Komponenten-Setup aus dem Verzeichnis \Backend\Gateway, wenn enaio® gateway auf einem anderen Rechner installiert werden soll.

Installationen auf dem Rechner der ersten Installation können so erfolgen:

• Kopieren Sie das Verzeichnis mit dem enaio® gateway-Setup und fügen Sie es in einem Verzeichnis auf dem Rechner der ersten Installation ein.

• Öffnen Sie die Eingabeaufforderung mit administrativen Rechten und wechseln Sie in das Verzeichnis.

• Führen Sie folgenden Befehl aus: osgateway_setup.exe --registry 0

• Geben Sie ein Verzeichnis für die Installation an.

• Geben Sie einen weiteren technischen Dienstnamen, einen weiteren Dienstanzeigenamen und einen freien Port an.

• Öffnen Sie die Eingabeaufforderung mit administrativen Rechten und wechseln Sie in das bin-Verzeichnis der weiteren Installation.

• Führen Sie folgenden Befehl aus: service.bat install

Danach kann der neue enaio® gateway-Dienst konfiguriert und gestartet werden.

Aktualisierungen von enaio® gateway auf Rechnern mit mehreren Installationen können so erfolgen:

• Kopieren Sie das Verzeichnis \Backend\Gateway der Installationsdaten und fügen Sie es in einem Verzeichnis auf den Rechner der enaio® gateway-Installationen ein.

• Beenden Sie den ersten enaio® gateway-Dienst.

• Aktualisieren Sie den ersten enaio® gateway-Dienst über osgateway_setup.exe.
  Das Setup aktualisiert den ersten enaio® gateway-Dienst.

• Aktualisieren Sie weitere enaio® gateway-Installationen wie folgt:

  • Beenden Sie den weiteren enaio® gateway-Dienst, der aktualisiert werden soll.

  • Öffnen Sie die Eingabeaufforderung mit administrativen Rechten und wechseln Sie in das enaio® gateway-Setup-Verzeichnis.

  • Führen Sie folgenden Befehl aus: osgateway_setup.exe --registry 0

  • Geben Sie das Verzeichnis der weiteren enaio® gateway-Installation an.

  • Geben Sie den technischen Dienstnamen und Port genau so an, wie bei der bisherige Installation des weiteren enaio® gateway-Dienstes.
    Die Installation erstellt ein Backup-Verzeichis mit den Daten der alten Installation.

  • Kopieren Sie die Konfigurationsdateien aus dem Verzeichnis os_gateway\config des Backup-Verzeichnisses.

  • Fügen Sie die Konfigurationsdateien in das Verzeichnis os_gateway\config der neuen weiteren enaio® gateway-Installation ein.

• Starten Sie danach die enaio® gateway-Dienste neu.

Aktualisieren Sie immer alle enaio® gateway-Dienste.

Die Deinstallation erfolgt über die folgende administrative Eingabeaufforderung: sc delete <gateway-technischer_name>. Der Dienst muss vorher beendet werden.

Authentifizierung per HTTP-Header

Eine Anmeldung kann ebenfalls per HTTP-Header ermöglicht werden.

Dazu ist in der Konfigurationsdatei …\os_gateway\config\application-prod.yml im Abschnitt ossecurity folgender Eintrag notwendig:

header: {
	enabled: true,
	name: 'X-User'
}

Zusätzlich muss NTLM deaktiviert werden:

ntlm: {
	enabled: false
}

Die angegebene Benutzer wird nicht geprüft. Daher sollte dieses Anmeldeverfahren nur in Verbindung mit einem IP-Filter verwendet werden, der ausschließlich Nachrichten aus vertrauenswürdigen Quellen zulässt.

HTTP-Header - Längenbegrenzung

Als Standard ist der Request-Header auf eine Länge von 8192 Byte begrenzt. Die maximale Länge kann über die Konfigurationsdatei …\os_gateway\config\application-prod.yml geändert werden.

Im Kontext der Kerberos-Authentifizierung ist eine Längenänderung notwendig.

Beispiel: proxy.max-http-header-size: 49152

Authentifizierung mit Kerberos

Die Kerberos-Authentifizierung dient als sichere Alternative zur NTLM- Authentifizierung. So wie bei NTLM, können sich Benutzer mit einer NT-Domänensitzung an enaio® anmelden.

Ist die Kerberos-Authentifizierung aktiv, dann werden die Einstellungen der anderen Anmeldeverfahren ignoriert. Sollte es nötig sein einen NT-Benutzer von außerhalb der NT-Domäne anzumelden, dann bleibt lediglich ein Web-Formular, über das sich dieser Benutzer mit NT-Anmeldedaten anmelden kann.

Voraussetzungen

Folgende Voraussetzungen müssen erfüllt sein:

• Active Directory Synchronisierung zwischen NT-Domäne und enaio® wurde durchgeführt

• eine eingerichtete Windows-Domäne (im Beispiel 'TESTDOMAIN.ORG')

• einen Hostnamen (SPN) über den enaio® gateway erreichbar ist (im Beispiel 'enaio.testdomain.org')

• administrativer Zugriff (im Beispiel mit dem NT-Konto 'enaioadmin') auf den Domain-Controller, um die Werkzeuge 'setspn' und 'ktpass' aufzurufen
• die HTTP-Header-Längenbegrenzung ist angepasst

Domänen-Konfiguration

Folgende Schritte ausführen:

1. SPN in der Domäne registrieren
2. Folgenden Aufruf in einer administrativen Shell absetzen:

setspn -A HTTP/enaio.testdomain.org enaioadmin

3. Registrierten SPN in eine keytab-Datei exportieren:

ktpass /out c:\enaioadmin.keytab /mapuser enaioadmin@TESTDOMAIN.ORG /princ
HTTP/enaio.testdomain.org@TESTDOMAIN.ORG /ptype KRB5_NT_PRINCIPAL /crypto All /pass enaioadmin_password

• die Datei muss nicht zwingend auf dem Laufwerk 'C:' liegen und kann einen beliebigen Namen tragen
• das am Ende übergebene Passwort muss dem des NT-Kontos 'enaioadmin' entsprechen

4. enaio® gateway muss mit dem Benutzerkonto als Dienst ausgeführt werden, für den der SPN gesetzt wurde (siehe 1.)

enaio® gateway konfigurieren:

In der Konfigurationsdatei …\os_gateway\config\application-prod.yml die Anmeldeverfahren im Abschnitt ossecurity um folgenden Block erweitern:

servicePrincipal muss dem Format im Beispiel entsprechen. Das Protokoll muss als HTTP und nicht als HTTPS angegeben werden, auch wenn enaio® gateway für SSL konfiguriert ist.

keytabLocation ist der Pfad zur exportierten keytab-Datei, als Pfadtrenner müssen Slashes (/) verwendet werden.

enabled: (true/false) legt fest, ob die Kerberos-Authentifizierung aktiv ist. Wenn die Kerberos-Authentifizierung aktiv ist, dann werden die anderen Anmeldeverfahren - Session-Guid, Simple, Formularbasiert, NTLM, Basic - ignoriert.

IP-Filter

In der Konfigurationsdatei …\os_gateway\config\application-prod.yml kann angegeben werden, welche eingehenden IP-Adressen auf die Services zugreifen dürfen.

Die Standardeinstellung erlaubt Zugriff von allen IP-Adressen: trusted.ipPattern: '.*'

Die Konfiguration erfolgt analog zur Konfiguration für die Microservices.

Dashlets verteilen

Zur Verteilung von Dashlets kann ein Webanwendungsserver oder enaio® gateway verwendet werden (siehe 'Dashlets in enaio®').

Für die Verteilung mit enaio® gateway legen Sie die Seiten für Dashlets im Verzeichnis …\services\OS_Gateway\apps\os_gateway\public ab. Beachten Sie jedoch, dass Sie die Dashlets mit individuellen Namen versehen, damit keine vorhandene gleichnamige Anwendung überschrieben wird.

URL-Verschlüsselung

Administrativ können für den Aufruf von Kerndiensten und enaio® webclient URLs zur Verfügung gestellt werden. Sensible Daten in solchen URLs können verschlüsselt werden.

Benutzername und Passwort in einer URL können nur verschlüsselt werden, wenn als Anmeldefilter 'Basic' aktiviert ist.

Damit enaio® gateway Aufrufen mit verschlüsselten Datenabschnitten verarbeiten kann, muss die Konfigurationsdatei application-prod.yml angepasst werden.

Die Konfigurationsdatei befindet sich in folgendem Verzeichnis:

Die Datei enthält folgenden Abschnitt:

Zur Aktivierung setzen Sie die gewünschten Werte auf 'true':

• urlEncryption.urlAuthentication

Schaltet die Verschlüsselung ein.

• urlEncryption.osCryptoProvider.enabled

Verschlüsselung nach dem Rijndael-Verfahren. Dieses Verfahren wird auch in früheren enaio® Versionen verwendet. Ein Datenabschnitt darf maximal 128 Zeichen enthalten.

• urlEncryption.vigenereCryptoProvider.enabled

Verschlüsselung nach dem Vigenère-Verfahren - nicht kompatibel zu früheren enaio® Versionen.

Ein Datenabschnitt darf maximal 32 Zeichen enthalten. Der Schlüssel muss angegeben werden (urlEncryption.vigenereCryptoProvider.key) und muss genau 32 Zeichen lang sein.

• urlEncryption.tokenPrefix/ urlEncryption.tokenSuffix

Verschlüsselte Abschnitte müssen durch ein Präfix und ein Suffix eingeschlossen werden.

Datenabschnitte können über einen Aufruf des Programms url-cipher-tool.jar verschlüsselt werden. Das Programm erhalten Sie über das Service Portal im Bereich 'Tools'.

Der zu verschlüsselnde Datenabschnitt wird über folgenden Konsolenaufruf an das Programm übergeben. Beispiel:

java -jar url-cipher-tool.jar -o -e -i Datenabschnitt

Der verschlüsselte Datenabschnitt wird über die Konsole ausgegeben.

Für das Programm wird das Java Runtime Environment benötigt.

Verschlüsselte Datenabschnitte müssen in der URL entsprechend den angegebenen Werten für Präfix und Suffix eingeschlossen werden.

Parameter für den Aufruf von url-cipher-tool.jar

Technische Benutzer – Verschlüsselte Passwörter

Das Passwort kann in der Konfigurationsdatei …\os_gateway\config\application-prod.yml verschlüsselt angegeben werden. Es muss in einfache Anführungszeichen gesetzt werden.

Das Passwort kann über einen Aufruf des Programms url-cipher-tool.jar verschlüsselt werden (siehe oben).

Als Verschlüsselung muss das Rijndael-Verfahren verwendet werden.

CORS-Zugriffe

Cross-Origin Resource Sharing (CORS) ist ein Mechanismus, der Webbrowsern oder auch anderen Webclients Cross-Origin-Requests ermöglicht. Zugriffe dieser Art sind normalerweise durch die Same-Origin-Policy untersagt. CORS ist ein Kompromiss zugunsten größerer Flexibilität im Internet unter Berücksichtigung möglichst hoher Sicherheitsmaßnahmen.

Damit asynchrone JavaScript-Anfragen (Ajax) einer Webseite, z. B. http://kunde.beispiel.de, an enaio® gateway mit abweichender Domain, z. B. http://<gateway_server>:80, erfolgreich durchgeführt werden können, muss in der Konfigurationsdatei application-prod.yml die Eigenschaft cors.enabled: true hinzugefügt werden. Damit werden alle Webseiten-Hosts für CORS-Zugriffe autorisiert.

Die Konfigurationsdatei befindet sich in folgendem Verzeichnis:

Verbindungsanzahl

Eine hohen Auslastung von enaio® gateway kann zur Fehlermeldung 'Too many requests running' führen. Wann diese Meldung zu erwarten ist, kann nicht pauschal vorhergesagt werden, weil es davon abhängt, was genau die Benutzer in enaio® webclient tun und ob noch weitere Anwendungen auf enaio® gateway zugreifen.

enaio® gateway ist so voreingestellt, dass bis zu 50 gleichzeitig offene Verbindungen zugelassen werden. Offene Sessions für einen Zeitpunkt kann es deutlich mehr oder weniger geben, abhängig von der tatsächlichen Last.

Wenn diese Fehlermeldung auftritt, dann können Sie die Voreinstellung über die Konfigurationsdatei …\os_gateway\config\application-prod.yml ändern.

Fügen Sie am Ende folgende Zeile ein:

proxy.maxParallelConnections: Wert

Der maximale Wert sollte nicht größer als '100' sein. Tritt die Fehlermeldung weiter auf, dann kann eine weitere enaio® gateway-Installation notwendig sein.

GZIP-Kompression

Als Standard ist für enaio® gateway die GZIP-Kompression aktiviert. Die Kompression kann über die Datei application-prod.yml aus dem Installationsverzeichnis \OS_Gateway\apps\os_gateway\config\ angepasst oder deaktiviert werden.

Standard-Einstellungen:

tomcat:
  compression: 'on'
  compressableMimeTypes: 'application/json,application/xml,text/html,text/xml,text/plain'
  compressionMinSize: 128
  serviceCompression: true

Einbinden kundenspezifischer Services

Services, die nicht über enaio® service-manager installiert werden, müssen über die Konfigurationsdatei application-prod.yml aus dem Installationsverzeichnis \OS_Gateway\apps\os_gateway\config\ eingebunden werden.

enaio® coLab muss, falls installiert, ebenfalls eingebunden werden.

Beispiel:

proxy:
  services:
    endpoints:
    - endpoint: {
        name: service_1,
        url: 'https://<server>:<port>/service_1'
      }

Angegeben wird die Bezeichnung des Services und die Adresse.