JWT validieren

Verwenden Sie die Sicherheitsrichtlinie JWT validieren , um die Validierung eines JWT (JSON Web Token) in einer Anforderung zu aktivieren, bevor Sie den Zugriff auf die APIs zulassen.

Gateway-Unterstützung

Tabelle 1. Tabelle, in der angegeben wird, welche Gateways diese Richtlinie unterstützen, sowie die entsprechende Richtlinienversion
Gateway	Richtlinienversion
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

In diesem Abschnitt wird die Konfiguration der Richtlinie in der Assembly-Benutzerschnittstelle beschrieben. Details zur Konfiguration der Richtlinie in Ihrer OpenAPI -Quelle finden Sie unter jwt-validate.

Produktinfo

JSON-Web-Token (JWT) ist eine kompakte, URL-sichere Möglichkeit, Anforderungen darzustellen, die zwischen zwei Parteien übertragen werden sollen. Mit der Richtlinie JWT validieren können Sie den Zugriff auf Ihre APIs mithilfe der JWT-Validierung sichern. Wenn beispielsweise eine Eingabeanforderung empfangen wird, die ein JWT im Header enthält, extrahiert die Richtlinie JWT validieren das Token, prüft und entschlüsselt (falls zutreffend) die Signatur und validiert den Anspruch. Wenn sie gültig ist, wird die Anforderung in eine Laufzeitvariable gesetzt (für die spätere Verwendung bei Bedarf) und der API wird der Zugriff gewährt. Wenn die Anforderung nicht gültig ist, wird der Zugriff verweigert.

Alle Claims, die in der Richtlinie JWT validieren angegeben sind, werden validiert, aber dies sind nicht unbedingt alle Claims, die im JWT enthalten sind. Es müssen nicht alle Deklarationen im JWT validiert werden, aber wenn eine der Deklarationen, die in der Richtlinie JWT validieren angegeben sind, fehlschlägt, schlägt die gesamte Validierung fehl. Wenn die Validierung erfolgreich ist, wird die vollständige Gruppe von Claims, die im JWT enthalten sind, in die Laufzeitvariable geschrieben, die in der Eigenschaft Output Claims angegeben ist. Dadurch wird ermöglicht, dass alle nachfolgenden Aktionen diese Laufzeitvariable verwenden können, um nach Bedarf den vollständigen Satz an Anforderungen, die sich im JWT befanden, weiter zu validieren.

Hinweis:

Wenn die ursprüngliche Nachricht mit einem geheimen Schlüssel für die gemeinsame Nutzung signiert wurde, muss das angegebene Verschlüsselungsobjekt ebenfalls ein geheimer Schlüssel für die gemeinsame Nutzung sein.
Wenn die ursprüngliche Nachricht mit einem privaten Schlüssel signiert wurde, muss das angegebene Verschlüsselungsobjekt ein Crypto-Zertifikat (öffentliches Zertifikat) sein.
Das Verschlüsselungsmaterial kann über einen JSON Web Key (JWK) bereitgestellt werden.
Wenn ein JWK-Headerparameter im Header des JWT eingeschlossen ist, muss der Parameter dem JWK oder dem Verschlüsselungsobjekt entsprechen, der/das in der Richtlinie angegeben ist. Andernfalls schlägt die JWT-Validierung fehl.
Wenn sowohl ein Verschlüsselungsobjekt als auch ein JWK angegeben werden, wird das Verschlüsselungsobjekt verwendet, um das JWT zu entschlüsseln oder zu überprüfen.
Die JWT-Validierungsaktion auf dem DataPower API Gateway kann ein JWT mit einem einzelnen JWK oder einer JWK-Gruppe verifizieren.

Voraussetzungen

Es gelten die folgenden Voraussetzungen:

IBM® DataPower V7.5 mit der Option "Application Optimization" (AO).
Wenn Sie ein oder mehrere kryptografische Objekte (Krypto-Objekte) verwenden, müssen diese sich in der IBM API Connect -Domain auf dem DataPower gerät befinden. Die Verschlüsselungsobjekte müssen auf den geheimen Schlüssel für die gemeinsame Nutzung oder auf das öffentliche Zertifikat verweisen, der/das zum Entschlüsseln der JWT-Inhalte oder zum Überprüfen der Signatur benötigt wird.
Wenn ein JWK (JSON Web Key) oder eine JWK-Gruppe verwendet wird, muss eine Laufzeitvariable darauf verweisen.

Eigenschaften

Die folgende Tabelle enthält die Richtlinieneigenschaften, gibt an, ob eine Eigenschaft erforderlich ist, enthält die gültigen Werte und die Standardwerte für Eingaben und gibt den jeweiligen Datentyp der Werte an.

