Übersicht über JWS- und JWT-Richtlinien

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Dieses Thema enthält allgemeine Informationen zu JWT (JSON Web Token) und JWS (JSON Web Signature) und den Apigee JWS/JWT-Richtlinien, die für Apigee-Proxy-Entwickler von Interesse sein können.

Einführung

Sowohl JWS als auch JWT werden häufig verwendet, um Ansprüche oder Assertions zwischen verbundenen Anwendungen auszutauschen. Die JWS/JWT-Richtlinien ermöglichen Apigee API-Proxys Folgendes:

• Erstellen Sie ein signiertes JWT oder JWS.
• Bestätigen Sie ein signiertes JWT oder JWS und Ansprüche innerhalb des JWS/JWT.
• Decodieren Sie ein signiertes JWT oder JWS, ohne die Signatur zu validieren.

In den beiden letzteren Fällen legt die Richtlinie auch Variablen fest, die zusätzliche Richtlinien oder die Back-End-Dienste selbst ermöglichen, um die validierten Ansprüche zu prüfen und Entscheidungen basierend auf diesen Anforderungen zu treffen.

Bei Verwendung der JWS/JWT-Richtlinie wird eine ungültige JWS/JWT abgelehnt, die zu einer Fehlerbedingung führt. Entsprechend führt die Verwendung der Decode-JWS/JWT-Richtlinie zu einer fehlerhaften JWS/JWT-Datei, die zu einer Fehlerbedingung führt.

Videos

In einem kurzen Video finden Sie eine schnelle Einführung in JWT. Obwohl dieses Video speziell für die Generierung eines JWT gedacht ist, sind viele der Konzepte für JWS identisch.

In diesem kurzen Video erfahren Sie mehr über die JWT-Struktur.

Anwendungsfälle

Sie können die JWS/JWT-Richtlinien für Folgendes verwenden:

• Generieren Sie ein neues JWS/JWT auf den Proxy- oder Zielendpunktseiten eines Apigee-Proxys. Sie können beispielsweise einen Proxy-Anfragefluss erstellen, der ein JWS/JWT generiert und an einen Client zurückgibt. Sie haben auch die Möglichkeit, einen Proxy so zu erstellen, dass er ein JWS/JWT im Zielanforderungsablauf generiert und ihn an die an das Ziel gesendete Anfrage anpasst. Diese Ansprüche wären dann verfügbar, damit Back-End-Dienste die weitere Sicherheitsverarbeitung anwenden können.
• Prüfen und extrahieren Sie Anforderungen aus einem JWS/JWT, die Sie von eingehenden Clientanfragen, von Zieldienstantworten, von Service-Callout-Richtlinienantworten oder aus anderen Quellen erhalten haben. Apigee überprüft die Signatur auf einem JWS/JWT, unabhängig davon, ob das JWS/JWT von einem Drittanbieter oder von Apigee selbst unter Verwendung von RSA- oder HMAC-Algorithmen generiert wurde.
• JWS/JWT decodieren Die Decodierung ist besonders nützlich, wenn sie in Verbindung mit der Richtlinie "JWS/JWT überprüfen" verwendet wird, wenn der Wert einer Anforderung (JWT) oder eines Headers (JWS/JWT) aus der JWS/JWT vor der Verifizierung des JWS/JWT bekannt sein muss.

Bestandteile eines JWS/JWT

Ein signiertes JWS/JWT codiert Informationen in drei Teile, die durch Punkte getrennt sind: Header, Nutzlast und die Signatur:

header.payload.signature

• Die Richtlinie "JWS/JWT generieren" erstellt alle drei Teile.
• Die JWS/JWT-Richtlinie prüft alle drei Teile.
• Die Decode JWS/JWT-Richtlinie prüft nur den Header und die Nutzlast.

Ein JWS unterstützt auch ein getrenntes Format, bei dem die Nutzlast vom JWS weggelassen wird:

header..signature

Bei einem getrennten JWS wird die Nutzlast getrennt vom JWS gesendet. Verwenden Sie das Element <DetachedContent> der JWS-Richtlinie, um die nicht codierte, unverschlüsselte JWS-Nutzlast anzugeben. Die JWS-Richtlinie überprüft dann die JWS mithilfe des Headers und der Signatur in der JWS und der durch das Element <DetachedContent> angegebenen Nutzlast.

