Allgemein


Amadeus 360 verwendet den Standard Hybrid Flow von OpenID Connect. Die Schritte zur Einrichtung der Authentifizierung mit der  Amadeus 360 API sind daher:

  • Implementierung des Authorization-Code-Verfahrens
  • Aktivieren bzw. Erstellen eines Clients in Amadeus360


In den nachfolgenden werden Begriffe verwendet, die nochmal genauer spezifiziert werden:

  • Server: Amadeus 360 bzw. die API-Schnittstelle
  • Client: Die Anwendung, die auf die API zugreifen soll
  • Nutzer: Der Anwender, der die Software, also den Client, nutzt


Erstellung eines Clients in Amadeus 360


Um Zugriff auf die API zu erhalten, muss ein Client im jeweiligen Laden angelegt werden. Sofern Sie die benötigten Berechntigungen dazu haben, können Sie neue Clients unter Mein Restaurant > Schnittstellen > API-Zugriff anlegen. Nach dem Anlegen erhalten Sie in der Liste eine Client-ID und ein Secret, dass im nachfolgenden verwendet wird. Weiter Details finden Sie hier: API-Zugang erstellen bzw. aktivieren


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


Auruf-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. Für weitere Informationen siehe http://openid.net/specs/openid-connect-core-1_0.html#Authentifizierungsanfrage  
scopestringListe der Bereiche, auf die der Client gemäß der Amadeus 360 API zugreifen möchte, getrennt durch Leerzeichen. 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.
response_typecodeParameter ist derzeit ein fester Wert und muss mit übergeben werden.
client_idstring (40 Zeichen)Eindeutige ID, die von Amadeus 360 für die Webanwendung eines Drittanbieters erstellt wurde.

Bitte stellen Sie sicher, dass Sie nicht Ihr Client-Secret in der Anfrage mitsenden. Ein Code-Verifier ist derzeit noch nicht implementiert.


Antwort:

Als Antwort gibt der Autorisierungsserver Amadeus 360 eine Webseite zurück.

Wenn sich der Benutzer bereits in dieser Browsersitzung angemeldet hat und die Anmeldung noch gültig ist, wird eine Zustimmungsseite zurückgegeben. Andernfalls wird die Seite zur Anmeldung des Benutzers, zurückgegeben. Wurde ein Parameter nicht oder fehlerhaft übermittelt, gibt der Server eine Fehlerseite inkl. Fehlercodes zurück.


2. Schritt: Benutzer autorisiert die Anwendung


Im zweiten Schritt muss der Nutzer die Seite bestätigen. Dabei wird eine Anfrage an den Server geschickt, die bei Erfolg einen authorization_code erzeugt.


3. Schritt: Anwendung erhält Autorisierungscode


Nach der Bestätigung des Nutzers wird dieser an die angegebene Redirect-URI weitergeleitet. Je nachdem, ob der Nutzer abgelehnt oder angenommen hat, werden unterschiedliche Parameter übermittelt.

Query-Parameter 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.


Query-Parameter 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 Amadeus 360.
statestring (20-40 Zeichen)Wert des Parameters der bei der ersten Anfrage auf Clientseite erzeugt wurde. Dient der Zuordnung der Antwort zur Anfrage.


4. 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


Aufruf-Parameter:

NameTypBeschreibung
client_idstring (40 Zeichen)Eindeutige ID, die von Amadeus 360 für die Webanwendung eines Drittanbieters erstellt wurde.
client_secretstring (32 Zeichen)Zu der Client-ID gehöriges Secret. Dieses kann in Amadeus 360 eingesehen werden.
redirect_uristringDie URI müss mit der des Autorisierungsprozesses übereinstimmen.
codestring (40 Zeichen)Von Amadeus 360 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 code 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 korret
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 Amadeus 360 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.


Manuelles Erstellen von Refresh-Token

Zum Testen der programmierten Schnittstelle, können auch manuell Refresh-Tokens erstellt werden. Diese unterscheiden sich von den durch OAuth2 erzeugten Tokens darin, dass Sie eine limitierte Gültigkeitsdauer besitzen.

Ein manuelles erzeugen ist in Amadeus 360 unter Mein Restaurant > Schnittstellen > API-Zugriff > Tab: Tokens möglich.


Anforderung eines neuen Zugriffstokens 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.


Aufruf allgemein:

POST http://login.amadeus360.de/extern/oauth2/token


Aufruf-Paramter:

NameTypBeschreibung
client_idstring (40 Zeichen)Eindeutige ID, die von Amadeus 360 für die Webanwendung eines Drittanbieters erstellt wurde.
client_secretstring (32 Zeichen)Zu der Client-ID gehöriges Secret. Dieses kann in Amadeus 360 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 korret
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 Amadeus 360 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.