OAuth 2.0 (Server)

Die Lobster Data Platform kann als HTTP-Server eingehende Clientanfragen über OAuth authentifizieren.

In dieser Rolle agiert Lobster Integration als OAuth 2.0 Authorization Server. Die Plattform stellt Access Token aus. Mit diesen Token greifen Clients auf geschützte Ressourcen zu.

Weisen Sie den Kanal mit der OAuth 2.0-Server-Konfiguration in Phase 1 den jeweiligen Profilen zu. Damit authentifiziert die Plattform eingehende HTTP(S)-Requests.

Setzen Sie in der Konfigurationsdatei ./etc/startup.xml den Eintrag <Set name="enableOAuth">false</Set>, um den OAuth 2.0-Server zu deaktivieren.

Fehlt dieser Eintrag oder steht er nicht auf false, lässt sich Lobster Integration bei entsprechender Konfiguration als OAuth 2.0-Server betreiben.

Bevor Sie beginnen

Um die OAuth 2.0-Server-Konfiguration einzurichten, legen Sie einen HTTP(S)-Kanal beim in der Übersicht markierten Partner an. Die Lobster Data Platform bietet dafür zwei Varianten.

Variante 1: Über das Partner-Kontextmenü

Navigieren Sie zu Verwaltung > Partner > Partner/Kanäle. Klicken Sie mit der rechten Maustaste auf den gewünschten Partner. Wählen Sie im Kontextmenü Neuen Kanal anlegen > Http(s).

Variante 2: Über den Schnellzugriff

Klicken Sie unten rechts auf den grünen Plus-Button. Wählen Sie Neuen Kanal anlegen > Http(s).

HINWEIS : Eine vollständige Übersicht zur Kanal-Verwaltung finden Sie unter Kanäle.

Einstellungen im Kanal

Definieren Sie im Tab Partner-Zugang (Partner zu mir) die Partnerkennung und das Partnerkennwort. Je nach verwendetem Grant Type stellen Sie diese Zugangsdaten dem Client zur Verfügung.

Über die Schaltfläche OAuth2 öffnen Sie anschließend die OAuth 2.0-Einstellungen:

Schaltfläche OAuth2 im Kanal

OAuth2 settings displaying Client ID and Client Secret with action buttons below.

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

(2) Client Secret: Das Client Secret basiert auf dem Partnerkennwort. Tragen Sie das Partnerkennwort ein. Ändert sich das Partnerkennwort, ändert sich auch das Client Secret.

Unterstützte Grant Types

Der Grant Type bestimmt, wie eine Anwendung ein Access Token vom Authorization Server erhält. Er definiert den Authentifizierungsfluss je nach Anwendungsfall. Beispiele: mit Benutzerinteraktion oder rein serverseitig.

Folgende Grant Types werden unterstützt:

