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


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:

NameTypBeschreibung
statestring (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.  
scopestringListe 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_typecodeParameter ist derzeit ein fester Wert und muss mit übergeben werden. Bitte setzen Sie hier "json" als fester Wert.
client_idstring (40 Zeichen)Eindeutige ID, die von LINA für die Webanwendung eines Drittanbieters erstellt wurde.
operator_idstring (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
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 
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:

NameTypBeschreibung
codestring (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.
statestring (20-40 Zeichen)Wert des Parameters der bei der ersten Anfrage auf Clientseite erzeugt wurde. Dient der Zuordnung der Antwort zur Anfrage.
clientIdstringID des clients, welcher für den angegebenen Betrieb in Zukunft eingesetzt werden kann. 
clientSecretstringClient Secret für den neu angelegten Client


Query-Antwortparameter im Fehlerfall:

NameTypBeschreibung
errorstringFehlermeldung, 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.
statestring (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:

NameTypBeschreibung
client_idstring (40 Zeichen)Eindeutige ID, die von LINA TeamCloud für die Webanwendung eines Drittanbieters erstellt wurde.
client_secretstring (32 Zeichen)Zu der Client-ID gehöriges Secret. Dieses kann in LINA TeamCloud eingesehen werden.
redirect_uristringDie URL muss mit der des Autorisierungsprozesses übereinstimmen.
codestring (40 Zeichen)Von LINA TeamCloud generierter Autorisierungscode, der dem Client durch die Bestätigung durch den Nutzer übermittelt wurde.
grant_typestringFester Wert authorization_code, da wir mittels Autorisierungscode das Token erzeugen.


Antwort-Statuscodes (HTTP):

CodeBedeutung
200Anfrage erfolgreich
400Der Autorisierungscode ist entweder abgelaufen oder wurde nicht gefunden oder grant_type ist nicht korrekt gesetzt.
403Client-ID client_id und/oder Client-Secret client_secret sind nicht korrekt.
405HTTP-Verb ist falsch. Für die Anfrage muss der Request-Typ POST sein.


Antwort-Parameter (JSON) bei Erfolg:

NameTypBeschreibung
token_typestringStatischer Wert bearer.
access_tokenstring (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_inintAblaufzeit des Access-Tokens in Sekunden.
refresh_tokenstring (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:

NameTypBeschreibung
statusstringStatischer Wert error.
messagestringDetaillierte 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:

NameTypBeschreibung
client_idstring (40 Zeichen)Eindeutige ID, die von LINA TeamCloud für die Webanwendung eines Drittanbieters erstellt wurde.
client_secretstring (32 Zeichen)Zu der Client-ID gehöriges Secret. Dieses kann in LINA TeamCloud eingesehen werden.
refresh_tokenstring (40 Zeichen)Zuvor erhaltenes Refresh-Token. Dieses ist nur für genau eine Anfrage gültig.
grant_typestringFester wert refresh_token, da wir mittels Refresh-Token ein Access-Token und ein weiteres Refresh-Token erzeugen.


Antwort-Statuscodes (HTTP):

CodeBedeutung
200Anfrage erfolgreich
400Das Refresh-Token refresh_token ist entweder abgelaufen oder wurde nicht gefunden oder grant_type ist nicht korrekt gesetzt.
403Client-ID client_id und/oder Client-Secret client_secret sind nicht korrekt.
405HTTP-Verb ist falsch. Für die Anfrage muss der Request-Typ POST sein.


Antwort-Parameter (JSON) bei Erfolg:

NameTypBeschreibung
token_typestringStatischer Wert bearer.
access_tokenstring (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_inintAblaufzeit des Access-Tokens in Sekunden.
refresh_tokenstring (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:

NameTypBeschreibung
statusstringStatischer Wert error.
messagestringDetaillierte 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"