06 Authentifizierung beim OData-Service

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 wurden zwei Funktionen bereitgestellt, 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.
Zur Anmeldung wird die Funktion “ServerLogin” mit Übergabe von Nutzername und Passwort benutzt.
Die Übergabe kann als Parameter über die Url oder im Header des Requests erfolgen.

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

Direkt mittels Url

Über den Request Header

Username und Passwort werden hier im Header in der Form name:pwd, Base64 codiert übergeben.
Insbesondere bei Verwendung von SSL/HTTPS ist diese Methode der Anmeldung aus Sicherheitsgründen gegenüber der vorzuziehen.

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.
Es wird empfohlen, das Token als Request-Header anzugeben.

Eine andere Möglichkeit wäre, das Token als Query-Parameter an die Abfrage anzuhängen.

Hier sind Beispiele für beide Formen der Authentifizierung:

Angabe als Request-Header:

Angabe als Query-Parameter:

Falls beide Angaben gemacht werden (Header und Query), dann gilt die Angabe im Query-Parameter.

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