Tabelle 2. JWT- -Richtlinieneigenschaften validieren
Eigenschaftsbezeichnung	Erforderlich	Beschreibung	Datentyp
Titel	Ja	Der Titel der Richtlinie. Der Standardwert ist `jwt-validate`.	Zeichenfolge
Beschreibung	Nein	Eine Beschreibung der Richtlinie.	Zeichenfolge
JSON-Web-Token (JWT)	Ja	Kontext- oder Laufzeitvariable, die das zu validierende JWT enthält. Der Standardwert ist `request.headers.authorization`. Wenn diese Eigenschaft jedoch nicht festgelegt ist, sucht die Richtlinie das JWT standardmäßig an der Position `request.headers.authorization`. Hinweis: Der Berechtigungsheader muss folgendes Format haben: `"Authorization: Bearer jwt-token"` Dabei ist `jwt-token` das verschlüsselte JWT.	Zeichenfolge
Ausgabeanforderungen	Ja	Laufzeitvariable, der der vollständige Satz an im JWT enthaltenen Anforderungen zugewiesen wird. Der Standardwert ist `decoded.claims`.	Zeichenfolge
Ausstelleranforderung	Nein	Der Perl Compatible Regular Expressions (PCRE) für die Validierung des Ausstelleranspruchs (iss).	Zeichenfolge
Zielgruppenanforderung	Nein	Der zum Validieren der Zielgruppenanforderung (aud) zu verwendende PCRE.	Zeichenfolge
Crypto-Objekt entschlüsseln	Nein	Das Verschlüsselungsobjekt (ein gemeinsam genutzter Schlüssel oder ein Zertifikat), das zum Entschlüsseln der Anforderung verwendet werden soll.^¹	Zeichenfolge
Crypto-JWK-Variablennamen entschlüsseln	Nein	Laufzeitvariable, die den JWK enthält, der zum Entschlüsseln des JWT verwendet werden soll.^¹	Zeichenfolge
Crypto-Objekt überprüfen	Nein	Das Verschlüsselungsobjekt (gemeinsam genutzter Schlüssel oder Zertifikat), das zum Prüfen der Signatur verwendet werden soll^²	Zeichenfolge
Crypto-JWK-Variablennamen überprüfen	Nein	Laufzeitvariable, die den JWK oder die JWK-Gruppe für die Überprüfung der Signatur enthält.^²	Zeichenfolge

Beispiel

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

Fehler

Der folgende Fehler kann ausgelöst werden, während die Richtlinie ausgeführt wird:

RuntimeError - ein generischer Fehler, der alle Fehler erfasst, die während der Ausführung der Richtlinie aufgetreten sind. Bei einem Fehler bei der Gültigkeitsprüfung wird die detaillierte Fehlernachricht, die vom zugrunde liegenden JOSE-Modul empfangen wird, als Fehlernachricht in das Standard-Systemprotokoll geschrieben. Diese detaillierte Fehlernachricht wird auch der Laufzeitvariable jwt-validate.error-message zugewiesen, sodass sie per Catch abgerufen werden kann.

Invalid-JWT-Validate Wenn kein Catch konfiguriert ist, gibt die Validate JWT-Richtlinie im Falle eines Validierungsfehlers einen HTTP -Fehlercode 500 zurück. Die detaillierte Fehlernachricht aus dem zugrunde liegenden JOSE-Modul befindet sich im Systemprotokoll.

Achtung: Wenn Sie ein API-Entwickler sind, der einen Fehler beheben soll, den einer Ihrer Kunden mit Ihrer API hatte, berücksichtigen Sie die Sicherheitsrisiken, bevor Sie einem Kunden den genauen Inhalt der Protokollnachricht senden. Sie können vermeiden, dass jemand einen Angriff auf der Grundlage der Informationen startet, den er aus der Protokollnachricht erhält, indem sie dem Kunden nur allgemeine Informationen zur Nachricht senden.

Beispiele finden Sie unter jwt-validate.

¹ Ein JWK und ein Verschlüsselungsobjekt sind beides gültige Methoden zur Bereitstellung der Verschlüsselungsdaten, die zum Entschlüsseln des JWT erforderlich sind. Wenn allerdings beide Datentypen angegeben sind, wird nur das Crypro-Objekt verwendet. Wenn Sie ein oder mehrere kryptografische Objekte (Krypto-Objekte) verwenden, müssen diese sich in der IBM API Connect -Domain auf dem DataPower gerät befinden. Die Verschlüsselungsobjekte müssen auf den geheimen Schlüssel für die gemeinsame Nutzung oder auf das öffentliche Zertifikat verweisen, der/das zum Entschlüsseln der JWT-Inhalte oder zum Überprüfen der Signatur benötigt wird.

² Eine JWK-oder JWK-Gruppe und ein Crypto-Objekt sind beides gültige Methoden zur Bereitstellung der Verschlüsselungsdaten, die zum Prüfen des JWT erforderlich sind. Wenn allerdings beide Datentypen angegeben sind, wird nur das Crypro-Objekt verwendet.