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

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

OAuth öffnet eine sichere Verbindung vonseiten des Drittanbieters mit einem DNS Namen und kann auf dieselbe 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 automatische Erneuerung mit dem Wiederaufruf 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
• Erstellung eines Clients in LINA TeamCloud
• Authorization-Code-Verfahren
  • 1. Schritt: Authorization-Code-Link erzeugen
    • Aufruf allgemein:
    • Aufruf-Parameter:
    • Beispiel Login-Link mit existierendem Client:
    • Beispiel Login-Link mit Operator-ID:
    • Login-Formular
    • Beispiel Rücksprung:
    • Query-Antwortparameter bei Erfolg:
  • 2. Schritt: Abrufen eines Access-Tokens
    • Aufruf allgemein
    • Beispiel Curl - Aufruf
    • Antwort JSON-Objekt
    • Aufruf-Parameter:
    • Antwort-Statuscodes (HTTP):
    • Antwort-Parameter (JSON) bei Erfolg:
    • Antwort-Parameter (JSON) im Fehlerfall:
• Anforderung eines neuen Zugriff-Tokens mit einem Refresh-Token
  • Aufruf allgemein:
  • Aufruf-Parameter:
  • Antwort-Statuscodes (HTTP):
  • Antwort-Parameter (JSON) bei Erfolg:
  • Antwort-Parameter (JSON) im Fehlerfall:
• Manuelles Erzeugen von Refresh-Token

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 Absätzen werden folgende Begriffe verwendet:

• 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:

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

Aufruf allgemein:

GET .../extern/oauth2/authorize

Aufruf-Parameter:

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:

... /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:

.../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 Parameter (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:

Query-Antwortparameter im Fehlerfall:

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:

Antwort-Statuscodes (HTTP):

Antwort-Parameter (JSON) bei Erfolg:

Antwort-Parameter (JSON) im Fehlerfall:

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:

Antwort-Statuscodes (HTTP):

Antwort-Parameter (JSON) bei Erfolg:

Antwort-Parameter (JSON) im Fehlerfall:

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"