Jedes Programm eines Drittanbieters mit Schnittstelle zum Webservice von LINA TeamCloud muss sich beim jeweiligen Endpunkt der Third Party API (TPAPI) anmelden. Es bekommt einen Access-Token für die weitere Authentifizierung .
Voraussetzung für die Anmeldung sind die Lizensierung, Registrierung des Clients und Berechtigungen (sowie bei der POS-API/Webkasse die Konfiguration der Kasse).
INHALTSVERZEICHNIS
Der oAuth Standard
LINA TeamCloud verwendet den Standard Hybrid Flow von Open-ID Connect.
Für weitere Informationen siehe http://openid.net/specs/openid-connect-core-1_0.html#Authentifizierungsanfrage
Die Schritte zur Einrichtung der Authentifizierung mit der Amadeus360 TP API sind daher:
- Implementierung des Authorization-Code-Verfahrens
- Registrieren und Aktivieren eines Clients in Amadeus360
In den nachfolgenden werden Begriffe verwendet, die nochmal genauer spezifiziert werden:
- Server: LINA TeamCloud Webservice bzw. die TP API-Schnittstelle
- Client: Die Anwendung, die auf die API zugreifen soll
der Client wird in LINA TeamCloud für die Zugriffssicherheit registriert - Nutzer: Der Anwender, der das Programm des Drittanbieters nutzt
Erstellung eines Clients in LINA TeamCloud
Um Zugriff auf die TPAPI zu erhalten, muss ein Client im jeweiligen Laden angelegt werden. Dies geschieht pro Endpunkt und pro Programm innerhalb von LINA TeamCloud unter API-Zugang erstellen bzw. aktivieren.
In der Liste der Clients stehen eine Client-ID und ein Secret, dass im nachfolgenden verwendet wird.
Authorization-Code-Verfahren
1. Schritt: Authorization-Code-Link erzeugen
Zuerst erhält der Benutzer einen Authorization-Code-Link, der wie folgt aussieht:
http://login.amadeus360.de/extern/oauth2/authorize?client_id={clientId}&state={state}&scope={scope}&response_type={responseType}&redirect_uri={uri}
Aufruf allgemein:
GET http://login.amadeus360.de/extern/oauth2/authorize
Aufruf-Parameter:
Name | Typ | Beschreibung |
---|---|---|
state | string (min. 20, max. 40 Zeichen) | Wird verwendet, um sicherzustellen, dass der Client seine Daten zuordnen kann (Authentifizierungsanforderung und der entsprechende Rückruf von der Server). Dies kann eine zufällig generierte Zeichenkette sein, mit welcher der Client überprüfen kann, ob der Rückruf stattgefunden hat. |
scope | string | Liste der Bereiche, auf die der Client gemäß der Amadeus 360 API zugreifen möchte, getrennt durch Komma. Zusätzlich zu diesen Scopes muss der Scope "openid" angefordert werden. Um zusätzliche Benutzerinformationen vom UserInfo-Endpunkt zu erhalten, fügen Sie bitte die entsprechenden Bereiche hinzu. Die für die Endpunkte benötigten Scopes finden Sie jeweils am Anfang der Endpunktdokumentation |
response_type | code | Parameter ist derzeit ein fester Wert und muss mit übergeben werden. Bitte setzen Sie hier "json" als fester Wert. |
client_id | string (40 Zeichen) | Eindeutige ID, die von LINA für die Webanwendung eines Drittanbieters erstellt wurde. |
operator_id | string (40 Zeichen) | Sollte noch kein Client für einen Betrieb in LINA TeamCloud erzeugt worden sein und Ihre Application über eine gültige Operator-ID verfügen, so kann statt dem Client die Operator-ID angegeben werden. Nach dem Login im nächsten Schritt kann der User dann auch einen Client mit den entsprechenden Rechten anlegen. |
Bitte stellen Sie sicher, dass Sie nicht Ihr Client-Secret in der Anfrage mit senden. Ein Code-Verifier ist derzeit noch nicht implementiert. Um Ihre App bei der Gastro-MIS registrieren zu lassen, schicken Sie bitte eine Mail an support@gastro-mis.de und erfragen die Registrierung als Third-Party-Operator
Beispiel Login-Link mit existierendem Client:
https://login.amadeus360.de/extern/oauth2/authorize?state=01234567890123456789&scope=openid,merchandisemanagement_read&redirect_uri=https%3A%2F%2Fwww.gastro-mis.de&client_id=8d703dec5bff161a57394fcae19eac9cdc4ffaa6
Beispiel Login-Link mit Operator-ID:
https://login.amadeus360.de /extern/oauth2/authorize?state=01234567890123456789&scope=openid&redirect_uri=https%3A%2F%2Fwww.gastro-mis.de&operator_id=baf9f8b910fe2141739560847876dd6b7ef82a17
Login-Formular
Beim Aufrufen des Login-Links wird ein Login-Formular sichtbar in dem der Benutzer sich anmelden muss.
und den Berechtigungen zum Lesen oder Schreiben von Daten durch das jeweilige Programm (scopes) zustimmen muss.
Nach erfolgreicher Anmeldung wird zu der redirect_uri zurückgesprungen. Der AuthCode befindet sich als Paramater (code) in der URL und ist ab nun 15 Minuten gültig.
Beispiel Rücksprung:
https://www.gastro-mis.de/?code=60df21ba298ef85710aed87c51b20678e6f994bf&state=01234567890123456789
Falls sie sich über eine Operator-ID angemeldet haben enthält die Rückgabe auch noch die Client-ID und das clientSecret:
https://www.gastro-mis.de/?code=24c7a3c0f9b124881a942f87c4d833bcaf738176&state=01234567890123456789&clientId=41f7723ac840ed83a1d63112009e596097261d0f&clientSecret=9477b921e9b4e4188fedc17c92e5063f
Query-Antwortparameter bei Erfolg:
Name | Typ | Beschreibung |
---|---|---|
code | string (40 Zeichen) | Von Amadeus 360 generierter Autorisierungscode, der vom Client verwendet wird, um ein Zugriffstoken und ein Refresh-Token zu erhalten. Der Autorisierungscode hat eine begrenzte Gültigkeit von 900 Sekunden. |
state | string (20-40 Zeichen) | Wert des Parameters der bei der ersten Anfrage auf Clientseite erzeugt wurde. Dient der Zuordnung der Antwort zur Anfrage. |
clientId | string | ID des clients, welcher für den angegebenen Betrieb in Zukunft eingesetzt werden kann. |
clientSecret | string | Client Secret für den neu angelegten Client |
Query-Antwortparameter im Fehlerfall:
Name | Typ | Beschreibung |
---|---|---|
error | string | Fehlermeldung, die beschreibt, warum die Anfrage nicht erfolgreich war. Beim Ablehnen auf der Zustimmungsseite ist die Fehlermeldung access_denied . Zum aktuellen Zeitpunkt gibt es keine anderen Fehlermeldungen in LINA. |
state | string (20-40 Zeichen) | Wert des Parameters der bei der ersten Anfrage auf Clientseite erzeugt wurde. Dient der Zuordnung der Antwort zur Anfrage. |
2. Schritt: Abrufen eines Access-Tokens
Ein erstes Access- und Refresh-Token kann mittels Autorisierungscode erzeugt werden. Dazu muss der Client eine Anfrage an den Server senden. Beachten Sie bitte, dass nur ein einziges Token mittels Autorisierungscode erzeugt werden kann. Weitere Access-Tokens können nur mit einem Refresh-Token erzeugt werden.
Aufruf allgemein
POST http://login.amadeus360.de/extern/oauth2/token
Beispiel Curl - Aufruf
curl --data "grant_type=authorization_code&client_id=8d703dec5bff161a57394fcae19eac9cdc4ffaa6&client_secret=c03001c30c3decab0c43798b98d320d6&code=60df21ba298ef85710aed87c51b20678e6f994bf" https://login.amadeus360.de/extern/oauth2/token
Antwort JSON-Objekt
{"token_type":"bearer","access_token":"ab205cd03ea010e6544b5fbf4d0351d1bbc7d0a1","expires_in":1800,"refresh_token":"56d326770a8bcd2bdee9f3c8c4e9c955764a4e3f"}
Aufruf-Parameter:
Name | Typ | Beschreibung |
---|---|---|
client_id | string (40 Zeichen) | Eindeutige ID, die von LINA TeamCloud für die Webanwendung eines Drittanbieters erstellt wurde. |
client_secret | string (32 Zeichen) | Zu der Client-ID gehöriges Secret. Dieses kann in LINA TeamCloud eingesehen werden. |
redirect_uri | string | Die URL muss mit der des Autorisierungsprozesses übereinstimmen. |
code | string (40 Zeichen) | Von LINA TeamCloud generierter Autorisierungscode, der dem Client durch die Bestätigung durch den Nutzer übermittelt wurde. |
grant_type | string | Fester Wert authorization_code , da wir mittels Autorisierungscode das Token erzeugen. |
Antwort-Statuscodes (HTTP):
Code | Bedeutung |
---|---|
200 | Anfrage erfolgreich |
400 | Der Autorisierungscode ist entweder abgelaufen oder wurde nicht gefunden oder grant_type ist nicht korrekt gesetzt. |
403 | Client-ID client_id und/oder Client-Secret client_secret sind nicht korrekt. |
405 | HTTP-Verb ist falsch. Für die Anfrage muss der Request-Typ POST sein. |
Antwort-Parameter (JSON) bei Erfolg:
Name | Typ | Beschreibung |
---|---|---|
token_type | string | Statischer Wert bearer . |
access_token | string (40 Zeichen) | Das Zugriffstoken ist ein von LINA TeamCloud generiertes "Bearer-Token", das für den Zugriff auf Ressourcen verwendet wird. Die Gültigkeit für jedes Access-Token liegt bei 900 Sekunden. |
expires_in | int | Ablaufzeit des Access-Tokens in Sekunden. |
refresh_token | string (40 Zeichen) | Das Refresh-Token wird später genutzt, um weitere Access-Tokens zu erstellen. Das über OAuth2 erzeugte Refresh-Token besitzt keine Gültigkeitsdauer und läuft somit nicht ab. |
Antwort-Parameter (JSON) im Fehlerfall:
Name | Typ | Beschreibung |
---|---|---|
status | string | Statischer Wert error . |
message | string | Detaillierte Fehlerbeschreibung. |
Mit dem Access-Token können nun Ressourcen abgefragt werden.
Wenn Sie die Logik mit einem Tool wie Postman testen, achten Sie bitte darauf, dass Sie die POST-Parameter im Body mitgeben.
Anforderung eines neuen Zugriff-Tokens mit einem Refresh-Token
Mithilfe eines noch gültigen Refresh-Tokens kann ein weiteres Access-Token erzeugt werden. Dazu muss eine Anfrage an den Server gesendet werden. Mit dem neuen Accesstoken wird auch ein neues Refresh-Token für den nächsten Abruf eines Accesstokens erstellt. Das neue Access-Token kann nur mit dem letzten Refresh-Token erzeugt werden. Die Kette der Refresh-Token ist nur so lange gültig, wie das vorhergehende Token.
Das alte Token bleibt noch 15 Minuten gültig, danach wird es gelöscht. Es die neuen Refresh-Tokens, die mit den Access-Tokens ausgeliefert werden sollten also unbedingt gespeichert und für den nächsten Abruf eines Access-Tokens genutzt werden.
Aufruf allgemein:
POST http://login.amadeus360.de/extern/oauth2/token
Aufruf-Parameter:
Name | Typ | Beschreibung |
---|---|---|
client_id | string (40 Zeichen) | Eindeutige ID, die von LINA TeamCloud für die Webanwendung eines Drittanbieters erstellt wurde. |
client_secret | string (32 Zeichen) | Zu der Client-ID gehöriges Secret. Dieses kann in LINA TeamCloud eingesehen werden. |
refresh_token | string (40 Zeichen) | Zuvor erhaltenes Refresh-Token. Dieses ist nur für genau eine Anfrage gültig. |
grant_type | string | Fester wert refresh_token , da wir mittels Refresh-Token ein Access-Token und ein weiteres Refresh-Token erzeugen. |
Antwort-Statuscodes (HTTP):
Code | Bedeutung |
---|---|
200 | Anfrage erfolgreich |
400 | Das Refresh-Token refresh_token ist entweder abgelaufen oder wurde nicht gefunden oder grant_type ist nicht korrekt gesetzt. |
403 | Client-ID client_id und/oder Client-Secret client_secret sind nicht korrekt. |
405 | HTTP-Verb ist falsch. Für die Anfrage muss der Request-Typ POST sein. |
Antwort-Parameter (JSON) bei Erfolg:
Name | Typ | Beschreibung |
---|---|---|
token_type | string | Statischer Wert bearer . |
access_token | string (40 Zeichen) | Das Zugriffstoken ist ein von LINA TeamCloud generiertes "Bearer-Token", das für den Zugriff auf Ressourcen verwendet wird. Die Gültigkeit für jedes Access-Token liegt bei 900 Sekunden. |
expires_in | int | Ablaufzeit des Access-Tokens in Sekunden. |
refresh_token | string (40 Zeichen) | Das Refresh-Token wird später genutzt, um weitere Access-Tokens zu erstellen. Das über OAuth2 erzeugte Refresh-Token besitzt keine Gültigkeitsdauer und läuft somit nicht ab. |
Antwort-Parameter (JSON) im Fehlerfall:
Name | Typ | Beschreibung |
---|---|---|
status | string | Statischer Wert error . |
message | string | Detaillierte Fehlerbeschreibung. |
Manuelles Erzeugen von Refresh-Token
Zum wiederholten Testen der programmierten Schnittstelle, können auch manuell Refresh-Tokens erzeugt werden. Diese unterscheiden sich von den durch OAuth2 erzeugten Tokens darin, dass Sie eine limitierte Gültigkeitsdauer von 15 Minuten (einstellbar) besitzen.
Ein manuelles Erzeugen ist in LINA TeamCloud möglich unter
LINA >> Config >> Schnittstellen >> Tab OAuth >> Ende der Tabellenzeile refresh token"