Authentifizierungsmechanismus

Bevor Sie beginnen, lesen Sie setup for using the Kaizala Connectors (Einrichten für die Verwendung der Kaizala-Connectors).

Authentifizierung für Kaizala-Connectors

Wir haben einen benutzerdefinierten tokenbasierten Autorisierungsmechanismus implementiert. Dieser Mechanismus verwendet das Konzept der Aktualisierungs- und Zugriffstoken, um die Zugriffsautorisierung für die Kaizala-Plattform-APIs zu verwalten.

• Aktualisierungstoken enthalten die informationen, die zum Abrufen eines neuen Zugriffstokens erforderlich sind. Sie müssen an den Tokendienst übergeben werden, wenn ein Zugriffstoken abläuft oder wenn zum ersten Mal ein Zugriffstoken generiert werden muss. Aktualisierungstoken für Kaizala-Connectors haben eine Ablaufzeit von 365 Tagen.

• Zugriffstoken enthalten die erforderlichen Informationen für den Zugriff auf eine Kaizala-Ressource. Ein Drittanbieterclient muss bei jeder API-Anforderung ein Zugriffstoken an die Kaizala-Plattform übergeben. Zugriffstoken für Kaizala-Connectors haben eine Ablaufzeit von 24 Stunden.

	Details	Generieren von	Ablaufzeit
Aktualisierungstoken	Tragen Sie die informationen, die zum Abrufen eines neuen Zugriffstokens erforderlich sind.	Verschiedene Möglichkeiten zum Generieren von Aktualisierungstoken sind im nächsten Abschnitt unten dokumentiert.	365 Tage
Zugriffstoken	Führen Sie die erforderlichen Informationen für den Zugriff auf eine Kaizala-Ressource mit.	Entwickler verwenden Aktualisierungstoken & anderen Connectordetails, um den Kaizala-API-Endpunkt abzufragen, um Zugriffstoken zu generieren.	24 Stunden

• Aktualisierungstoken können vom Server auf zwei Arten für ungültig erklärt werden– indem neue Aktualisierungstoken für denselben Kaizala-Connector generiert oder der entsprechende Kaizala-Connector vollständig gelöscht wird.

Verschiedene Arten von Aktualisierungstoken

Kaizala-Connectors ermöglichen es Optionen, zwei verschiedene Arten von Aktualisierungstoken zu generieren. Benutzertoken können entweder über Kaizala-Verwaltungsportal oder oAuth generiert werden.

	Zu generierende Tools	Zugriffsbereich	Wer kann generieren?	Details
Gruppentoken	Kaizala-Verwaltungsportal	Ausgewählte Gruppe	Gruppen-/Mandanten-Admin	Mithilfe dieses Tokens können Entwickler Vorgänge ausführen, für die ein Gruppenadministrator über Berechtigungen in dieser Gruppe verfügt.
Benutzertoken	Kaizala-Verwaltungsportal	Alle Gruppen, in denen ein Benutzer Mitglied ist	Beliebiger Benutzer	Wenn der Benutzer Mandant Admin ist, hat dieses Token Zugriff auf Mandantenebene. Für andere kann das Token für den Zugriff auf Gruppen gemäß ihrem Zugriff verwendet werden.
Benutzertoken	Verwenden von OAuth 2.0, Verwenden von APIs	Alle Gruppen, in denen ein Benutzer Mitglied ist	Beliebiger Benutzer	Mit diesem Token können Entwickler Vorgänge für alle Gruppen ausführen.

• Bei Benutzertoken bietet ein einzelnes Token Zugriff auf alle Gruppen, zu der ein Benutzer gehört.
• Für einen einzelnen Connector können Entwickler Token für mehrere Gruppen generieren.

Kaizala bietet zwei weitere Methoden zum programmgesteuerten Generieren von Aktualisierungstoken.

• Verwenden der API (wird in Kürze hinzugefügt)
• Verwenden von OAuth (wird in Kürze hinzugefügt)

Sobald das Aktualisierungstoken von Group-Admin oder einem Benutzer für den Entwickler bereitgestellt wurde, sollte es zum Generieren des Zugriffstokens verwendet werden.

Methoden zum Generieren von Zugriffstoken

Als Entwickler verfügen Sie jetzt über eine Connector-ID, ein Geheimnis und ein Aktualisierungstoken, die an Sie übergeben werden sollten. Damit können Sie ein Zugriffstoken generieren.

Kaizala bietet zwei Methoden zum Generieren von Zugriffstoken.

• Verwenden der API
• Verwenden von OAuth

Generieren eines Zugriffstokens mithilfe der API

