Jedes Programm eines Drittanbieters muss sich an der Schnittstelle zu LINA TeamCloud anmelden.
OAuth2 ö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
implementieren sie für OAuth2 eine automatische Erneuerung mit dem Wiederaufruf von ../oauth2/authorize?.. , wenn sie die token chain unerwartet verloren haben.
Der OAuth2 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
Authorization-Code-Verfahren
Um Zugriff auf die TPAPI zu erhalten, muss ein Client im jeweiligen Laden registriert werden. Dies geschieht pro Endpunkt und pro Programm mit der Operator-ID des Partners und einmaliger Autorisierung durch berechtigte Personen.
1. Schritt: Authorization-Code-Link
Aufruf LINA mit Operator-ID
Beispiel Login-Link mit Operator-ID GET .../extern/oauth2/authorize?state=01234567890123456789&scope=openid&response_type=json&redirect_uri=https%3A%2F%2Fyour.rest-uri.partner.id&operator_id=baf9f8b910fe2141739560847876dd6b7ef82a17
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 | Es muss der Scope "openid" angefordert werden. |
| redirect_uri | string | Es muss die indentische URI wie beim Anlegen der Operatot-ID angegeben werden. |
| response_type | code | Parameter ist derzeit ein fester Wert "json". |
| operator_id | string (40 Zeichen) | Die Operator-ID für die Partner-Schnittstelle enthält Namen und angefragte Zugriffsrechte. |
2. Schritt: Login-Formular
Beim Aufrufen des Login-Links wird von LINA TeamCloud ein Formular angezeigt, in dem ein berechtigter Benutzer aus dem Laden sich anmelden und den Zugriffsrechten für die Partner-Schnittstelle zustimmen muss.
Ist ein Benutzer in mehreren Läden tätig, wählt er den betreffenden Laden aus.
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://your.rest-uri.partner.id/?code=24c7a3c0f9b124881a942f87c4d833bcaf738176&state=01234567890123456789&clientId=41f7723ac840ed83a1d63112009e596097261d0f&clientSecret=9477b921e9b4e4188fedc17c92e5063f
Query-Antwortparameter bei Erfolg:
| Name | Typ | Beschreibung |
|---|---|---|
| code | string (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. |
| 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. |
3. 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.
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:
| 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. |
| 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 übermittelt. Das neue Access-Token ist so lange gültig wie das vorhergehende und kann nur mit dem letzten Refresh-Token erzeugt werden.
Das alte Token bleibt noch 15 Minuten gültig, danach wird es gelöscht. Die neuen Refresh-Tokens müssen gespeichert und für den nächsten Abruf eines Access-Token genutzt werden.
Aufruf allgemein:
POST .../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. |