REST-Schnittstelle für OSB-Dienste

Allgemein

Die REST-Schnittstelle dient dazu, einen beliebigen OSB-Dienst automatisiert aufzurufen.

Token

Der Token ist ein “JSON Web Token” (JWT) und besteht aus 3 Teilen:

1. Header: Hier steht, mit welchem Algorithmus die Signatur verschlüsselt ist sowie die Art des Token.

2. Payload: Hier stehen alle Informationen, die bei einem CGI-Aufruf im Context stehen. Zusätzlich ist ein Timestamp enthalten, der angibt, wie lang der Token gültig ist.

3. Signatur: Die Signatur ist ein verschlüsselter Hash, der aus dem Header und dem Payload besteht. Das dazugehörige Passwort steht in der dbcgi.cfg unter Global → RestPassword.

Für weitere Informationen zu JWT kann die offizielle Webseite besucht werden: https://jwt.io

REST-Anfrage an Dienst

Jeder Dienst mit einer REST-Schnittstelle muss über eine spezielle REST-kompatible URL aufrufbar sein.

Dieser Aufruf verweist auf die entsprechende CGI.

Zudem muss im Request-Header zusätzlich der Token angegeben werden.

X-Authorization: Bearer TOKEN

Fehlerbehandlung

Wenn ein Problem entsteht, muss ein zum Vorfall passender HTTP-Code zurückgegeben werden.

So muss immer der HTTP-Code 401 zurückgegeben werden, wenn der User auf eine Ressource ohne einen gültigen Token zugreifen möchte.

Shopzugriff

Da auch Requests aus dem Shop ausgeführt werden, wird ein für den Zweck benötigter User existieren. Dieser User muss, damit nicht für jeden Dienst und Kunden Extraaufwand durch das Hinzufügen von Rechten entstehen, Adminberechtigungen haben.

Um Missbrauch vorzubeugen, muss dieses Konto spezielle Regeln befolgen:

1. Das Konto darf nur vom internen System auf die REST-Schnittstelle zugreifen.

2. Das Konto darf nur über das REST-Interface mit dem AuthentServer kommunizieren.

Damit die Regeln befolgt werden, muss eine Konfigurationsdatei rest.cfg erstellt werden, die folgende Sektion beinhaltet:

<+REST-User>
   PersNr = 0000000       # Personennummer des Users
   AllowBrowserLogin = no # yes/no, Flag ob Konto sich über Browser im OSB einloggen kann
   +IPAllowed = 123.123.123.123 # IP-Adresse über die Request erlaubt ist
   +IPAllowed = 123.123.124.*	# Möglich ein IP-Block anzugeben (* nur letzter Block möglich)
</+REST-User>