OAuth 2.0 (Server)

Wenn Lobster Integration als HTTP-Server auftritt, kann die Authentifizierung eingehender Clientanfragen über OAuth erfolgen.

In diesem Fall kann Lobster Integration als OAuth 2.0 Authorization Server agieren und Zugriffstoken ausstellen, die Clients für den gesicherten Zugriff auf geschützte Ressourcen verwenden können.

Der Kanal mit der OAuth 2.0-Server-Konfiguration muss in Phase 1 den jeweiligen Profilen zugewiesen werden, um eine Authentifizierung der eingehenden HTTP(S) Requests zu ermöglichen.

Die Möglichkeit, Lobster Integration als OAuth 2.0-Server zu betreiben, kann über die Konfigurationsdatei ./etc/startup.xml deaktiviert werden, indem der Eintrag <Set name="enableOAuth">false</Set> gesetzt wird.

Fehlt dieser Eintrag oder ist er nicht auf false gesetzt, kann Lobster bei entsprechender Konfiguration als OAuth 2.0-Server fungieren.

Einstellungen im Kanal

Im Tab “Partner-Zugang (Partner zu mir)” sind Partnerkennung und Partnerkennwort zu definieren. Je nach verwendetem Grant Type ist es erforderlich, diese Zugangsdaten dem Client zur Verfügung zu stellen.

Über die Schaltfläche "OAuth2" sind im Anschluss die OAuth 2.0 Settings abrufbar:

images/download/attachments/137310301/1-version-1-modificationdate-1745996201471-api-v2.png

(1) Client ID: Die Client ID entspricht der ID des Kanals.

(2) Client Secret: Das Client Secret basiert auf dem Partner-Kennwort, dieses muss also eingetragen werden. Wird das Partner-Kennwort geändert, ändert sich auch das Client Secret.

Unterstützte Grant Types

Der Grant Type bestimmt, wie eine Anwendung ein Zugriffstoken vom Autorisierungsserver erhält. Er definiert den Authentifizierungsfluss je nach Anwendungsfall, z. B. mit Benutzerinteraktion oder rein serverseitig.

Folgende Grant Types werden unterstützt:

Grant Type	Beschreibung
client_credentials	Wird verwendet, wenn ein Client direkt und ohne Nutzerinteraktion auf geschützte Ressourcen zugreifen soll, zum Beispiel für serverseitige APIs. Hier benötigt der Client die Client ID (1) und das Client Secret (2). Hinweis: Statt des Client Secrets kann der Client bei diesem Grant Type auch das Partner-Kennwort direkt verwenden. Der Client fragt das Token ab über: <IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>
authorization_code	Wird genutzt, wenn ein Benutzer sich authentifizieren soll und die Anwendung im Namen des Benutzers Zugriff auf Ressourcen erhält, typischerweise bei Web- oder Mobile-Apps mit Benutzer-Login. Die Zugangsdaten sind Partner-Kennung und Partner-Kennwort. Der Client erhält nach erfolgreicher Authentifizierung und dem Austausch des Autorisierungscodes sowohl ein Access Token als auch ein Refresh Token. Das Access Token wird für den Zugriff auf geschützte Ressourcen verwendet, während das Refresh Token genutzt werden kann, um nach Ablauf des Access Tokens ein neues Token zu erhalten – ohne dass sich der Benutzer erneut authentifizieren muss. Die Webseite, über die clientseitig die Zugangsdaten eingegeben werden müssen, liegt unter ./webapps/root/oauth2/OAuth2.html. Die für den Workflow notwendigen URLs, die der Client abfragen muss, sind: Authorization Code Flow: <IP/URL des Integration Servers>/dw/register/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&state=<STATE>&redirect_uri=<REDIRECT_URI> Token-Anfrage: <IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET> Refresh Token: <IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Grant Type

Beschreibung

client_credentials

Wird verwendet, wenn ein Client direkt und ohne Nutzerinteraktion auf geschützte Ressourcen zugreifen soll, zum Beispiel für serverseitige APIs.

Hier benötigt der Client die Client ID (1) und das Client Secret (2).

Hinweis: Statt des Client Secrets kann der Client bei diesem Grant Type auch das Partner-Kennwort direkt verwenden.

Der Client fragt das Token ab über:

<IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

authorization_code

Wird genutzt, wenn ein Benutzer sich authentifizieren soll und die Anwendung im Namen des Benutzers Zugriff auf Ressourcen erhält, typischerweise bei Web- oder Mobile-Apps mit Benutzer-Login.

Die Zugangsdaten sind Partner-Kennung und Partner-Kennwort.

Der Client erhält nach erfolgreicher Authentifizierung und dem Austausch des Autorisierungscodes sowohl ein Access Token als auch ein Refresh Token. Das Access Token wird für den Zugriff auf geschützte Ressourcen verwendet, während das Refresh Token genutzt werden kann, um nach Ablauf des Access Tokens ein neues Token zu erhalten – ohne dass sich der Benutzer erneut authentifizieren muss.

