enaio® gateway

Gültig für: enaio® Version 10.10

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. HTTPS und TSL-Konfiguation sind dann nicht notwendig.

Als Beispiel ist die Installation und Konfiguration von NGINX dokumentiert.

Konfiguration

Für das Einrichten der verschlüsselten Datenübertragung (HTTPS) und der Authentifizierungsmethode muss enaio® gateway konfiguriert werden.

HTTPS

Die Datenübertragung per HTTPS richten Sie wie folgt ein:

  1. Erstellen Sie einen Key und (Selbst-)Zertifikat im Keystore vom Anwendungsserver. Eine Anleitung finden Sie unter:

http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html

  1. Setzen Sie den Standardport des Anwendungsservers auf den HTTPS-Standardport.

Dazu starten Sie den Anwendungsmanager enaio blue gatewayw.exe im Verzeichnis …\services\OS_Gateway\bin und setzen auf der Registerkarte Startup den Parameter –server.port=443.

enaio_pic

  1. Aktivieren Sie die Datenübertragung per HTTPS in der Konfigurationsdatei application-prod.yml, die sich im Verzeichnis …\services\OS_Gateway\apps\os_gateway\config\ befindet. Sie kann mit jedem beliebigen Editor bearbeitet werden.
  1. Fügen Sie folgenden Abschnitt hinzu:
  2. https: {
    enabled: true,
    keyAlias: 'enaio',
    keystorePass: 'optimal',
    keystoreFile: 'c:/path/certificate.jks',
    keystoreType: JKS,
    sslProtocol: 'TLS',
    sslEnabledProtocols: 'TLSv1.2,TLSv1.3'
    }

    Die Parameter haben folgende Bedeutung:

    Parameter

    Beschreibung

    enabled

    Aktiviert die Datenübertragung per HTTPS.

    keyAlias:

    Name für den Keystore

    keystorePass

    Passwort für den Keystore-Benutzer

    keystoreFile

    Verzeichnis, in dem sich die Keystore-Datei befindet.

    Werte mit Sonderzeichen benötigen einfache Anführungszeichen.

  1. Speichern und schließen Sie die Datei.

Die Datenübertragung per HTTPS ist eingerichtet.

Wenn Sie ein selbst signiertes SSL-Zertifikat in enaio® gateway verwenden, dann müssen Sie auf allen Clients dessen Root-CA Zertifikat in die vertrauenswürdigen Stammzertifizierungsstellen importieren. Ansonsten wird das Zertifikat von allen Clients als nicht vertrauenswürdig erachtet und ein Verbindungsaufbau, beispielsweise aus enaio® webclient, schlägt fehl. Selbst signierte Zertifikate sind in der Regel für Produktivsysteme nicht empfohlen.

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
  • 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 in enaio® webclient eine Bestätigung durch das Passwort gefordert wird, dann muss bei aktivierter NTLM-Authentifizierung der enaio®-Benutzername und das enaio®-Passwort eingegeben werden oder die Anmeldung 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 'formularbasiert' - form - deaktiviert sein:

form: {
	enabled: false
	urls:''
	}

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 den Rechner ein.

  • Öffnen Sie die Eingabeaufforderung als Administrator 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 Dienstnamen, einen weiteren Dienstanzeigenamen und einen freien Port an.

  • Öffnen Sie die Eingabeaufforderung als Administrator 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-Hotfix der Installationsdaten und fügen Sie es in einem Verzeichnis auf den Rechner ein.

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

  • Öffnen Sie die Eingabeaufforderung als Administrator und wechseln Sie in das Hotfix-Verzeichnis.

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

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

  • Starten Sie den enaio® gateway-Dienst neu.

Aktualisieren Sie immer alle enaio® gateway-Dienste.

Die Deinstallation erfolgt über die folgende administrative Eingabeaufforderung: sc delete <gateway-name>. Der Diensts 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

  1. 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
  1. 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:

ossecurity:

  kerberos: {

    enabled: true,

    servicePrincipal: 'HTTP/beispiel.testdomain.org@TESTDOMAIN.ORG',

    keytabLocation: 'c:/enaioadmin.keytab'

  }

 

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:

\services\OS_Gateway\apps\os_gateway\config

Die Datei enthält folgenden Abschnitt:

urlEncryption.osCryptoProvider.enabled: false

urlEncryption.vigenereCryptoProvider.enabled: false

urlEncryption.vigenereCryptoProvider.key: '~secret_~secret_~secret_~secret_'

urlEncryption.tokenPrefix: '(('

urlEncryption.tokenSuffix: '))'

urlEncryption.urlAuthentication: false

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 der angegebenen Werte für Präfix und Suffix eingeschlossen werden.

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

Parameter

Funktion

-d (--decrypt)

Modus für Entschlüsselung

-e (--encrypt)

Modus für Verschlüsselung

-o (--oscrypto)

Rijndael-Verfahren mit festem Schlüssel

-v (--vigenere)

Vigenère-Verfahren

-k <arg> (--key<arg>)

Anzuwendender Schlüssel (nur mit -v)

-i <arg> (--input <arg>)

Zu verarbeitender Datenabschnitt

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:

\services\OS_Gateway\apps\os_gateway\config

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ächlich 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