Die Stammdomäne zum Aufrufen der Kaizala-APIs lautet:

https://api.kaiza.la/v1/

Sie müssen den folgenden Endpunkt verwenden, um ein Zugriffstoken abzurufen (das erste Mal & später, wenn das Zugriffstoken abläuft):

GET https://{api_root}/accessToken

Anforderungsparameter

	Parameter	Typ	Optional?	Beschreibung
HTTP-Header	applicationId	Zeichenfolge	Nein	ID, die dem Connector zugeordnet ist
HTTP-Header	applicationSecret	Zeichenfolge	Nein	Geheimnis, das dem Connector zugeordnet ist
HTTP-Header	refreshToken	Zeichenfolge	Nein	RefreshToken, das von der Kaizala-Gruppe Admin freigegeben wurde, wenn dem jeweiligen Connector Zugriff auf die Gruppe gewährt wurde

Antworttext

Parameter	Typ	Beschreibung
accessToken	Zeichenfolge	Bei erfolgreicher Authentifizierung wird ein Anwendungstoken zurückgegeben, das für nachfolgende API-Aufrufe verwendet werden kann.
endpointUrl	Zeichenfolge	Bei erfolgreicher Authentifizierung wird eine Endpunkt-URL zurückgegeben, die als api-base-url für nachfolgende API-Aufrufe verwendet werden soll.
accessTokenExpiry	Long	Gibt die Ablaufzeit für accessToken in Epochenzeit (Millisekunden) an.
refreshToken	Zeichenfolge	Nach Ablauf von 328 Tagen (90 % der Gültigkeit des Aktualisierungstokens) wird das neue refreshToken zurückgegeben, das zum Generieren von accessToken verwendet werden soll. Andernfalls funktioniert der Connector nicht mehr, nachdem die Gültigkeit des aktuellen Aktualisierungstokens abgelaufen ist. Der Wert ist Null, bis 90 % der Gültigkeit des aktuellen RefreshTokens abläuft.
scope	Zeichenfolge	Berechtigungssatz, mit dem der Connector bereitgestellt wird

JSON-Beispielantwort

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cm46bWljcm9zb2Z0OmNyZWRlbnRpYWxzIjoie1wicGhvbmVOdW1iZXJcIjpcIis5MTk1NTAwMDAxMTZcIixcImNJZFwiOlwiXCIsXCJ0ZXN0U2VuZGVyXCI6XCJmYWxzZVwiLFwiYXBwTmFtZVwiOlwiY29tLm1pY3Jvc29mdC5tb2JpbGUua2FpemFsYWFwaVwiLFwiYXBwbGljYXRpb25JZFwiOlwiOTExMDY3RTE4QUUCJ2ZXIiOiIyIiwibmJmIjoxNTE0ODgxNjg2LCJleHAiOjE1MTg0ODE2ODYsImlhdCI6MTUxNDg4MTY4NiwiaXNzIjoidXJuOm1pY3Jvc29mdDp3aW5kb3dzLWF6dXJlOnp1bW8iLCJhdWQiOiJ1cm46bWljcm9zb2Z0OndpbmRvd3MtYXp1cmU6enVtbyJ9.fHbIHHTdzoDYT-QIPMu6Oit6x3JMT78LSm50o5cA-N8",
    "endpointUrl": "https://kms-alpha.kaiza.la/",
    "accessTokenExpiry": 1518481686294,
    "refreshToken": "",
    "scope": "token.write"
}

Generieren eines Zugriffstokens mit oAuth 2.0

Schritte zum Generieren eines Zugriffstokens mit oAuth 2.0

• Schritt 1: Erstellen/Aktualisieren eines Connectors auf Kaizala-Verwaltungsportal, um die Umleitungs-URL einzuschließen

  • Vergewissern Sie sich im verwendeten Connector, dass Sie beim Erstellen des Connectors eine Umleitungs-URL eingegeben haben. Wenn nicht, aktualisieren Sie die Umleitungs-URL.

  • Zu Testzwecken können Sie die folgende Postman-Rückruf-URL verwenden, die Ihnen nur eine Seite mit dem Code bietet. 

    https://www.getpostman.com/oauth2/callback