Grant Type	Beschreibung
`client_credentials`	Der Client greift direkt und ohne Nutzerinteraktion auf geschützte Ressourcen zu. Typischer Anwendungsfall: serverseitige APIs. Der Client benötigt die Client ID (1) und das Client Secret (2). Hinweis: Bei diesem Grant Type kann der Client statt des Client Secrets auch das Partnerkennwort 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`	Ein Benutzer authentifiziert sich. Die Anwendung erhält im Namen des Benutzers Zugriff auf Ressourcen. Typischer Anwendungsfall: Web- oder Mobile-Apps mit Benutzer-Login. Die Zugangsdaten sind Partnerkennung und Partnerkennwort. Nach erfolgreicher Authentifizierung und nach dem Austausch des Authorization Codes erhält der Client ein Access Token und ein Refresh Token. Das Access Token dient dem Zugriff auf geschützte Ressourcen. Mit dem Refresh Token fordert der Client nach Ablauf des Access Tokens ein neues Token an. Der Benutzer muss sich dafür nicht erneut authentifizieren. Die Webseite für die clientseitige Eingabe der Zugangsdaten liegt unter `./webapps/root/oauth2/OAuth2.html`. Folgende URLs muss der Client für den Workflow abfragen: 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

Der Client greift direkt und ohne Nutzerinteraktion auf geschützte Ressourcen zu. Typischer Anwendungsfall: serverseitige APIs.

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

Hinweis: Bei diesem Grant Type kann der Client statt des Client Secrets auch das Partnerkennwort 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

Ein Benutzer authentifiziert sich. Die Anwendung erhält im Namen des Benutzers Zugriff auf Ressourcen. Typischer Anwendungsfall: Web- oder Mobile-Apps mit Benutzer-Login.

Die Zugangsdaten sind Partnerkennung und Partnerkennwort.

Nach erfolgreicher Authentifizierung und nach dem Austausch des Authorization Codes erhält der Client ein Access Token und ein Refresh Token. Das Access Token dient dem Zugriff auf geschützte Ressourcen. Mit dem Refresh Token fordert der Client nach Ablauf des Access Tokens ein neues Token an. Der Benutzer muss sich dafür nicht erneut authentifizieren.

Die Webseite für die clientseitige Eingabe der Zugangsdaten liegt unter ./webapps/root/oauth2/OAuth2.html.

Folgende URLs muss der Client für den Workflow abfragen:

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-Token sind folgende Endpunkte relevant:

Token Endpoint: http(s)://<IP/URL des Integration Servers>/dw/register/oauth/token

Der Client verwendet den Token Endpoint, um ein Access Token zu erhalten. Optional erhält er zusätzlich ein Refresh Token.

Authorization Endpoint: http(s)://<IP/URL des Integration Servers>/dw/register/oauth/authorize

Der Authorization Endpoint leitet den Authorization Code Flow ein. Der Benutzer authentifiziert sich hier und erteilt Zugriff.

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

Der Code Verifier Endpoint wird ausschließlich bei Authorization Code Flows mit Code Challenge benötigt. Er prüft den Code Verifier.

HINWEIS : Wird ein DMZ-Server verwendet, bleibt die hier gezeigte Einrichtung auf dem inneren Integration Server identisch. Tragen Sie auf dem DMZ-Server in der Konfigurationsdatei ./etc/forward.properties die folgenden Weiterleitungen ein. Ersetzen Sie http(s):// durch das tatsächlich verwendete Schema (https:// für Produktivumgebungen). Ersetzen Sie <Host:Port des inneren Integration Servers> durch Hostname oder IP-Adresse und Port. Verwenden Sie keinen abschließenden Schrägstrich.

/dw/register/oauth/token=http(s)://<Host:Port des inneren Integration Servers>/dw/register/oauth/token
/dw/register/oauth/authorize=http(s)://<Host:Port des inneren Integration Servers>/dw/register/oauth/authorize
/dw/register/oauth/verify=http(s)://<Host:Port des inneren Integration Servers>/dw/register/oauth/verify

Beispiel mit konkreten Werten:

/dw/register/oauth/token=https://integration.intern.example.com:8443/dw/register/oauth/token
/dw/register/oauth/authorize=https://integration.intern.example.com:8443/dw/register/oauth/authorize
/dw/register/oauth/verify=https://integration.intern.example.com:8443/dw/register/oauth/verify

Token

JSON Web Token

JSON Web Token (JWT) ist die neue Standardeinstellung. Siehe auch Abschnitt Klassische Token für die Hintergründe.

OAuth 2.0-Einstellungen mit Issuer, Audience und Tokengültigkeitsdauer

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

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

(3) Access-Tokengültigkeitsdauer: Liegt diese Zeit in der Vergangenheit, muss der Client ein neues Token anfordern.

(4) Refresh-Tokengültigkeitsdauer: Liegt diese Zeit in der Vergangenheit, muss der Client ein neues Token anfordern.

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

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

(7) Access & Refresh-Token zurückziehen: Diese Aktion ändert den Wert von Refresh Audience und auch interne Claims. Nach einem Klick werden alle erstellten Access Token und Refresh Token ungültig.

Klassische Token

Ist die Option JSON Web Token (JWT) verwenden nicht gesetzt, erzeugt die Plattform ein klassisches Token. Diese Einstellung wird nicht empfohlen.

In der Datenbank kann für einen Kanal nur ein aktuelles klassisches Token existieren. Mehrere Clients greifen über einen Kanal mit OAuth 2.0-Konfiguration auf ein Profil zu. Dann fordert jeder Client ein neues Token an. Damit werden Token ungültig, die andere Clients bereits empfangen haben. Die Folge sind Performance-Probleme und mögliche Datenbank-Deadlock-Exceptions.

Verwenden Sie stattdessen die Option JSON Web Token (JWT) verwenden, um dieses Problem zu vermeiden.

Ansicht nach erfolgter Token-Abfrage

Nach einer Token-Abfrage durch den Client erscheint eine erweiterte Ansicht. Diese zeigt das aktuell gültige Access Token (3), die Ablaufzeit (4) und das Refresh Token (5).

Erweiterte Ansicht mit Access Token, Expires in und Refresh Token

(3) Access Token: Kurzlebiger Schlüssel. Er erlaubt den Zugriff auf Ressourcen, die mit diesem Kanal geschützt sind.

(4) Expires in: Ablaufzeitpunkt des Tokens. Standardmäßig ist das Access Token 30 Tage gültig. Die Gültigkeitsdauer ändern Sie über die System-Property hub.datawizard.oauth.expiresIn=<Anzahl_in_Sekunden> in der Datei ./etc/wrapper.conf (Windows) oder ./bin/execute.sh (Linux).

(5) Refresh Token: Langlebiger Schlüssel. Mit ihm fordert der Client ein neues Access Token an, ohne sich erneut anzumelden.

(6) Reset: Löscht die Einträge nach dem Token-Abruf und stellt den ursprünglichen Zustand wieder her.

Documentation Index