Allgemeines

Die Kommunikation ist sitzungsbezogen, d. h. es ist ein Login notwendig, der eine Sitzungs-ID erzeugt. Diese Sitzungs-ID muss bei allen folgenden Requests mitgesendet werden. Innerhalb einer Anmeldung können beliebig viele oxaion-Calls durchgeführt werden.
Nach Beendigung der Kommunikation muss die Sitzungs-ID wieder abgemeldet werden.
Die HTTP-Schnittstelle besitzt einen konfigurierbaren Sitzungs-Timeout. Ist eine Sitzung längere Zeit inaktiv, wird die Sitzung automatisch abgemeldet. Standardmäßig liegt der Timeout bei 15 Minuten
Die Schnittstelle ist über das Standard-HTTP-Protokoll aufrufbar. Die Parameter werden als HTTP-Parameter übergeben. Die Rückgabe erfolgt in XML- oder JSON-Form im HTTP-Body.
Als Zeichensatz wird UTF-8 verwendet.
Auf Wunsch kann die Schnittstelle auch per HTTPS betrieben werden (SSL-Verschlüsselung).

Installation

Die oxaion HTTP-Schnittstelle kann auf allen Systemen installiert werden, die den Hard- und Softwareanforderungen eines oxaion JET Servers entsprechen.

Aktuelle Vorgehensweise

Die Installation erfolgt als weiterer Dienst durch das Installations-Skript:
Aufruf "./install-oxaion.sh installAdditionalServer" , empfohlener Servername SRV-HTTP01, abweichender Server-Port 11290 führt zum Jetty-Port 11298 - dies ist der Port über den die API von externen Diensten angesprochen wird. Weitere Details siehe Installieren weiterer Server (ILM/ERW/HTTP).
Da dies ein eigenständiger Appserver ist, müssen dafür Jobs eingerichtet werden, aber nicht mehr der hosts-Eintrag angepasst werden, Anpassungsmöglichkeiten unten.

Klassische Herangehensweise

Alternativ erfolgt die Installation klassisch durch Entpacken der http_server.zip-Datei unterhalb des PRODUCTION-Ordners.

Für die erfolgreiche Verwendung der HTTP-Schnittstelle, muss in der server.xml der HTTP-Schnittstelle ("SRV-HTTP\temp\conf\server.xml") der hosts-Eintrag angepasst werden.

<hosts>
<host address="localhost" encoding="UTF-8" name="OXAION" port="11200" timeout="0" type="RMI"/>
</hosts>

Der hier einzutragende Port entspricht dem RMI-Port der server.xml des SRV01 (SRV01\temp\conf\server.xml).

Wichtig: Port, Type und Name sind zu prüfen.

Dabei sollte der Port der Angabe des Portservers (com.oxaion.jet.server.rmi.RMIRegistry unter dem App-Server) entsprechen.

Bei Windows-Betriebssystemen kann ein automatisch startender Windows-Dienst eingerichtet werden. Dazu ist die bat-Datei "installService.bat" unter "bin\service\bat\" auszuführen.

Benutzer anlegen

Für die Nutzung der HTTP-Schnittstelle muss ein oxaion-Benutzer mit entsprechenden Berechtigungen vorhanden sein:

• MN10640 – Verwaltung von Benutzerstammdaten und Berechtigungen
• OP10100 – Festlegung und Änderung des Benutzerpasswortes

Dem Benutzer müssen die Berechtigungen für alle Programme erteilt werden, die über die HTTP-Schnittstelle aufgerufen werden sollen.

Hinweise zur Konfiguration

Hostname der oxaion-Umgebung

Der im Parameter host des connect-Aufrufs angegebene Name der oxaion-Umgebung (z. B. PRODUCTION, STAGING oder DEVELOP) sollte keine Leerzeichen enthalten. Falls der konfigurierte Umgebungsname Leerzeichen enthält, werden diese von Browsern automatisch als %20 kodiert, was zu Fehlern bei der Anmeldung führen kann. Leerzeichen im Umgebungsnamen sollten daher vermieden werden.

Anpassungen

Für beide Varianten gilt: Optional kann der Port geändert werden, falls die Schnittstelle nicht auf Port 11290/11298 gestartet werden soll.

Konfiguration der SSL-Verschlüsselung

Eigentlich wird empfohlen, diesen Sicherheitslayer außerhalb der oxaion-Services über WAF oder Reverseproxy abzuwickeln, aber SSL wird auch nativ unterstützt.

Über die Option <option name="ssl" value="true|false" /> in der server.xml kann die SSL-Verschlüsselung aktiviert/deaktiviert werden.

<listen active="true" class="com.oxaion.jet.server.jetty.HTTPServer" name="HTTP-Jetty" port="11298" required="false">
<option name="ssl" value="false" />
<option name="password" value="oxaion" />
oder
<option name="encryptedPassword" value="GJKL7890H1" />
<option name="keystore" value="./../../data/certs/ssl-http-tunnel.keystore" />
</listen>

Um statt dem "password" ein "encryptedPassword" für den SSL-Keystore anzugeben, kann das Passwort wie folgt verschlüsselt werden:

Workaround Encrypted

Bei der Nutzung der Option encryptedPassword muss trotzdem password verwendet werden, der value ist dagegen egal, kann also als value="" gesetzt sein.

Vereinfachung

Ein vorhandener PFX-Keystore ist auch direkt ohne Konvertierung einbindbar.

Selbst signiertes Zertifikat

Die SSL-Verschlüsselung erfordert einen Java-Keystore. Bei Windows-Betriebssystemen kann dieser mit folgenden beiden Befehlen erzeugt werden kann:

keytool -genkey –keyalg RSA -keystore ssl-http-tunnel.keystore -alias ihreFirma
keytool -selfcert -alias ihreFirma -keystore ssl-http-tunnel.keystore

Anschließend muss die Datei ssl-http-tunnel.keystore in das PRODUCTION\data\certs-Verzeichnis oder certs-Verzeichnis der HTTP-Schnittstelle (dann aber keystore-Pfad anpassen!) kopiert werden.

Öffentlich gültiges Zertifikat

Anstatt eines selbst signierten Zertifikats, kann auch ein Zertifikat von einer öffentlichen Zertifizierungsstelle importiert werden.

keytool -genkey –keyalg RSA -keystore oxaionssl.jks -alias ihreFirma
keytool -importkeystore -srckeystore \_.oxaion.de\_private\_key.pfx -srcstoretype pkcs12 -destkeystore oxaionssl.jks -deststoretype JKS

Wichtig: Das Passwort für den neuen Keystore muss dem Passwort für das Zertifikat entsprechen (das Passwort für den PFX-Keystore).

SSL-Debugging

Manchmal kann es nützlich sein, die SSL-Verschlüsselung temporär zu debuggen. (Wenn z.B. ein neues Zertifikat nicht wie gewünscht funktioniert.)
Hierfür können folgende Parameter in der wrapper.conf des Service verwendet werden.

wrapper.console.visible=true
wrapper.java.additional.# = -Dorg.eclipse.jetty.LEVEL=DEBUG
wrapper.java.additional.# = -Djavax.net.debug=ssl,handshake,data

Zentralisierung

Bei infinite ist es Gepflogenheit die Zertifikate nicht pro Dienst, sondern zentral je Umgebung, also unter PRODUCTION\data\certs abzulegen.