Jeglicher Zugriff auf die Daten der ABES/Objects-OData-Schnittstelle mit Ausnahme des Zugriffs auf die Metadaten erfordert eine gültige Authentifizierung gegenüber dem Web-Service.

Für die Server-Anmeldung und ggf. auch die explizite Abmeldung stehen verschiedene Funktionen bereit, die in den nächsten Abschnitten beschrieben werden.

1. Anforderung eines Authentifizierungs-Tokens (Anmeldung)
2. Benutzung des Authentifizierungs-Tokens
3. Überprüfung eines Authentifizierungs-Tokens
4. Explizite Abmeldung vom Web-Service

1. Anforderung eines Authentifizierungs-Tokens (Anmeldung)

Die Anmeldung beim ABES/Objects-OData-Service erfolgt mittels eines technischen Users mit Hilfe der Funktion “ServerLogin”.
Bei Aufruf der Funktion werden Nutzername und Passwort in der Form name:pwd, Base64 codiert übergeben.
Zusätzlich wird ein Schlüssel zur Identifikation der Client-Anwendung (“ApiKey”) benötigt. Dieser wird in AbesObjects angelegt und verwaltet.
Die Übergabe beider Angaben erfolgt über den Header des Requests.

Es ist unbedingt darauf zu achten, dass Funktionsname und Parameterbezeichnung case-sensitiv angegeben werden.

Rückgabe/Response

Im Fall, das der Anmeldevorgang erfolgreich durchgeführt werden konnte, wird zurückgegeben

Der Wert aus dem Feld “value” stellt das Authentifizierungs-Token dar, das in allen nachfolgenden Abfragen verwendet werden muss.

Die anderen Elemente geben Auskunft über die Versionen der verwendeten Odata-Schnittstelle, des Backend-Framworks und der aktiven Datenbank.
Außerdem wird die für das Backend-Framework benötigte Datenbank-Version ausgegeben.

Für den Fall, dass ein Fehler aufgetreten ist, wird ein Fehler Objekt zurückgegeben. Im folgenden Beispiel wurde ein falsches Passwort verwendet:

2. Benutzung des Authentifizierungs-Tokens

Das im vorherigen Abschnitt erstellte Authentifizierungs-Token muss clientseitig gespeichert werden, da es bei allen nachfolgenden Abfragen immer wieder im Http-Request angegeben werden muss. Bei weiteren Requests muss das Token im Header mit übergeben werden.

Nach jeder Abfrage ist der Http-Statuscode zu prüfen, da die Gültigkeitsdauer der Authentifizierungs-Token durch den OData-Service beschränkt werden kann (sessionTimeoutMinutes, siehe “Hinweise für Backend-Entwickler”). Auch unabhängig davon kann ein bestehendes Authentifizierungs-Token ungültig werden, falls die OData-Schnittstelle auf Server-Seite neu gestartet werden (muss) – bspw. aufgrund von Wartungsarbeiten. Ein neues Token muss in einem solchen Fall neu angefordert werden.

3. Überprüfung eines Authentifizierungs-Tokens

Für eine schnelle und einfache Überprüfung der Gültigkeit eines vorliegenden Token steht eine eigene Funktion “CheckAuthentication” zur Verfügung.
Dabei muss das (zu prüfende) Authentifizierungs-Token in einer der vorstehend beschriebenen Formen übergeben werden.

Falls das genutzte Token nicht (mehr) gültg ist, erhält man in der Response den Statuscode 401 (Unauthorized) – andernfalls 200 (Ok).

4. Explizite Abmeldung vom Web-Service

Um die Serveranmeldung explizit ungültig zu machen, kann die Funktion “ServerLogout” verwendet werden. Dies ist zu empfehlen, wenn eine Clientanwendung beendet wird.

Die Funktion “ServerLogout” erwartet keine Parameter.

Auch für die Abmeldung muss ein gültiges Authentifizierungs-Token in einer der beschriebenen Formen übergeben werden.