JWT-OAuth-Tokens verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

.

In diesem Thema wird erläutert, wie Sie JWT-Zugriffstokens mithilfe der OAuthV2-Richtlinie generieren, verifizieren und aktualisieren.

Einführung

Die JWT-Vorgänge ermöglichen es der OAuthV2-Richtlinie, Zugriffstoken zu generieren, zu prüfen und zu aktualisieren, die dem IETF RFC 9068 entsprechen, ein Standard, der beschreibt, wie Zugriffstoken im JWT-Format ausgegeben werden. JWTs werden häufig zum Freigeben von Anforderungen oder Assertions für verbundene Anwendungen verwendet. Das Ausstellen von OAuthV2-Zugriffstokens im JWT-Format ist eine Alternative zur Ausgabe intransparenter Zugriffstokens.

Bei der Konfiguration für JWT generiert die OAuthV2-Richtlinie ein Base64-codiertes JWT, das aus einem Header, einer Nutzlast und einer durch Punkte getrennten Signatur besteht, und gibt dieses zurück. Beispiel:

Abbildung 1: Serialisiertes JWT-Format, das aus Header, Nutzlast und Signatur besteht, die durch Punkte getrennt sind.

Der codierte Inhalt dieser Elemente hängt davon ab, wie Sie die OAuthV2-Richtlinie konfigurieren. In der Richtlinie geben Sie solche Parameter wie den Signaturalgorithmus und Nutzlastelemente wie Betreff und Name an. Beispielsweise kann der Header als {"alg":"HS256","typ":"at+JWT"} und die Nutzlast als {"sub":"ABC1234567","iat":1516239022} decodiert werden.

