Vorbereitung einer authentifizierten Anfrage an die API

Nach dem Erstellen und Konfigurieren eines Service-Kontos muss Ihre Anwendung die folgenden Schritte durchführen:

1. Erstellen Sie ein JSON Web Token (JWT), das den Header, den Payload und die Signatur enthält;
2. Fordern Sie ein Zugriffstoken (AccessToken) von der OAuth2-Authentifizierungsplattform an;
3. Verarbeiten Sie die JSON-Antwort, die die Authentifizierungsplattform zurückgibt.

Wenn die Antwort ein Zugriffstoken enthält, können Sie es verwenden, um Anfragen an die Produkt-APIs von Unico zu stellen, für die das Service-Konto Zugriffsberechtigungen hat. (Wenn die Antwort kein Zugriffstoken enthält, sind Ihr JWT und Ihre Token-Anfrage möglicherweise fehlerhaft, oder das Service-Konto verfügt nicht über die erforderlichen Berechtigungen für den Zugriff auf die angeforderten Ressourcen.)

Das in der oben genannten Anfrage generierte Zugriffstoken hat standardmäßig eine Gültigkeit von 3600 Sekunden, dies kann jedoch je nach der für Ihr Unternehmen festgelegten Sicherheitskonfiguration variieren. Wenn das Zugriffstoken abläuft, sollte Ihre Anwendung ein neues JWT generieren, es signieren und ein neues Zugriffstoken von der Authentifizierungsplattform anfordern.

1 — Erstellen des JWT

Ein JWT besteht aus drei Teilen: einem Header, einem Payload und einer Signatur. Der Header und der Payload sind JSON-Objekte. Diese JSON-Objekte werden in UTF-8 serialisiert und dann mit Base64url-Kodierung¹ kodiert. Diese Kodierung bietet Widerstandsfähigkeit gegenüber Kodierungsänderungen bei wiederholten Kodierungsvorgängen. Der Header, der Payload und die Signatur werden mit einem Punktzeichen (.) verkettet.

Ein JWT ist wie folgt aufgebaut:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

Der Basistext für die Signatur ist wie folgt aufgebaut:

{Header in Base64url}.{Payload in Base64url}

1.1 — Bildung des JWT-Headers

Der Header besteht aus zwei Feldern, die den Signaturalgorithmus und das Token-Format angeben. Beide Felder sind Pflichtfelder, und jedes Feld hat nur einen Wert. Service-Konten verwenden den RSA-SHA-256-Algorithmus und das JWT-Token-Format. Daher sieht die JSON-Darstellung des Headers wie folgt aus:

{"alg":"RS256","typ":"JWT"}

Die Base64url-Darstellung lautet wie folgt:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 — Bildung des JWT-Payloads

Der JWT-Payload enthält Informationen über das JWT, einschließlich der angeforderten Berechtigungen (Scopes), des Kontos, das den Zugriff anfordert, des Ausstellers, des Zeitpunkts der Token-Ausstellung und der Gültigkeitsdauer des Tokens. Die meisten Felder sind Pflichtfelder. Genau wie der JWT-Header ist der Payload ein JSON-Objekt und wird bei der Erstellung der Signatur verwendet.

1.3 — Pflichtfelder

Die Pflichtfelder im JWT sind in der folgenden Tabelle dargestellt. Sie können in beliebiger Reihenfolge im Payload erscheinen.

Name	Beschreibung
iss	Die Kennung des Service-Kontos innerhalb des Unternehmens.
scope	Eine durch Leerzeichen oder Pluszeichen (+) getrennte Liste der Berechtigungen, die die Anwendung anfordert. Wenn alle Berechtigungen des Kontos benötigt werden, verwenden Sie dafür das Sternchen-Symbol (*).
aud	Die Adresse der Authentifizierungsplattform, die Zugriffstoken ausstellt. Dieser Wert sollte immer genau https://identityhomolog.acesso.io lauten. Häufige Probleme, die nicht funktionieren: das Hinzufügen eines abschließenden Schrägstrichs (https://identityhomolog.acesso.io/) oder die Verwendung von HTTP statt HTTPS.
exp	Der Ablaufzeitpunkt des Tokens, angegeben in Sekunden seit 00:00:00 UTC, 1. Januar 1970. Dieser Wert hat eine maximale Dauer von 1 Stunde nach dem Zeitpunkt der JWT-Ausstellung. Er muss numerisch sein — ein in Anführungszeichen gesetzter Wert wie "1524161193" ist eine Zeichenkette und funktioniert nicht; 1524161193 ist eine Zahl und funktioniert.
iat	Der Zeitpunkt der JWT-Ausstellung, angegeben in Sekunden seit 00:00:00 UTC, 1. Januar 1970. Dieser Wert muss numerisch sein, gleiche Regel wie bei exp.

Das Feld iat muss die aktuelle Zeit im erforderlichen Format darstellen, und das Feld exp muss die folgende Berechnung berücksichtigen:

