Diese Anleitung beschreibt, wie ein Partner Zugriff auf die Daten von RIO-Kunden erhält und wie die Berechtigungen verwaltet werden. Es beschreibt NICHT die Abrechnung, Business APIs oder die Integration der Partneranwendung in den RIO Marktplatz.
Wenn eine Partneranwendung registriert wird, geschieht Folgendes:
client-id und ein client-secret, um seine Anwendung zu initialisieren.Immer wenn ein RIO Kunde eine Anwendung auf dem Marketplace bucht, sendet RIO automatisch relevante Buchungs-Informationen über E-Mail an den Partner. Zu diesen Informationen gehört auch eine integration-id, die erforderlich ist, um den Access-Token für Daten-Abruf im Namen des Kunden, via der RIO-APIs zu erhalten.
RIO betreibt services, die Implementierungen der OAuth 2.1 - und OpenID Connect 1.0-Spezifikationen sowie anderer verwandter Spezifikationen bereitstellen.
Zusätzlich zu den in den genannten Spezifikationen genutzten grant types hat RIO einen speziellen grant type partner_integration eingeführt um das Konzept eines technischen Benutzers für jedes Konto (jeden Kunden), das ein Abonnement für das Partnerprodukt abonniert hat, abzubilden. Der technische Benutzer wird durch eine integration-id eindeutig referenziert.
Dieser Grant-Type darf nur von vertraulichen Clients verwendet werden, die ein client_secret sicher verwalten können.
Parameter:
client_id und client_secret wie in RFC 6749 - Client Password beschriebenpartner_integration
curl \
--user ${client_id}:${client_secret} \
-k \
-d "grant_type=partner_integration&integration_id=${integration_id}" \
https://auth.iam.rio.cloud/oauth/tokenPOST /oauth/token HTTP/1.1 Host: auth.iam.rio.cloud Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded Accept: application/json grant_type=partner_integration&integration_id=58cfbc07-4424-45b5-8638-f24f9f734fcb
Eine Antwort sieht aus wie in RFC 6749 beschrieben.
Die Partneranwendung muss das Access-Token aus der Antwort verwenden, um auf die APIs im Scope zuzugreifen. Ein Refresh-Token wird nicht ausgestellt, da die Partneranwendung jederzeit ein neues Access-Token erhalten kann, wenn sie es benötigt.
Ein Access-Token ist für eine bestimmte Zeit gültig, wie in RFC 6749 - Access Token Response beschrieben, und sollte in dieser Zeit für alle API-Anfragen verwendet werden. Es ist also nicht notwendig, vor jeder Anfrage an eine API ein neues Access-Token anzufragen!
Hier bedeutet:
"access_token": "eyJraWQiOiJjMD...": der zu verwendende Wert des Access-Tokens"expires_in": 3599: der Access-Token ist 3599 Sekunden gültig"exp": 1689068077: der Access-Token ist bis zum Unix-Timestamp 1689068077 (= 2023-07-11 09:34:37 UTC) gültigDas Access-Token ist im HTTP-Header Authorization bei der Anfrage an RIO APIs zu verwenden. Er darf NICHT bei Anfragen an APIs enthalten sein die nicht an RIO APIs gehen.
Der Access Token ist ein JWT wie in RFC 7519 - JSON Web Token (JWT) spezifiziert. Ein JWT hat die Form xxxxx.yyyyy.zzzzz wobei:
xxxxx: JOSE Header (Base64Url codiert)yyyyy: JWS Payload (Base64Url codiert)zzzzz: JWS Signatur (basierend auf Algorithmus der im Header festgelegt ist)Im Regelfall sollten Clients den AccessToken nicht dekodieren müssen. Falls Sie jedoch für Debugging Zwecke jemals den Token dekodieren sollten, verwenden Sie bitte ein lokales programm (e.g. https://github.com/mike-engel/jwt-cli).
Wir raten generell davon ab dafür Online/Browser-Tools zu benutzen. Falls Sie dennoch auf solche Dienste (e.g. https://jwt.io) angewiesen sind, sollten sie niemals den gesamten Token kopieren, sondern lediglich Header und Payload xxxxx.yyyyy. Wenn Sie den gesamten Access Token, inklusive Signatur, mit einer dritten Person/Service teilen, kann diese Person sich für 1h auf der RIO Platform als Ihr Client ausgeben. Alle dadurch eventuell verursachten Schäden würden auf Sie zurückfallen.