Weitere Informationen zu Tokens und dazu, wie sie codiert und signiert werden, finden Sie unter:

• JWT: IETF RFC7519
• JWS: IETF RFC7515

Unterschiede zwischen JWS und JWT

Sie können entweder ein JWT oder JWS verwenden, um Anforderungen oder Assertions für verbundene Anwendungen zu teilen. Der Hauptunterschied zwischen den beiden Funktionen ist die Darstellung der Nutzlast:

• JWT
  • Die Nutzlast ist immer ein JSON-Objekt.
  • Die Nutzlast wird immer mit dem JWT verknüpft.
  • Der Header typ des Tokens ist immer auf JWT.
• JWS
  • Die Nutzlast kann durch ein beliebiges Format dargestellt werden, z. B. ein JSON-Objekt, einen Byte-Stream oder einen Oktett-Stream.
  • Die Nutzlast muss nicht an das JWS angehängt werden.

Da das JWT-Format immer ein JSON-Objekt zur Darstellung der Nutzlast verwendet, haben die Apigee-Generate-JWT-Richtlinien und die Überprüfung der JWT-Richtlinien die Unterstützung für die Verarbeitung gängiger registrierter Anspruchsnamen wie aud. iss, sub und andere. Dies bedeutet, dass Sie Elemente der Richtlinie Generate JWT verwenden können, um diese Anforderungen in der Nutzlast festzulegen, und Elemente der Richtlinie Verify JWT, um ihre Werte zu überprüfen. Weitere Informationen finden Sie im Abschnitt Registrierte Anspruchsnamen der JWT-Spezifikation.

Neben der Unterstützung bestimmter registrierter Anspruchsnamen unterstützt die Generate JWT-Richtlinie direkt das Hinzufügen von Anforderungen mit beliebigen Namen zum JWT. Jede Anforderung ist ein einfaches Name/Wert-Paar, bei dem der Wert vom Typ "Ganzzahl", "Boolesch", "String", "Zuordnung" oder "Array" sein kann.

Da eine JWS eine beliebige Datendarstellung für die Nutzlast verwenden kann, können Sie der Nutzlast keine Ansprüche hinzufügen. Die Richtlinie Generate JWS unterstützt das Hinzufügen von Ansprüchen mit beliebigen Namen im Header der JWS. Außerdem unterstützen die JWS-Richtlinien eine getrennte Nutzlast, wobei die JWS die Nutzlast weglässt. Mit einer getrennten Nutzlast können Sie die JWS und die Nutzlast separat senden und es sind mehrere Sicherheitsstandards erforderlich.

Über Signaturalgorithmen

Die Richtlinien für die JWS/JWT-Überprüfung und die JWS/JWT-Generierung unterstützen RSA-, RSASSA-PSS-, ECDSA- und HMAC-Algorithmen und verwenden SHA2-Prüfsummen der Bitstärke 256, 384 oder 512. Die JWS/JWT-Decodierungsrichtlinie funktioniert unabhängig vom Algorithmus, der zum Signieren des JWS/JWT verwendet wurde.

Hinweis: Alle von JWS/JWT verwendeten Algorithmen und die erforderlichen Schlüssel werden in der JWA-Spezifikation RFC 7518 beschrieben.

HMAC-Algorithmus

Der HMAC-Algorithmus beruht auf einem gemeinsamen Secret, dem sogenannten geheimen Schlüssel, zum Erstellen der Signatur (auch als Signatur des JWS/JWT bezeichnet) und der Überprüfung der Signatur.

Die Mindestlänge des geheimen Schlüssels hängt von der Bitstärke des Algorithmus ab:

• HS256: 32 Byte Mindestlänge
• HS386: Mindestlänge von 48 Byte
• HS512: Mindestlänge von 64 Byte

RSA-Algorithmus