exp = iat + 3600

Die Darstellung der Pflicht-JSON-Felder im JWT-Payload sieht wie folgt aus:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

1.4 — Berechnung der Signatur

Die Spezifikation **JSON Web Signature (JWS)**² ist der Mechanismus, der die Berechnung der Signatur für ein JWT vorgibt. Der Eingabeinhalt für die Signaturberechnung ist das Byte-Array des folgenden Inhalts:

{Header in Base64url}.{Payload in Base64url}

Für die Berechnung der Signatur muss derselbe Algorithmus verwendet werden, der im JWT-Header angegeben ist. Der einzige von der OAuth2-Authentifizierungsplattform unterstützte Signaturalgorithmus ist RSA mit SHA-256, ausgedrückt als RS256 im Feld alg des JWT-Headers.

Signieren Sie die UTF-8-Darstellung des Eingabeinhalts mit SHA256withRSA (auch bekannt als RSASSA-PKCS1-V1_5-SIGN mit dem SHA-256-Hash) unter Verwendung des privaten Schlüssels, der erstellt und mit dem Service-Konto verknüpft wurde (die Datei .key.pem, die aus der per E-Mail erhaltenen Anfrage generiert wurde). Der Ausgabeinhalt ist ein Byte-Array.

Die Signatur muss dann in Base64url kodiert werden. Der Header, der Payload und die Signatur sollten mit einem Punktzeichen verkettet werden. Das Ergebnis ist das JWT.

Es ist auch möglich, vorhandene Bibliotheken zur Erstellung des JWT zu verwenden. Als Referenz finden Sie eine Liste von Bibliotheken auf der Website jwt.io.

2 — Anfordern eines Zugriffstokens

Nach der Erstellung des signierten JWT kann eine Anwendung es verwenden, um ein Zugriffstoken anzufordern. Die Zugriffstoken-Anfrage ist eine POST-HTTPS-Anfrage, und der Body sollte URL-kodiert sein. Die URL wird unten angezeigt:

https://identityhomolog.acesso.io/oauth2/token

Die folgenden Parameter sind in der POST-HTTPS-Anfrage erforderlich:

Name	Beschreibung
grant_type	Verwenden Sie den folgenden Text, bei Bedarf URL-kodiert: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Das JWT, einschließlich der Signatur.

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>

3 — Verarbeitung der Antwort der Authentifizierungsplattform

Wenn das JWT und die Zugriffstoken-Anfrage ordnungsgemäß erstellt wurden und das Service-Konto über die erforderlichen Berechtigungen verfügt, gibt die Authentifizierungsplattform ein JSON-Objekt zurück, das ein Zugriffstoken enthält:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

Das im Feld access_token des JSON-Objekts zurückgegebene Zugriffstoken ist ebenfalls ein JWT-Token, das in den APIs der Produkte von Unico verwendet werden sollte. Tritt bei der Anfrage ein Fehler auf, prüfen Sie den Fehlertyp unter Authentifizierungsfehler.

4 — Gültigkeitsdauer des Zugriffstokens

Die Gültigkeitsdauer des Zugriffstokens ist variabel. Ihre Dauer wird im Feld expires_in angegeben, das zusammen mit dem Zugriffstoken zurückgegeben wird. Dasselbe Zugriffstoken sollte während seiner gesamten Gültigkeitsdauer für alle API-Aufrufe an die Produkte verwendet werden.

Fordern Sie kein neues Zugriffstoken an, bevor die Gültigkeit des aktuellen Tokens sich nicht dem Ende nähert. Wir empfehlen einen Spielraum von 600 Sekunden (10 Minuten):

new Date((token.exp - 600) * 1000)

Wobei token.exp der Zeitstempel des Ablaufs des Tokens ist.

Hinweis

Standardmäßig ist das an das Unternehmen gesendete Token 1 Stunde gültig, dies kann jedoch geändert werden. Die Empfehlung ist, immer expires_in als Basis zu verwenden und davon 600s abzuziehen, um ein neues Token anzufordern.

Beispiele:

Standardszenario:
expires_in: 3600 (1h) - Token generiert um 14:42
Fordern Sie ein neues Token erst um 15:32 an, das heißt 14:42 + (3600 - 600)

Szenario mit geänderter Dauer:
expires_in: 7200 (2h) - Token generiert um 14:42
Fordern Sie ein neues Token erst um 16:32 an, das heißt 14:42 + (7200 - 600)

Warnung

Verwenden Sie keine feste Zeit, um ein neues Token zu erhalten, da die Gültigkeitsdauer des erhaltenen Tokens kürzer sein kann als die festgelegte Zeit, was zu Fehlern bei der Nutzung der Dienste führen könnte.

---

¹ Gemäß RFC 4648 für die BaseN-Kodierung ähnelt das Base64url-Format Base64, mit der Ausnahme, dass das Zeichen = weggelassen wird und die Zeichen + und / durch - bzw. _ ersetzt werden. ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.