Authentication

API Authentifizierung, OAuth2, OAuth, Postman, Access Token, Client Key, Client Secret

Modul: ETRON onRetail REST API

API & Hooks -> Authentication

API & Hooks -> Authentication

Über Authentication werden OAuth2-Zugangsdaten für externe Programme verwaltet. Der Zugriff auf die REST-API wird damit auf berechtigte Verbindungen beschränkt.

Damit ein externes Programm auf die REST-API zugreifen kann, werden gültige Zugangsdaten benötigt. Über Authentication wird festgelegt, welche Programme verbunden werden dürfen und welche Rechte verwendet werden. Jede Verbindung wird über OAuth2 aufgebaut. Dies gilt für eigene Software, andere Systeme und Testwerkzeuge wie Postman.

Es stehen zwei Vorgehensweisen zur Verfügung:

• Schnelleinstieg mit Postman: Ein vorkonfiguriertes Postman-Paket wird direkt heruntergeladen. Das Paket wird zum schnellen Testen der API in Postman verwendet.

• Eigene Authentifizierung: Für ein Drittprogramm wird ein eigener OAuth2-Zugang angelegt. Dabei werden ein eigener Name, ein eingeschränkter Benutzer und eigene Zugangsdaten verwendet. Dieser Zugang kann mit jedem OAuth2-fähigen Programm verwendet werden.

Schnelleinstieg: Postman-Paket verwenden

Das Paket enthält gültige Zugangsdaten der jeweiligen Instanz. Die Datei ist wie ein Passwort zu behandeln. Eine öffentliche Weitergabe oder Ablage in Tickets und Versionsverwaltungen ist zu vermeiden.

Über API & Hooks -> Endpunkte -> Documentation steht Download Postman Collection & Environment zur Verfügung. Es wird ein ZIP-Archiv mit der vollständigen Collection und einer vorkonfigurierten Umgebung heruntergeladen.

Die Umgebung wird mit base_url, Client Key und Client Secret der jeweiligen Instanz befüllt. Der Import des Archivs und der Collection ist unter Documentation: v2 REST API Dokumentation beschrieben. Dort wird auch eine Collection-Datei ohne Zugangsdaten bereitgestellt.

Nach dem Import werden folgende Schritte durchgeführt:

1. Die Umgebung onRetail V2 wird in Postman als aktive Umgebung ausgewählt.

2. In der Collection wird Authorization geöffnet.

3. Unter Configure New Token wird Get New Access Token ausgewählt.

4. Das Token wird abgerufen und mit Use Token übernommen.

Danach können API-Abfragen ohne eigene Authentifizierung durchgeführt werden.

Eigene Authentifizierung anlegen

Die erzeugten Zugangsdaten sind nicht an Postman gebunden. Die Zugangsdaten können von jedem OAuth2-fähigen Programm verwendet werden. Die Hinterlegung in Postman wird nachfolgend beispielhaft beschrieben.

1

Authentifizierung in ETRON onRetail erstellen

API & Hooks -> Authentication

1. Eine neue Authentifizierung wird angelegt.

2. Folgende Einstellungen werden gesetzt:

   • Name: Name des Drittprogramms

   • OAuth Type: Client Credentials

   • User: Für die API verwendeter Benutzer

3. Alle weiteren Felder bleiben unverändert.

4. Die Authentifizierung wird gespeichert.

Name, OAuth Type und User werden gesetzt

Die Werte Client Key und Client Secret werden für die Authentifzierung über die API-Plattform benötigt.

2

Collection in Postman vorbereiten

Für die manuelle Einrichtung wird dieselbe Collection wie beim Schnelleinstieg verwendet. Sie steht über API & Hooks -> Endpunkte -> Documentation -> Download Postman Collection & Environment zur Verfügung.

1. Die heruntergeladene Collection in Postman über die Schaltfläche "Import" importieren. Dabei kann eine einzelne Datei oder ein Ordner ausgewählt werden.

   

   Import einer Collection in Postman
2. Nach dem Import die Collection in Postman öffnen.

3. Den Tab Variables auswählen.

4. Die Variable base_url anlegen

   • Current Value: URL der Instanz, beispielsweise https://xxxxxx.wawi.onretail.eu Die URL wird ohne abschließenden / hinterlegt.

   • Optional können client_id und client_secret als Variablen hinterlegt werden. Als Current Value werden Client Key und Client Secret eingetragen.

Variablenübersicht in Postman

1. In den Tab Authorization wechseln, um die Authentifzierung zu konfigurieren.

2. Als Type wird OAuth 2.0 gesetzt.

   

   OAuth 2.0 als Auth Type in Postman

3

Access Token konfigurieren

1. Im Tab Authorization zum Bereich Configure New Token scrollen.

2. Folgende Werte eintragen:

   • Token Name: frei wählbar, beispielsweise ETRON onRetail Postman Token

   • Grant Type: Client Credentials

   • Access Token URL: {{base_url}}/api/v2/authentication/oauth2/token

   • Client ID: Client Key aus ETRON onRetail oder {{client_id}} (wenn als Variable angelegt)

   • Client Secret: Client Secret aus ETRON onRetail oder {{client_secret}} (wenn als Variable angelegt)

   • Client Authentication: Send as Basic Auth header

Neue Tokenkonfiguration in Postman

4

Access Token generieren

Access-Token generieren

1. Get New Access Token auswählen.

2. Das Token wird abgerufen.

3. Use Token wird ausgewählt.

API-Abfragen durchführen

Nach erfolgreicher Authentifizierung können API-Abfragen über den Schnelleinstieg oder eine eigene Authentifizierung durchgeführt werden. Beispielabfragen sind in der Postman Collection enthalten.

Weitere Informationen: Documentation: v2 REST API Dokumentation (Postman Collection + Environment)