Die Webseite, über die clientseitig die Zugangsdaten eingegeben werden müssen, liegt unter ./webapps/root/oauth2/OAuth2.html.

Die für den Workflow notwendigen URLs, die der Client abfragen muss, sind:

Authorization Code Flow: <IP/URL des Integration Servers>/dw/register/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&state=<STATE>&redirect_uri=<REDIRECT_URI>

Token-Anfrage: <IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Refresh Token: <IP/URL des Integration Servers>/dw/register/oauth/token?grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Endpunkte

Für den Abruf und die Verarbeitung von OAuth 2.0-Tokens sind folgende Endpunkte relevant:

Token Endpoint: <IP/URL des Integration Servers>/dw/register/oauth/token

Wird vom Client verwendet, um ein Access Token (und ggf. ein Refresh Token) zu erhalten.

Authorization Endpoint: <IP/URL des Integration Servers>/dw/register/oauth/authorize

Dient zur Einleitung des Authorization Code Flows. Hier authentifiziert sich der Benutzer und erteilt Zugriff.

Code Verifier Endpoint: <IP/URL des Integration Servers>/dw/register/oauth/verify

Wird ausschließlich bei Authorization Code Flows mit Code Challenge benötigt, um den Code Verifier zu prüfen.

Hinweis: Wird ein DMZ-Server verwendet, dann bleibt die hier gezeigte Einrichtung auf dem inneren Integration Server identisch, aber es müssen auf dem DMZ-Server die beteiligten URLs in der Konfigurationsdatei ./etc/forward.properties eingetragen werden.

/dw/register/oauth/token=<URL des inneren Integration Servers>/dw/register/oauth/token
/dw/register/oauth/authorize=<URL des inneren Integration Servers>/dw/register/oauth/authorize
/dw/register/oauth/verify=<URL des inneren Integration Servers>/dw/register/oauth/verify

Tokens

Json Web Tokens

Dies ist die neue Standardeinstellung (→ siehe Probleme mit klassischen Tokens).

(1) Issuer (iss): Die Instanz, die das Token ausgibt. Sie können den Defaultwert verwenden (“webServiceUrl” aus der Konfigurationsdatei ./etc/startup.xml oder die Installations-ID, falls nicht konfiguriert).

(2) Audience (aud): Zusätzliche Kennung, da “Issuer“ für mehrere Kanäle verwendet werden kann. Default: Die Kanal-ID.

(3) Access-Tokengültigkeitsdauer: Wenn diese Zeit in der Vergangenheit liegt, muss ein neues Token angefordert werden.

(4) Refresh-Tokengültigkeitsdauer: Wenn diese Zeit in der Vergangenheit liegt, muss ein neues Token angefordert werden.

(5) Eigenes Zertifikat (Verschlüsselung): Eigenes Zertifikat, das zum Signieren des Tokens verwendet wird. Es sind nur RSA-Zertifikate zulässig.

(6) Refresh Audience: Audience für das Refresh-Token.

(7) Access & Refresh-Token zurückziehen: Dadurch werden der Wert von “Refresh Audience“ und auch interne Claims geändert. Wenn Sie hier klicken, werden alle erstellten Access- und Refresh-Tokens ungültig.

Klassische Tokens

Wenn die Option “Json Web Token (JWT) verwenden” nicht gesetzt ist, wird ein klassisches Token erzeugt. Wir empfehlen diese Einstellung nicht, da es in der Datenbank für einen Kanal nur ein aktuelles klassisches Token geben kann. Wenn mehrere Clients über einen Kanal, für den OAuth2 konfiguriert ist, auf ein Profil zugreifen, fordert jeder Client ein neues Token an und macht damit alte Tokens ungültig, die bereits von anderen Clients empfangen wurden. Dies führt zu Performanceproblemen und kann auch zu Datenbank-Deadlock-Exceptions führen. Bitte verwenden Sie die Option “Json Web Token (JWT) verwenden“, um dieses Problem zu vermeiden.

Ansicht nach erfolgter Token-Abfrage

Wurde vom Client ein Token abgefragt, dann ist eine erweiterte Ansicht mit dem aktuell gültigen Access Token (3), der Ablaufzeit (4) und dem Refresh Token (5) zu sehen.

(3) Access token: Kurzlebiger Schlüssel, der den Zugriff auf mit diesem Kanal geschützte Ressourcen erlaubt.

(4) Expires in: Ablauf-Datum des Tokens. Standardmäßig ist der Access Token 30 Tage gültig. Dies kann geändert werden über das System-Property hub.datawizard.oauth.expiresIn=<Anzahl_in_Sekunden> in der ./etc/wrapper.conf (Windows) bzw. ./bin/execute.sh (Linux).

(5) Refresh token: Langlebiger Schlüssel, mit dem ein neues Access Token angefordert werden kann, ohne sich erneut anmelden zu müssen.

(6) Reset: Löschen der Einträge nach Token-Abruf und Wiederherstellen des ursprünglichen Zustands.