• Schritt 2: Geben Sie unten die URL im Browser ein, und drücken Sie die EINGABETASTE.

   `https://ds.kaiza.la/api/Oauth/Authorize?client_id={{ConnectorID}}&redirect_uri={{re-directURL}}`
  

  • Stellen Sie sicher, dass Sie "client_id" & "redirect_uri" richtig eingegeben haben.

  Anforderungsparameter

  	Parameter	Typ	Optional?	Beschreibung
  URL-Parameter	client_id	Zeichenfolge	Nein	ID, die dem Connector zugeordnet ist
  URL-Parameter	redirect_uri	Zeichenfolge	Nein	Geheimnis, das dem Connector zugeordnet ist

  • Beispiel-URL wäre z. B.

    https://ds.kaiza.la/api/Oauth/Authorize?client_id=2AB9B82044683484EE9D958E7&redirect_uri=https://www.getpostman.com/oauth2/callback

• Schritt 3: Melden Sie sich bei Kaizala an, und generieren Sie "Code".

  • Sobald Sie in Schritt 2 die EINGABETASTE drücken, werden Sie zur Kaizala-Anmeldeseite weitergeleitet.
  • Authentifizieren Sie sich mit Ihrer registrierten Kaizala-Nummer
  • Nachdem Sie sich erfolgreich angemeldet haben, werden Sie mit "code" als Abfrageparameter in der Rückruf-URL erneut zur url für die erneute Weiterleitung weitergeleitet.
  • Notieren Sie sich den zurückgegebenen "Code".

• Schritt 4: Verwenden von Code zum Generieren von Zugriffstoken

  • Führen Sie den folgenden API-Aufruf aus, um Zugriffstoken zu generieren.

    POST https://ds.kaiza.la/api/oauth/token 

  Anforderungsparameter

  	Parameter	Typ	Optional?	Beschreibung
  HTTP-Header	Content-Type	Zeichenfolge	Nein	Zulässiger Wert: application/x-www-form-urlencoded
  Body-Parameter	client_id	Zeichenfolge	Nein	ID, die dem Connector zugeordnet ist
  Body-Parameter	client_secret	Zeichenfolge	Nein	Geheimnis, das dem Connector zugeordnet ist
  Body-Parameter	code	Zeichenfolge	Nein	Code, der im Abfrageparameter der url für die erneute Weiterleitung zurückgegeben wurde

Sie erhalten accessToken, endpointUrl, accessToken Expiry als Teil der Antwort.

Antworttext

Parameter	Typ	Beschreibung
accessToken	Zeichenfolge	Bei erfolgreicher Authentifizierung wird ein Anwendungstoken zurückgegeben, das für nachfolgende API-Aufrufe verwendet werden kann.
endpointUrl	Zeichenfolge	Bei erfolgreicher Authentifizierung wird eine Endpunkt-URL zurückgegeben, die als api-base-url für nachfolgende API-Aufrufe verwendet werden soll.
accessTokenExpiry	Long	Gibt die Ablaufzeit für accessToken in Epochenzeit (Millisekunden) an.
refreshToken	Zeichenfolge	Nach Ablauf von 328 Tagen (90 % der Gültigkeit des Aktualisierungstokens) wird das neue refreshToken zurückgegeben, das zum Generieren von accessToken verwendet werden soll. Andernfalls funktioniert der Connector nicht mehr, nachdem die Gültigkeit des aktuellen Aktualisierungstokens abgelaufen ist. Der Wert ist Null, bis 90 % der Gültigkeit des aktuellen RefreshTokens abläuft.
scope	Zeichenfolge	Berechtigungssatz, mit dem der Connector bereitgestellt wird

JSON-Beispielantwort

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cm46bWljcm9zb2Z0OmNyZWRlbnRpYWxzIjoie1wicGhvbmVOdW1iZXJcIjpcIis5MTk1NTAwMDAxMTZcIixcImNJZFwiOlwiXCIsXCJ0ZXN0U2VuZGVyXCI6XCJmYWxzZVwiLFwiYXBwTmFtZVwiOlwiY29tLm1pY3Jvc29mdC5tb2JpbGUua2FpemFsYWFwaVwiLFwiYXBwbGljYXRpb25JZFwiOlwiOTExMDY3RTE4QUUCJ2ZXIiOiIyIiwibmJmIjoxNTE0ODgxNjg2LCJleHAiOjE1MTg0ODE2ODYsImlhdCI6MTUxNDg4MTY4NiwiaXNzIjoidXJuOm1pY3Jvc29mdDp3aW5kb3dzLWF6dXJlOnp1bW8iLCJhdWQiOiJ1cm46bWljcm9zb2Z0OndpbmRvd3MtYXp1cmU6enVtbyJ9.fHbIHHTdzoDYT-QIPMu6Oit6x3JMT78LSm50o5cA-N8",
    "endpointUrl": "https://kms-alpha.kaiza.la/",
    "accessTokenExpiry": 1518481686294,
    "refreshToken": "",
    "scope": "token.write"
}

Weiter: API-Dokumentation