Authentifizierungsprozess

Authentifizierungsprozess #

Anfragen an die API werden über ein JWT-Zugriffstoken gesichert. Dieses Token muss mit dem OAuth v2 Authorization Code Grant Flow generiert werden.

Das untenstehende Bild zeigt einen Überblick über den Prozess, der bei der Erzeugung der benötigten Token und deren Erhaltung insolviert ist:

Support-Login

Bitte beachten Sie die untenstehenden Links für detaillierte technische Informationen und Codebeispiele zum Genehmigungsverlauf:

Um mit den folgenden Schritten fortzufahren, benötigen Sie:

  • Die Request_URL, Client_ID & Client_Secret (diese werden Ihnen bereitgestellt, wenn Sie API Zugriff anfordern)
  • Ein Benutzer-Login für die ~.Dimensions.~ Reseller Portal zur Genehmigung der Autorisierung.
Color Wand tip
Wenn Sie irgendwann Probleme haben und Hilfe benötigen, kontaktieren Sie uns bitte unter [email protected] oder rufen Sie uns unter (+1) 480 207 7920 an.

1. Erlaubnis anfordern #

Der erste Schritt ist, die Genehmigung zu beantragen. Erstellen Sie eine URL die folgenden Elemente enthalten:

  • Client_Id: Das client_id wird beim ersten Anfordern von API bereitgestellt.
  • Response_Type: Verwenden Sie "Code".
  • State: Geben Sie einen Zustand an, der zur Identifikation der Weiterleitung verwendet werden kann
  • Redirect_URI: Dies setzt den Redirect URL der nach der Ausgabe eines Tokens verwendet wird. Der Standard ist https://127.0.0.1:8000.
  • Scope: Dies ist die Liste der Scopes, die bei der Anforderung eines Tokens angegeben werden müssen. Dies sollte auf "Openid offline_access Onboarding" eingestellt sein.

Sobald die Autorisierungsanfrage gestellt wurde, wird Ihnen der Anmeldebildschirm für die ~.Dimensions.~ Reseller-Portal.

Die Weiterleitung URL sollte nun ein 'Auth Code' erhalten haben, der in Schritt 2 verwendet werden kann.

Beispielanfrage

\/connect/authorize?client_id=987654&response_type=code&state=5ca75bd30&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&scope=open%20id%20offline_access%20onboarding

2. Zugriffs- und Aktualisierungstoken anfordern #

Der 'Auth Code' muss jetzt gegen Zugriffs- und Aktualisierungstoken ausgetauscht werden – https://login.xarios.cloud/connect/token.

  • Access Token wurde verwendet, um auf die Funktionen API zuzugreifen und Onboarding-Anfragen durchzuführen.
  • Refresh Token, verwendet zur Generierung laufender Zugriffstoken

Dies kann erreicht werden, indem man eine POST Anfrage an den Autorisierungsserver stellt, die folgende Elemente enthält:

  • Code: Der in Schritt 1 gesammelte Authentifizierungscode.
  • Grant_Type: Auf authorization_code eingestellt. (Laut der https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type Spezifikation).
  • Client_Id: Das client_id wird beim ersten Anfordern von API bereitgestellt.
  • Client_Secret: Das client_secret wird beim ersten Anforderungszugriff auf API bereitgestellt.
  • Redirect_URI: Dies setzt den Redirect URL der nach der Ausgabe eines Tokens verwendet wird. Der Standard ist https://127.0.0.1:8000.

Beispielanfrage 

NACH /connect/token HTTP/1.1
Inhaltstyp: application/x-www-form-urlencoded
Inhalt-Länge: xx
code=98765&grant_type=code&client_id=123456&client_secret=987654321&redirect_uri=https%3A%2f%2fexample.com%2fauth

Der Authentifizierungsserver validiert die Anfrage und antwortet mit einem Zugriffs- und Aktualisierungstoken:

Beispielantwort 

{\
  "access_token": "AYjcyMzY3ZDhiNmJkNTY",\
  "refresh_token": "RjY2NjM5NzA2OWJjuE7c",\
  "token_type": "Träger",\
  "läuft ab": 5400\
}\

In diesem Stadium solltest du sowohl Zugriffs- als auch Refresh-Token besitzen. Das Zugriffstoken kann verwendet werden, um API Onboarding-Anfragen nach Bedarf durchzuführen.

Für Informationen zur Verwendung der API siehe bitte die API Referenz.

3. Aktualisierung des Zugangstokens #

Die Lebensdauer des Zugriffstokens ist auf 1 Stunde gesetzt. Nach dieser Zeit muss ein neues Zugriffstoken mit dem Aktualisierungstoken generiert werden.

Um eine Benutzerinteraktion zur Erstellung eines neuen Zugriffstokens zu vermeiden, wird ein Aktualisierungstoken verwendet. Das Aktualisierungstoken kann verwendet werden, um ein neues Zugriffstoken anzufordern, wenn das ursprüngliche abgelaufen ist.

Dies kann geschehen, indem man eine POST Anfrage an den Autorisierungsserver stellt, die folgende Elemente enthält (dies ist dasselbe wie Schritt 2, verwendet jedoch den Refresh Token anstelle des Auth Code):

  • Refresh_Token: Die gespeicherte refresh_token Sammlung in Schritt 2.
  • Grant_Type: Verwenden Sie "refresh_token".
  • Client_Id: Das client_id wird beim ersten Anfordern von API bereitgestellt.
  • Client_Secret: Das client_secret wird beim ersten Anforderungszugriff auf API bereitgestellt.

Beispielanfrage

NACH /connect/token HTTP/1.1
Inhaltstyp: application/x-www-form-urlencoded
Inhalt-Länge: xx
refresh_token=RjY2NjM5NzA2OWJjuE7c&grant_type=refresh_token&client_id=123456&client_secret=987654321
Information Circle info
Das Hinzufügen des offline_access zum Scope bei der Anforderung der Autorisierung im Schritt-1-Prozess führt dazu, dass zusammen mit dem initialen Zugriffstoken ein Aktualisierungstoken generiert wird.

Hand Left warning
Refresh-Token verfallen, wenn sie 90 Tage lang nicht verwendet werden. Die Verfallszeit wird jedes Mal, wenn das Refresh-Token verwendet wird, auf 90 Tage zurückgesetzt.

Widerruf von Tokens #

Wenn das Token kompromittiert wird, kann das Zugriffstoken nicht widerrufen werden, das Aktualisierungstoken jedoch schon. Kontaktieren Sie den Support sofort, falls dies passiert, oder deaktivieren Sie die REST API über das Reseller Portal.