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

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

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: Passwörter verschlüsseln

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