Jedes Programm eines Drittanbieters muss sich an der Schnittstelle zu LINA TeamCloud anmelden

Voraussetzung für die Anmeldung sind die Lizensierung, Registrierung des Clients und Berechtigungen, sowie bei der POS-API/Webkasse die Konfiguration der Kasse.


OAuth öffnet eine sichere Verbindung von Seiten des Drittanbieters mit einem DNS Namen und kann auf die selbe Weise erneuert werden. Die token chain wird nach der ersten Autorisierung ständig erneuert.
Alternativ kann die API-Key Authentifizierung genutzt werden. siehe API-Key authentication / Authentifizierung 


Der Aufruf für die LINA data API ist geändert, die alte URL amadeus360 ist noch erreichbar.
Bitte auf die neue URL umstellen.

https://api.lina.de/ ...



implementieren sie für OAuth eine einen automatische Erneuerung mit dem Wieder-Aufruf von  ../oauth2/authorize?.. , wenn sie die token chain unerwartet verloren haben.

zurück zum Inhaltsverzeichnis

EN

OAuth opens a secured connection from a party with DNS name and even without public fixed IP address. The token chain is repeatedly renewed after first authorization. OAUth is started by a auth call by Third Party without public fixed IP and can be restarted the same way. 


For OAuth implement an automatic renewal re-calling ../oauth2/authorize?.. and "login" by relevant users after the token chain was lost unexpectedly

back to table of contents




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 LINA data TPAPI sind daher:

  • Implementierung des Authorization-Code-Verfahrens
  • Registrieren und Aktivieren eines Clients in LINA TeamCloud


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:

.../extern/oauth2/authorize?client_id={clientId}&state={state}&scope={scope}&response_type={responseType}&redirect_uri={uri}

Aufruf allgemein:

GET .../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 LINA data TPAPI 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
... /extern/oauth2/authorize?state=01234567890123456789&scope=openid,merchandisemanagement_read&redirect_uri=https%3A%2F%2Fwww.gastro-mis.de&client_id=8d703dec5bff161a57394fcae19eac9cdc4ffaa6 
.../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 LINA TeamCloud 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 .../extern/oauth2/token

Beispiel Curl - Aufruf

curl --data "grant_type=authorization_code&client_id=8d703dec5bff161a57394fcae19eac9cdc4ffaa6&client_secret=c03001c30c3decab0c43798b98d320d6&code=60df21ba298ef85710aed87c51b20678e6f994bf" .../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 .../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"