Der RSA-Algorithmus verwendet ein öffentliches/privates Schlüsselpaar für die kryptografische Signatur. Bei RSA-Signaturen verwendet die signierende Partei einen privaten RSA-Schlüssel, um das JWS/JWT zu signieren, und die überprüfende Partei verwendet den entsprechenden öffentlichen RSA-Schlüssel, um die Signatur auf dem JWS/JWT zu prüfen. Es gibt keine Größenanforderungen für die Schlüssel.

RSASSA-PSS-Algorithmus

Der RSASSA-PSS-Algorithmus ist ein Update des RSA-Algorithmus. Wie RSS verwendet RSASSA-PSS ein öffentliches/privates RSA-Schlüsselpaar für die kryptografische Signatur. Das Format des Schlüssels hat das gleiche wie für RSS. Die signierte Partei signiert das JWS/JWT mit einem privaten Schlüssel und die Verifizierungsanbieter verwendet den passenden öffentlichen Schlüssel, um die Signatur auf JWS/JWT zu prüfen. Für die Schlüssel gelten keine Größenanforderungen.

ECDSA-Algorithmus

Der Elistic Curve Digital Signature-Algorithmus (ECDSA-Algorithmus) ist ein Elliptische-Kurven-Kryptografiealgorithmus mit P-256, P-384 und P-521. Wenn Sie ECDSA-Algorithmen verwenden, bestimmt der Algorithmus den Typ des öffentlichen und privaten Schlüssels, den Sie angeben müssen:

Algorithmus	Curve	Schlüsselanforderung
ES256	P-256	Ein Schlüssel, der aus der P-256-Kurve generiert wurde (auch bekannt als secp256r1 oder Prime256v1)
ES384	P-384	Ein Schlüssel, der aus der P-384-Kurve generiert wird (auch secp384r1)
ES512	P-521	Ein Schlüssel, der aus der P-521-Kurve erzeugt wurde (auch als "secp521r1" bezeichnet)

Schlüsselverschlüsselungs-Algorithmen

Die JWS/JWT-Richtlinien unterstützen alle Schlüsselverschlüsselungsalgorithmen, die von OpenSSL unterstützt werden.

Mit einem JSON-Webschlüsselsatz (JWKS) ein JWS/JWT verifizieren

Wenn Sie ein signiertes JWS/JWT bestätigen, müssen Sie den öffentlichen Schlüssel angeben, der dem privaten Schlüssel zugeordnet ist, der zum Signieren des Tokens verwendet wird. Sie haben zwei Möglichkeiten, den öffentlichen Schlüssel für die Überprüfung der JWS/JWT-Richtlinien bereitzustellen:

• Verwenden Sie den tatsächlichen Wert des öffentlichen Schlüssels (normalerweise in einer Ablaufvariablen) oder
• verwenden Sie einen öffentlichen Schlüssel, der in ein JWKS verpackt ist.

Über JWKS

Ein JWKS ist eine JSON-Struktur, die einen Satz von JSON-Webschlüsseln (JWKs) darstellt. Ein JWK ist eine JSON-Datenstruktur, die einen kryptografischen Schlüssel darstellt. JWK und JWKS werden in RFC7517 beschrieben. Beispiele für JKWS-Beispiele finden Sie unter Anhang A. Beispiele für JSON-Webschlüssel

JWKS-Struktur

In RFC7517 werden die JWKS-Schlüsselelemente für jeden Schlüsseltyp wie RSA oder EC beschrieben. Beispielsweise können diese Parameter je nach Schlüsseltyp Folgendes umfassen:

• kty – der Schlüsseltyp, z. B. RSA oder EC.
• kid (die Schlüssel-ID) – Kann ein beliebiger Wert sein (keine Duplikate innerhalb eines Schlüsselsatzes) Wenn das eingehende JWT eine Schlüssel-ID besitzt, die im Satz von JWKS vorhanden ist, verwendet die Richtlinie den richtigen öffentlichen Schlüssel, um die JWS/JWT-Signatur zu überprüfen.

Im Folgenden finden Sie Beispiele für optionale Elemente und ihre Werte:

• alg – der Schlüsselalgorithmus Er muss mit dem Signaturalgorithmus in JWS/JWT übereinstimmen.
• use – wenn vorhanden, muss er sig sein.