Der Header gibt eine typ-Anforderung (immer "at+JWT) und die alg-Anforderung an, die den Algorithmus angeben, der zum Signieren des JWT verwendet wird. Apigee unterstützt RSA- und HMAC-Algorithmen: RS(256,384,512) und HS(256,384,512).

Nutzlast

Die Nutzlast besteht aus Anforderungen an die Entität. Einige Anforderungen müssen in der Richtlinienkonfiguration angegeben werden, während andere automatisch von der Apigee-Laufzeit generiert werden. Die Richtlinie unterstützt die folgenden Anforderungen:

Anspruch Beschreibung Bereitgestellt von
iss Der Tokenaussteller. Dieser Wert wird so festgelegt: (http|https)://{domain-name-for-proxy}/{proxy-basePath}. Beispiel: https://api.mycompany.com/auth/v2 Apigee
sub Entweder die Client-ID oder die ID des Ressourceninhabers (im Fall von Kennwort- oder Autorisierungsberechtigungen). Wenn der Parameter appEndUserId in der Anfrage angegeben ist, wird dieser Wert als Ressourceninhaber-ID verwendet. Sie können steuern, wo dieser Wert festgelegt wird. Verwenden Sie dazu das Element <AppEndUser> der OAuthV2-Richtlinie. API-Entwickler
jti Eine eindeutige ID, die als UUID-gestützter zufälliger String dargestellt wird, um das Token eindeutig zu identifizieren. Apigee
exp Die Ablaufzeit, d. h. die Zeit, nach der das Token als ungültig betrachtet werden muss. Der Wert wird in Epochenzeit (in Sekunden) ausgedrückt. Apigee
iat Der Zeitpunkt, zu dem das Token erstellt wurde. Der Wert wird in Epochenzeit (in Sekunden) ausgedrückt. Apigee
client_id Die eindeutige ID der Clientanwendung. API-Entwickler
scope Der OAuth-Bereich, der dem Token zugewiesen ist. Siehe auch Mit OAuth-Bereichen arbeiten. API-Entwickler

Signatur

Die Signatur wird mit dem codierten Header, der Nutzlast, dem Secret/privaten Schlüssel und dem Algorithmus generiert. Die Signatur sorgt dafür, dass der Inhalt des Tokens nicht manipuliert wurde.

Weitere Informationen zu OAuth 2.0-Zugriffstokens im JWT-Format finden Sie unter IETF RFC 9068: JSON Web Token (JWT)-Profil für OAuth 2.0-Zugriffstoken.

Vorbereitung

In diesem Dokument wird davon ausgegangen, dass Sie wissen, wie Sie OAuthV2-Zugriffstokens mithilfe der OAuthV2-Richtlinie generieren und überprüfen. Unabhängig davon, ob Sie die JWT-Vorgänge oder die herkömmlichen Vorgänge, die intransparente Stringtoken erstellen, verwenden, ist die grundlegende Verwendung der OAuthV2-Richtlinie identisch. Sie können JWT-Zugriffstokens mit allen unterstützten OAuthV2-Berechtigungstypen verwenden. Weitere Informationen finden Sie unter Einführung in OAuth 2.0.

Wird generiert

Generieren Sie mit den Vorgängen GenerateJWTAccessToken und GenerateJWTAccessTokenImplicitGrant ein JWT-Zugriffstoken mit der OAuthV2-Richtlinie. Diese Vorgänge sind den herkömmlichen Vorgängen GenerateAccessToken und GenerateAccessTokenImplicitGrant der Richtlinie ähnlich. Der Hauptunterschied besteht darin, dass der JWT-Vorgang ein JWT-formatiertes Zugriffstoken anstelle eines intransparenten String-Tokens zurückgibt. Siehe auch OAuth 2.0-Tokens abrufen.

Die folgenden Beispiele zeigen, wie diese Vorgänge in der OAuthV2-Richtlinie verwendet werden. In den Beispielen wird der Berechtigungstyp client_credentials verwendet. Sie können für diese Vorgänge jedoch jeden der unterstützten Berechtigungstypen verwenden.

Token mit einem JWT-Format generieren, das mit einem HMAC-Algorithmus signiert wurde

Geben Sie das Element <Algorithm> mit einem der HMAC-Algorithmen (HS256/HS384/HS512) an. Geben Sie auch <SecretKey> an. Das folgende Beispiel zeigt eine Richtlinie, die zum Generieren eines JWT konfiguriert ist, das mit dem HS512-Algorithmus mithilfe des angegebenen geheimen Schlüssels signiert wurde. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Token mit einem JWT-Format generieren, das mit einem RSA-Algorithmus signiert wurde

Geben Sie einen der RSA-Algorithmen (einen von RS256/RS384/RS512) im Element <Algorithm> an und geben Sie den privaten Schlüssel im Element <PrivateKey> an. Das folgende Beispiel zeigt eine Richtlinie, die für die Generierung eines mit dem privaten RSA-Schlüssel signierten JWT mithilfe des RS256-Algorithmus konfiguriert wurde. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Token im JWT-Format mit dem impliziten Berechtigungstyp generieren

Der Vorgang GenerateJWTAccessTokenImplicitGrant generiert ein JWT-Zugriffstoken mit dem impliziten Berechtigungstyp. Das Token erhält den impliziten Berechtigungstyp automatisch. Daher ist das Element <SupportedGrantTypes> nicht erforderlich. Da es sich um ein JWT handelt, ist das Element <Algorithm> erforderlich. Das folgende Beispiel zeigt die Verwendung des RS256-Algorithmus. Aus diesem Grund ist das Element <PrivateKey> erforderlich. Weitere Informationen finden Sie unter Implizierten Berechtigungstyp verwenden. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Wird überprüft

Verwenden Sie den Vorgang VerifyJWTAccessToken, um ein JWT-Zugriffstoken mit der OAuthV2-Richtlinie zu prüfen. Dieser Vorgang ähnelt dem Vorgang VerifyAccessToken. Der Unterschied besteht darin, dass VerifyJWTAccessToken für Tokens im JWT-Format und VerifyAccessToken für intransparente Tokens gilt.

Mit einem HMAC-Algorithmus signiertes JWT-Zugriffstoken verifizieren

Das folgende Beispiel zeigt, wie die OAuthV2-Richtlinie konfiguriert wird, um ein mit dem HS512-Algorithmus signiertes JWT-Token zu prüfen. Wenn Sie den Vorgang VerifyJWTAccessToken mit einem HMAC-Algorithmus verwenden, muss die Richtlinienkonfiguration das Element <SecretKey> verwenden, um den geheimen Schlüssel anzugeben, mit dem das JWT signiert wurde. 

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

Mit einem RSA-Algorithmus signiertes JWT-Zugriffstoken verifizieren

Das folgende Beispiel zeigt, wie die OAuthV2-Richtlinie konfiguriert wird, um ein mit dem RS512-Algorithmus signiertes JWT-Token zu prüfen. Wenn Sie den VerifyJWTAccessToken-Vorgang mit einem RSA-Algorithmus verwenden, muss die Richtlinienkonfiguration das Element <PublicKey> verwenden, um den öffentlichen Schlüssel anzugeben, der dem privaten Schlüssel entspricht, der zum Signieren des JWT verwendet wurde. 

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

Wird aktualisiert

Verwenden Sie den Vorgang RefreshJWTAccessToken, um ein JWT-Zugriffstoken zu aktualisieren. Dieser Vorgang ähnelt dem herkömmlichen RefreshAccessToken-Vorgang der Richtlinie. Weitere Informationen finden Sie unter Zugriffstoken aktualisieren.

HMAC-signiertes Zugriffstoken aktualisieren

Das folgende XML-Beispiel zeigt, wie die OAuthV2-Richtlinie so konfiguriert wird, dass ein JWT-Token aktualisiert wird, das mit einem HMAC-Algorithmus signiert wurde. In diesem Fall sind die Elemente <SecretKey> und <Algorithm> erforderlich.

Die Antwort des Aktualisierungsvorgangs ähnelt der Antwort eines neu generierten Tokens. Der Aktualisierungsvorgang generiert ein neues JWT-Token mit einer aktualisierten Ablaufzeit, wobei andere Anforderungen gleich bleiben. 

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Mit RSA signiertes JWT-Zugriffstoken aktualisieren

Das folgende Richtlinienbeispiel zeigt, wie die OAuthV2-Richtlinie so konfiguriert wird, dass ein JWT-Token aktualisiert wird, das mit einem RSA-Algorithmus signiert wurde. Weitere Informationen finden Sie unter Zugriffstoken aktualisieren. 

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Beispiel für eine Tokenantwort

Sowohl beim Generieren als auch beim Aktualisieren sieht der Antworttext ähnlich aus wie im folgenden Beispiel. Beachten Sie, dass access_token als serialisiertes JWT dargestellt wird und das Aktualisierungstoken ein herkömmliches intransparentes Token ist. 

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

Zusammenfassung der erforderlichen Richtlinienelemente

In der folgenden Tabelle werden JWT-spezifische Elemente beschrieben, die in den vorherigen Beispielen verwendet wurden:

Element Typ Hinweise
Algorithmus Statischer Wert Gibt den Algorithmus an, der zum Signieren des Tokens verwendet wird.
SecretKey Referenzwert Stellt den geheimen Schlüssel bereit, mit dem Tokens mit einem HMAC-Algorithmus verifiziert oder signiert werden: HS (256/384/512).
PrivateKey Referenzwert Stellt den privaten Schlüssel bereit, mit dem das Token generiert wird. Nur verwenden, wenn der Algorithmus ein RSA-Algorithmus ist: RS (256/384/512).
PublicKey Referenzwert Stellt den öffentlichen Schlüssel bereit, mit dem das Token verifiziert wird. Nur verwenden, wenn der Algorithmus ein RSA-Algorithmus ist: RS (256/384/512).

Nicht unterstützte Richtlinienelemente

Die folgenden OAuthV2-Richtlinienelemente werden bei Konfigurationen von JWT-Tokens nicht unterstützt:

Element Hinweise
ExternalAuthorization Beim Generieren eines JWT-Zugriffstokens validiert die OAuthV2-Richtlinie die Client-ID und das Secret.
ExternalAccessToken Wenn ein JWT-Zugriffstoken generiert wird, wird es von Apigee signiert und die Anforderungen werden von Apigee entweder standardmäßig oder über die Richtlinienkonfiguration bereitgestellt. Die Richtlinie unterstützt ExternalRefreshToken, was bei Migrationsanwendungsfällen hilfreich sein kann.
RFCCompliantRequestResponse Das Generieren und Aktualisieren von JWT-Zugriffstokens ist standardmäßig RFC-konform.

Verwendungshinweise

  • Verschlüsselte JWTs werden nicht unterstützt.
  • Neben einem JWT-Zugriffstoken enthält die Richtlinienantwort auch ein intransparentes Aktualisierungstoken für Berechtigungstypen, in denen Aktualisierungstokens unterstützt werden. Nur die Bewährungstypen "Passwort" und "Autorisierungscode" unterstützen Aktualisierungstokens.
  • Fügen Sie den Autorisierungsheader in Anfragen ein, die an den Proxy mit der OAuthV2-Richtlinie gesendet werden.
  • Sie können ein JWT-Zugriffstoken nicht widerrufen. Das generierte JWT-Token bleibt so lange gültig, bis es abläuft. Sie können ein Aktualisierungstoken widerrufen, das mit einem JWT-Zugriffstoken verknüpft ist.
  • Das Erstellen, Verifizieren und Aktualisieren von Zugriffstokens muss von Apigee erfolgen. Obwohl eine externe Anwendung oder ein Gateway, das Zugriff auf den öffentlichen oder geheimen Schlüssel hat, den Inhalt des JWT decodieren kann, enthält die externe Anwendung keine Informationen zu den API-Produkten, die durch die Anforderung client_id identifiziert werden, und kann daher bei der API-Proxy-Autorisierung keine Rolle spielen.