Die folgende JWKS enthält die erforderlichen Elemente und Werte, die in Apigee gültig sind (von https://www.googleapis.com/oauth2/v3/certs):

{
   "keys":[
      {
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

Proxy für die Verwendung von JWKS entwerfen

Wenn ein JWS/JWT von einem Aussteller abgerufen wird, fügt der Aussteller häufig eine Schlüssel-ID oder ein untergeordnetes Element in den JWS/JWT-Header ein. Mit dem Schlüssel wird dem Empfänger des JWS/JWT mitgeteilt, wie der öffentliche oder geheime Schlüssel gefunden werden kann, der zur Überprüfung der Signatur auf dem signierten JWS/JWT erforderlich ist.

Angenommen, ein Aussteller signiert ein JWT mit einem privaten Schlüssel. Die "Schlüssel-ID" identifiziert den passenden öffentlichen Schlüssel, der zur Überprüfung des JWT verwendet werden kann. Die Liste der öffentlichen Schlüssel ist in der Regel an einem bekannten Endpunkt verfügbar, z. B. https://www.googleapis.com/oauth2/v3/certs.

Im Folgenden ist die grundlegende Reihenfolge aufgeführt, in der Apigee (oder eine mit JWKS ausgeführte Plattform) mit einem JWS/JWT, der über ein JWKS verfügt:

1. Suchen Sie im JWS/JWT-Header nach der Schlüssel-ID (kid).
2. Untersuchen Sie den JWS/JWT-Header, um den Signaturalgorithmus (alg) zu finden, z. B. RS256.
3. Die Liste der Schlüssel und IDs aus dem JWKS des bekannten Endpunkts eines bestimmten Ausstellers abrufen.
4. Extrahieren Sie den öffentlichen Schlüssel aus der Liste der Schlüssel mit der im JWS/JWT-Header genannten Schlüssel-ID und mit dem übereinstimmenden Algorithmus, wenn der JWKS-Schlüssel den Algorithmus angibt.
5. Verwenden Sie diesen öffentlichen Schlüssel, um die Signatur auf dem JWS/JWT zu prüfen.
   Hinweis: Die Richtlinie Verify JWS/JWT führt die Suche nach Schlüssel-für-Schlüssel-ID automatisch durch.

Als Apigee API-Proxy-Entwickler müssen Sie folgende Schritte ausführen, um die JWS/JWT-Überprüfung durchzuführen:

1. Rufen Sie die Liste der Schlüssel und IDs vom bekannten Endpunkt für einen bestimmten Aussteller ab. Für diesen Schritt können Sie eine Service Callout-Richtlinie verwenden.
   Hinweis: Es wird empfohlen, das JWKS-Cache im Cache zu speichern, um ein Service-Callout bei jeder Anfrage zu vermeiden.
2. Geben Sie in der Richtlinie Verify JWS/JWT den Speicherort der JWS/JWT im Element <Source> und die JWKS-Nutzlast im Element <PublicKey/JWKS> an. Zum Beispiel für die Verify JWT-Richtlinie:

   <VerifyJWT name="JWT-Verify-RS256">
       <Algorithm>RS256</Algorithm>
       <Source>json.jwt</Source>
       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
       <PublicKey>
           <JWKS ref="public.jwks"/>
       </PublicKey>
       <Subject>apigee-seattle-hatrack-montage</Subject>
       <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
       <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
       <AdditionalClaims>
           <Claim name="show">And now for something completely different.</Claim>
       </AdditionalClaims>
   </VerifyJWT>
   

Die JWT-Bestätigungsrichtlinie erledigt alles andere:

• Wenn ein Schlüssel mit einer Schlüssel-ID, die mit der in der JWT geltend gemachten Schlüssel-ID (kid) übereinstimmt, in der JWKS nicht gefunden wird, gibt die Richtlinie Verify JWT einen Fehler aus und validiert die JWT nicht.
• Wenn das eingehende JWT keine Schlüssel-ID (kid) im Header enthält, ist diese Zuordnung von keyid-to-verification-key nicht möglich.

Als Proxy-Designer sind Sie für die Bestimmung des zu verwendenden Schlüssels verantwortlich. In einigen Fällen kann es sich um einen festen, hartcodierten Schlüssel handeln.