<ph type="x-smartling-placeholder"></ph>
Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur
Apigee X-Dokumentation. Weitere Informationen
Was
Verifiziert die Signatur auf einem JWT, das von Clients oder anderen Systemen empfangen wurde. Diese Richtlinie extrahiert auch die Anforderungen in Kontextvariablen, damit nachfolgende Richtlinien oder Bedingungen diese Werte untersuchen können, um Autorisierungs- oder Routingentscheidungen zu treffen. Eine detaillierte Einführung finden Sie unter Übersicht über JWS- und JWT-Richtlinien.
Wenn diese Richtlinie ausgeführt wird, überprüft Edge die Signatur eines JWT und überprüft, ob das JWT nach Ablauf und „Nicht vorher“-Zeiten gültig, sofern vorhanden. Die Richtlinie kann optional auch die Werte bestimmter Anforderungen im JWT prüfen, z. B. Betreff, Aussteller, Zielgruppe oder Wert zusätzlicher Anforderungen.
Wenn das JWT verifiziert und gültig ist, werden alle darin enthaltenen Anforderungen in Kontextvariablen zur Verwendung durch nachfolgende Richtlinien oder Bedingungen extrahiert. Die Anfrage kann fortgesetzt werden. Wenn die JWT-Signatur nicht verifiziert werden kann oder das JWT aufgrund eines der Zeitstempel ungültig ist, wird die gesamte Verarbeitung beendet und ein Fehler wird in der Antwort zurückgegeben.
Informationen zu den Teilen eines JWT und deren Verschlüsselung und Signatur finden Sie unter RFC7519.
Video
In einem kurzen Video erfahren Sie, wie Sie die Signatur auf einem JWT verifizieren.
Beispiele
- Mit dem HS256-Algorithmus signiertes JWT verifizieren
- Mit dem RS256-Algorithmus signiertes JWT verifizieren
Mit dem HS256-Algorithmus signiertes JWT verifizieren
Diese Beispielrichtlinie prüft ein JWT, das mit dem HS256-Verschlüsselungsalgorithmus HMAC mit einer SHA-256-Prüfsumme signiert wurde. Das JWT wird in der Proxyanfrage mit einem Formularparameter namens jwt
übergeben. Der Schlüssel ist in einer Variablen mit dem Namen private.secretkey
enthalten.
Das Video oben zeigt ein umfassendes Beispiel, in dem auch beschrieben wird, wie Sie eine Anfrage an die Richtlinie senden.
Die Richtlinienkonfiguration enthält die Informationen, die Edge zum Decodieren und Bewerten des JWT benötigt, z. B. wo das JWT zu finden ist (in einer im Quellelement angegebenen Flussvariablen), die erforderliche Signaturalgorithmus, wo Sie den geheimen Schlüssel finden (gespeichert in einer Edge-Flussvariablen, die möglicherweise abgerufen wurden, z. B. aus der Edge-KVM), und eine Reihe erforderlicher Anforderungen und ihrer Werte.
<VerifyJWT name="JWT-Verify-HS256"> <DisplayName>JWT Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey encoding="base64"> <Value ref="private.secretkey"/> </SecretKey> <Subject>monty-pythons-flying-circus</Subject> <Issuer>urn://apigee-edge-JWT-policy-test</Issuer> <Audience>fans</Audience> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> </VerifyJWT>
Die Richtlinie schreibt ihre Ausgabe in Kontextvariablen, damit nachfolgende Richtlinien oder Bedingungen im API-Proxy diese Werte prüfen können. Eine Liste der durch diese Richtlinie festgelegten Variablen finden Sie unter Ablaufvariablen.
Mit dem RS256-Algorithmus signiertes JWT verifizieren
Diese Beispielrichtlinie prüft ein JWT, das mit dem RS256-Algorithmus signiert wurde. Zur Überprüfung müssen Sie den öffentlichen Schlüssel angeben. Das JWT wird in der Proxyanfrage mit einem Formularparameter namens jwt
übergeben. Der öffentliche Schlüssel ist in einer Variablen mit dem Namen public.publickey
enthalten.
Das Video oben zeigt ein umfassendes Beispiel, in dem auch gezeigt wird, wie Sie eine Anfrage an die Richtlinie senden.
Details zu den Anforderungen und Optionen für die einzelnen Elemente in dieser Beispielrichtlinie finden Sie in der Elementreferenz.
<VerifyJWT name="JWT-Verify-RS256"> <Algorithm>RS256</Algorithm> <Source>request.formparam.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </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>
Für die obige Konfiguration wird ein JWT mit diesem Header...
{ "typ" : "JWT", "alg" : "RS256" }
Und dieser Nutzlast…
{ "sub" : "apigee-seattle-hatrack-montage", "iss" : "urn://apigee-edge-JWT-policy-test", "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a", "show": "And now for something completely different." }
…als gültig betrachtet, wenn die Signatur mit dem angegebenen öffentlichen Schlüssel verifiziert werden kann.
Ein JWT mit demselben Header, aber mit dieser Nutzlast…
{ "sub" : "monty-pythons-flying-circus", "iss" : "urn://apigee-edge-JWT-policy-test", "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a", "show": "And now for something completely different." }
…wird als ungültig betrachtet, auch wenn die Signatur verifiziert werden kann, da die im JWT enthaltene Anforderung "sub" nicht mit dem erforderlichen Wert des Elements "Subject" gemäß der Richtlinienkonfiguration übereinstimmt.
Die Richtlinie schreibt ihre Ausgabe in Kontextvariablen, damit nachfolgende Richtlinien oder Bedingungen im API-Proxy diese Werte prüfen können. Eine Liste der durch diese Richtlinie festgelegten Variablen finden Sie unter Ablaufvariablen.
Schlüsselelemente festlegen
Welche Elemente Sie zum Angeben des Schlüssels verwenden, mit dem das JWT geprüft wird, hängt vom ausgewählten Algorithmus ab, wie in der folgenden Tabelle dargestellt:
Algorithmus | Schlüsselelemente | |
---|---|---|
HS* |
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key_or_value"/> </PublicKey> oder: <PublicKey> <Certificate ref="signed_cert_val_ref"/> </PublicKey> oder: <PublicKey> <JWKS ref="jwks_val_or_ref"/> </PublicKey> |
|
* Weitere Informationen zu den Schlüsselanforderungen finden Sie unter Signaturverschlüsselungsalgorithmen. |
Elementverweis
In der Richtlinienreferenz werden die Elemente und Attribute der Richtlinie zum Verifizieren des JWT beschrieben.
Hinweis: Die Konfiguration variiert je nach verwendetem Verschlüsselungsalgorithmus. In den Beispielen finden Sie Beispiele für Konfigurationen von bestimmten Anwendungsfällen.
Attribute, die für das Element der obersten Ebene gelten
<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">
Die folgenden Attribute gelten für alle übergeordneten Richtlinienelemente.
Attribut | Beschreibung | Standard | Präsenz |
---|---|---|---|
name |
Der interne Name der Richtlinie. Folgende Zeichen sind im Namen zulässig: A-Z0-9._\-$ % . Die Edge-Management-Benutzeroberfläche erzwingt jedoch zusätzliche
Einschränkungen gelten, z. B. das automatische Entfernen von Zeichen, die nicht alphanumerisch sind.
Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.
Legen Sie |
false | Optional |
Aktiviert | Legen Sie true fest, um die Richtlinie zu erzwingen.
Legen Sie |
true | Optional |
async | Dieses Attribut wurde verworfen. | false | Veraltet |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Wird zusätzlich zum Namensattribut verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
Standard | Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs der Richtlinie verwendet. |
Präsenz | Optional |
Typ | String |
<Algorithm>
<Algorithm>HS256</Algorithm>
Gibt den Verschlüsselungsalgorithmus zum Signieren des Tokens an. RS*/PS*/ES*-Algorithmen verwenden ein Paar aus öffentlichem/geheimem Schlüssel und HS*-Algorithmen ein gemeinsames Secret. Weitere Informationen finden Sie unter Signaturen für die Signaturverschlüsselung.
Sie können mehrere durch Kommas getrennte Werte angeben. Zum Beispiel "HS256, HS512" oder "RS256, PS256". Sie können jedoch HS*-Algorithmen nicht mit anderen und ES*-Algorithmen nicht mit anderen kombinieren, da sie einen bestimmten Schlüsseltyp erfordern. Sie können RS * - und PS * -Algorithmen kombinieren.
Standard | – |
Präsenz | Erforderlich |
Typ | String mit kommagetrennten Werten |
Zulässige Werte | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
Die Richtlinie überprüft, ob die Zielgruppenanforderung im JWT mit dem in der Konfiguration angegebenen Wert übereinstimmt. Wenn keine Übereinstimmung gefunden wird, gibt die Richtlinie einen Fehler aus. Mit dieser Anforderung werden die Empfänger identifiziert, für die das JWT bestimmt ist. Dies ist eine der in RFC7519 genannten registrierten Anforderungen.
Standard | – |
Präsenz | Optional |
Typ | String |
Zulässige Werte | Eine Ablaufvariable oder ein String zur Identifizierung der Zielgruppe. |
<AdditionalClaims/Claim>
<AdditionalClaims> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> </AdditionalClaims> or: <AdditionalClaims ref='claim_payload'/>
Validiert, dass die JWT-Nutzlast die angegebenen zusätzlichen Anforderungen enthält und die bestätigten Anforderungswerte übereinstimmen.
Eine zusätzliche Anforderung verwendet einen Namen, der nicht zu den standardmäßigen, registrierten JWT-Anforderungsnamen gehört. Der Wert einer zusätzlichen Anforderung kann ein String, eine Zahl, ein boolescher Wert, ein Map oder ein Array sein. Ein Map besteht aus einer Reihe von Name/Wert-Paaren. Der Wert für eine Anforderung dieser Typen kann explizit in der Richtlinienkonfiguration oder indirekt über einen Verweis auf eine Ablaufvariable angegeben werden.
Standard | – |
Präsenz | Optional |
Typ | String, Zahl, boolescher Wert oder Zuordnung |
Array | Mit true wird angegeben, ob der Wert ein Typarray ist. Standardeinstellung: false |
Zulässige Werte | Jeder Wert, den Sie für eine zusätzliche Anforderung verwenden möchten. |
Das Element <Claim>
verwendet die folgenden Attribute:
- name – (erforderlich) Der Name der Anforderung.
- ref – (optional) Der Name einer Ablaufvariable. Falls vorhanden, verwendet die Richtlinie den Wert dieser Variable als Anforderung. Wenn sowohl ein ref-Attribut als auch ein expliziter Anforderungswert angegeben sind, ist der explizite Wert der Standardwert. Er wird verwendet, wenn die referenzierte Ablaufvariable nicht aufgelöst wird.
- type – (optional) Kann String (Standard), Zahl, boolescher Wert oder Map sein
- array – (optional) Legen Sie true fest, um anzugeben, dass der Wert ein Typarray ist. Standardeinstellung: false.
Wenn Sie das Element <Claim>
hinzufügen, werden die Anforderungsnamen beim Konfigurieren der Richtlinie statisch festgelegt. Alternativ können Sie ein JSON-Objekt übergeben, um die Anforderungsnamen anzugeben.
Da das JSON-Objekt als Variable übergeben wird, werden die Anforderungsnamen zur Laufzeit bestimmt.
Beispiele:
<AdditionalClaims ref='json_claims'/>
Die Variable json_claims
enthält ein JSON-Objekt im folgenden Format:
{ "sub" : "person@example.com", "iss" : "urn://secure-issuer@example.com", "non-registered-claim" : { "This-is-a-thing" : 817, "https://example.com/foobar" : { "p": 42, "q": false } } }
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
Validiert, dass der JWT-Header die angegebenen zusätzlichen Name/Wert-Paare der Anforderung enthält und die Werte der bestätigten Anforderung übereinstimmen.
Eine zusätzliche Anforderung verwendet einen Namen, der nicht einem der standardmäßigen registrierten JWT-Anforderungsnamen entspricht. Der Wert einer zusätzlichen Anforderung kann ein String, eine Zahl, ein boolescher Wert, ein Map oder ein Array sein. Ein Map besteht aus einer Reihe von Name/Wert-Paaren. Der Wert für eine Anforderung dieser Typen kann explizit in der Richtlinienkonfiguration oder indirekt über einen Verweis auf eine Ablaufvariable angegeben werden.
Standard | – |
Präsenz | Optional |
Typ |
String (Standard), Zahl, boolescher Wert oder Map. Der Typ wird standardmäßig auf "String" gesetzt, wenn kein Typ angegeben ist. |
Array | Mit true wird angegeben, ob der Wert ein Typarray ist. Standardeinstellung: false |
Zulässige Werte | Jeder Wert, den Sie für eine zusätzliche Anforderung verwenden möchten. |
Das Element <Claim>
verwendet die folgenden Attribute:
- name – (erforderlich) Der Name der Anforderung.
- ref – (optional) Der Name einer Ablaufvariable. Falls vorhanden, verwendet die Richtlinie den Wert dieser Variable als Anforderung. Wenn sowohl ein ref-Attribut als auch ein expliziter Anforderungswert angegeben sind, ist der explizite Wert der Standardwert. Er wird verwendet, wenn die referenzierte Ablaufvariable nicht aufgelöst wird.
- type – (optional) Kann String (Standard), Zahl, boolescher Wert oder Map sein
- array – (optional) Legen Sie true fest, um anzugeben, dass der Wert ein Typarray ist. Standardeinstellung: false.
<CustomClaims>
Hinweis: Derzeit wird ein CustomClaims-Element eingefügt, wenn Sie eine neue GenerateJWT-Richtlinie über die UI hinzufügen. Dieses Element ist nicht funktionsfähig und wird ignoriert. Das richtige zu verwendende Element ist <AdditionalClaims>. Die Benutzeroberfläche wird aktualisiert, sodass später die richtigen Elemente eingefügt werden.
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
Überprüft, ob das JWT die bestimmte jti-Anforderung hat. Wenn der Textwert und das ref-Attribut beide leer sind, generiert die Richtlinie eine jti mit einer zufälligen UUID. Die Anforderung der JWT-ID (jti) ist eine eindeutige Kennung für das JWT. Weitere Informationen über jti finden Sie unter RFC7519.
Standard | – |
Präsenz | Optional |
Typ | String oder Verweis. |
Zulässige Werte | Entweder ein String oder der Name einer Ablaufvariablen, die die ID enthält. |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Setzen Sie diesen Wert auf "false", wenn die Richtlinie einen Fehler ausgibt, wenn ein im Crit-Header des JWT aufgeführter Header nicht im <KnownHeaders>
-Element aufgelistet ist.
Setzen Sie den Wert auf "true", damit die VerifyJWT-Richtlinie den Header crit ignoriert.
Ein Grund für die Festlegung auf "true" wäre, dass Sie sich in einer Testumgebung befinden und noch nicht bereit sind, einen Fehler durch einen fehlenden Header zu verursachen.
Standard | false |
Präsenz | Optional |
Typ | Boolean |
Zulässige Werte | "true" oder "false" |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
Auf "false" (Standard) setzen, wenn die Richtlinie einen Fehler ausgeben soll, wenn ein JWT eine iat
-Anforderung (ausgegeben am) enthält, die einen Zeitpunkt in der Zukunft angibt.
Setzen Sie diesen Wert auf "true", damit die Richtlinie während der Verifizierung iat
ignoriert.
Standard | false |
Präsenz | Optional |
Typ | Boolean |
Zulässige Werte | "true" oder "false" |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Setzen Sie diesen Wert auf "false", wenn die Richtlinie einen Fehler ausgibt, falls eine in der Richtlinie angegebene Variable, auf die verwiesen wird, nicht auflösbar ist. Setzen Sie diesen Wert auf "true", um alle nicht aufgelösten Variablen als leeren String zu behandeln (null).
Standard | false |
Präsenz | Optional |
Typ | Boolean |
Zulässige Werte | "true" oder "false" |
<Issuer>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
Die Richtlinie verifiziert, ob der Aussteller im JWT mit dem im Konfigurationselement angegebenen String übereinstimmt. Eine Anforderung, die den Aussteller des JWT identifiziert. Dies ist eine der registrierten Anforderungen, die in RFC7519 erwähnt werden.
Standard | – |
Präsenz | Optional |
Typ | String oder Verweis |
Zulässige Werte | Alle |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Die GenerateJWT-Richtlinie verwendet das Element <CriticalHeaders>
, um den Header crit in einem JWT zu füllen. Beispiel:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
Die VerifyJWT-Richtlinie prüft den Header crit im JWT, sofern vorhanden, und prüft für jeden Header, ob dieser auch im <KnownHeaders>
-Element aufgelistet ist. Das Element <KnownHeaders>
kann eine Obermenge der in crit aufgelisteten Elemente enthalten.
Es müssen nur die in crit aufgeführten Header im Element <KnownHeaders>
aufgelistet sein. Jeder Header, den die Richtlinie in crit findet, der aber nicht in <KnownHeaders>
aufgeführt ist, lässt die VerifyJWT-Richtlinie fehlschlagen.
Sie können die VerifyJWT-Richtlinie optional konfigurieren, um den Header crit zu ignorieren. Dazu setzen Sie das Element <IgnoreCriticalHeaders>
auf true
.
Standard | – |
Präsenz | Optional |
Typ | Kommagetrenntes Stringarray |
Zulässige Werte | Entweder ein Array oder der Name einer Variable, die das Array enthält. |
<PublicKey/Certificate>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
Gibt das signierte Zertifikat an, mit dem die Signatur im JWT geprüft wird. Verwenden Sie das ref-Attribut, um das signierte Zertifikat in einer Ablaufvariablen zu übergeben, oder geben Sie das PEM-codierte Zertifikat direkt an. Nur verwenden, wenn der Algorithmus RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512 ist.
Standard | – |
Präsenz | Zum Verifizieren eines mit einem RSA-Algorithmus signierten JWT müssen Sie das Element "Certificate", "JWKS" oder "Value" verwenden. |
Typ | String |
Zulässige Werte | Eine Ablaufvariable oder ein String. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
Gibt einen Wert im JWKS-Format (RFC 7517) an, das einen Satz öffentlicher Schlüssel enthält. Nur verwenden, wenn der Algorithmus einen der folgenden Werte hat: RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512.
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 JWT-Signatur zu verifizieren. Weitere Informationen zu diesem Feature finden Sie unter JSON Web Key Set (JWKS) zur Verifizierung eines JWT verwenden.
Wenn Sie den Wert von einer öffentlichen URL abrufen, speichert Edge das JWKS für einen Zeitraum von 300 Sekunden im Cache. Wenn der Cache abläuft, ruft Edge den JWKS noch einmal ab.
Standard | – |
Präsenz | Zur Verifizierung eines JWT mithilfe eines RSA-Algorithmus müssen Sie das Element "Certificate", "JWKS" oder "Value" verwenden. |
Typ | String |
Zulässige Werte | Eine Ablaufvariable, ein Stringwert oder eine URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickeyorcert"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
Gibt den öffentlichen Schlüssel oder das öffentliche Zertifikat an, das zur Überprüfung der Signatur im JWT verwendet wird. Verwenden Sie das ref-Attribut, um den Schlüssel bzw. das Zertifikat in einer Ablaufvariable zu übergeben, oder geben Sie den PEM-codierten Schlüssel direkt an. Nur verwenden, wenn der Algorithmus entweder RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512 ist.
Standard | – |
Präsenz | Zum Verifizieren eines mit einem RSA-Algorithmus signierten JWT müssen Sie das Element "Certificate", "JWKS" oder "Value" verwenden. |
Typ | String |
Zulässige Werte | Eine Ablaufvariable oder ein String. |
<SecretKey/Value>
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.your-variable-name"/> </SecretKey>
Stellt den geheimen Schlüssel zum Verifizieren oder Signieren von Tokens mit einem HMAC-Algorithmus bereit. Nur verwenden wenn der Algorithmus HS256, HS384 oder HS512 ist.
Standard | – |
Präsenz | Erforderlich für HMAC-Algorithmen. |
Typ | String |
Zulässige Werte |
Gültige Werte für Verwenden Sie das Attribut ref. um den Schlüssel in einer Flussvariablen zu übergeben. Hinweis: Wenn eine Ablaufvariable vorhanden ist, muss sie das Präfix "privat" haben. Beispiel,
|
<Source>
<Source>jwt-variable</Source>
Gibt, sofern vorhanden, die Ablaufvariable an, in der die Richtlinie das zu verifizierende JWT findet.
Standard | request.header.authorization (Wichtige Informationen zur Standardeinstellung finden Sie im Hinweis oben). |
Präsenz | Optional |
Typ | String |
Zulässige Werte | Name einer Edge-Flussvariablen. |
<Subject>
<Subject>subject-string-here</Subject>
Die Richtlinie verifiziert, ob das Subjekt im JWT mit dem in der Richtlinienkonfiguration angegebenen String übereinstimmt. Diese Anforderung identifiziert das Subjekt des JWT oder bestätigt es. Dies ist einer der Standardsätze Anforderungen, die in RFC7519 erwähnt werden.
Standard | – |
Präsenz | Optional |
Typ | String |
Zulässige Werte | Jeder Wert, der ein Subjekt eindeutig identifiziert. |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
"Kulanzzeitraum" für Zeiten. Wenn für den Kulanzzeitraum beispielsweise 60 Sekunden festgelegt sind, wird ein abgelaufenes JWT 60 Sekunden nach dem festgelegten Ablauf noch als gültig betrachtet. Das "not-before-time" wird ähnlich ausgewertet. Der Standardwert ist 0 Sekunden (kein Kulanzzeitraum).
Standard | 0 Sekunden (kein Kulanzzeitraum) |
Präsenz | Optional |
Typ | String |
Zulässige Werte |
Ein Wert oder ein Verweis auf eine Ablaufvariable, die den Wert enthält. Zeiträume können so angegeben werden:
|
Ablaufvariablen
Bei Erfolg werden bestimmen die Richtlinien JWT prüfen und JWT dekodieren entsprechend folgendem Muster Kontextvariablen:
jwt.{policy_name}.{variable_name}
Beispiel: Lautet der Richtlinienname jwt-parse-token
, so speichert die Richtlinie das im JWT angegebene Subjekt in dieser Kontextvariable: jwt.jwt-parse-token.decoded.claim.sub
Aus Gründen der Abwärtskompatibilität ist sie auch in jwt.jwt-parse-token.claim.subject
verfügbar.
Variablenname | Beschreibung |
---|---|
claim.audience |
Die JWT-Zielgruppenanforderung. Dieser Wert kann ein String oder ein Array von Strings sein. |
claim.expiry |
Ablaufdatum bzw. Ablaufzeit in Millisekunden seit der Epoche. |
claim.issuedat |
Datum des Tokens in Millisekunden seit der Epoche. |
claim.issuer |
Anspruch des JWT-Ausstellers. |
claim.notbefore |
Wenn das JWT eine nbf-Anforderung enthält, enthält diese Variable den Wert, in Millisekunden seit der Epoche. |
claim.subject |
Anforderung des JWT-Betreffs. |
claim.name |
Der Wert des in der Nutzlast benannten Anspruchs (Standard oder Zusätzlich). Eines der Elemente wird für jeden Anspruch in der Nutzlast festgelegt. |
decoded.claim.name |
Der JSON-Parsewert der benannten Anforderung (Standard oder zusätzlicher) in der Nutzlast. Eine Variable wird für jeden Anspruch in der Nutzlast festgelegt. Sie können z. B. decoded.claim.iat verwenden, um
Ruft den Zeitpunkt der Ausgabe des JWT in Sekunden seit der Epoche ab. Sie können auch die Flow-Variablen claim.name verwenden. Dies ist jedoch die empfohlene Variable für den Zugriff auf eine Anforderung. |
decoded.header.name |
JSON-Parsingwert eines Headers in der Nutzlast. Für jeden Header in der Nutzlast wird eine Variable festgelegt. Sie können auch die Flow-Variablen header.name verwenden. Dies ist jedoch die empfohlene Variable für den Zugriff auf einen Header. |
expiry_formatted |
Ablaufdatum und -zeit als formatierter String. Beispiel: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
Der für das JWT verwendete Signaturalgorithmus. Zum Beispiel RS256, HS384 usw. Weitere Informationen finden Sie unter Headerparameter (Algorithmus). |
header.kid |
Die Schlüssel-ID, wenn sie beim Generieren des JWT hinzugefügt wurde. Weitere Informationen zur Überprüfung eines JWT finden Sie auch unter "JSON-Webschlüsselsatz verwenden (JWKS)" unter JWT-Richtlinienübersicht. Weitere Informationen finden Sie unter Header-Parameter (Key ID). |
header.type |
Wird auf JWT festgelegt. |
header.name |
Der Wert des benannten Headers (Standard oder Zusätzlich). Eines der Elemente wird für jeden zusätzlichen Header im Header-Teil des JWT bestimmt. |
header-json |
Die Kopfzeile im JSON-Format. |
is_expired |
Richtig oder falsch? |
payload-claim-names |
Ein Array von Ansprüchen, vom JWT unterstützt. |
payload-json |
Nutzlast im JSON-Format.
|
seconds_remaining |
Anzahl der Sekunden bis zum Ablauf des Tokens. Ist das Token abgelaufen, ist diese Zahl negativ. |
time_remaining_formatted |
Die verbleibende Zeit bis zum Ablauf des Tokens als formatierter String. Beispiel: 00:59:59.926 |
valid |
Im Fall von VerifyJWT ist diese Variable "true", wenn die Signatur verifiziert wurde. Die aktuelle Zeit ist entsprechend vor Ablauf des Tokens bzw. nach dem Token-Wert "notBefore", sofern vorhanden. Ansonsten ist die Variable "false".
Im Fall von DecodeJWT ist die Variable nicht festgelegt. |
Fehlerreferenz
In diesem Abschnitt werden die Fehlercodes und Fehlermeldungen beschrieben, die zurückgegeben werden, sowie die Fehlervariablen, die von Edge festgelegt werden, wenn diese Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.
Laufzeitfehler
Diese Fehler können bei Ausführung der Richtlinie auftreten.
Fehlercode | HTTP-Status | Tritt auf, wenn Folgendes eintritt |
---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 | Tritt auf, wenn die Prüfungsrichtlinie mehrere Algorithmen nutzt. |
steps.jwt.AlgorithmMismatch |
401 | Der in der Generierungsrichtlinie angegebene Algorithmus stimmte nicht mit dem in der Verifizierungsrichtlinie erwarteten Algorithmus überein. Die angegebenen Algorithmen müssen übereinstimmen. |
steps.jwt.FailedToDecode |
401 | Die Richtlinie konnte das JWT nicht decodieren. Das JWT ist möglicherweise beschädigt. |
steps.jwt.GenerationFailed |
401 | Die Richtlinie konnte das JWT nicht generieren. |
steps.jwt.InsufficientKeyLength |
401 | Für einen Schlüssel mit weniger als 32 Byte beim HS256-Algorithmus, weniger als 48 Byte beim HS386 Algorithmus und weniger als 64 Byte beim HS512-Algorithmus. |
steps.jwt.InvalidClaim |
401 | Bei einem fehlenden Anspruch oder nicht übereinstimmenden Ansprüchen oder einem fehlenden Header oder Header. |
steps.jwt.InvalidCurve |
401 | Die vom Schlüssel angegebene Kurve ist für den Elliptic-Curve-Algorithmus ungültig. |
steps.jwt.InvalidJsonFormat |
401 | Ungültiger JSON-Code im Header oder der Nutzlast gefunden. |
steps.jwt.InvalidToken |
401 | Dieser Fehler tritt auf, wenn die JWT-Signaturprüfung fehlschlägt. |
steps.jwt.JwtAudienceMismatch |
401 | Der Zielgruppenanspruch ist bei der Tokenprüfung fehlgeschlagen. |
steps.jwt.JwtIssuerMismatch |
401 | Der Ausstelleranspruch ist bei der Tokenprüfung fehlgeschlagen. |
steps.jwt.JwtSubjectMismatch |
401 | Der Betreffanspruch ist bei der Tokenprüfung fehlgeschlagen. |
steps.jwt.KeyIdMissing |
401 | Die Verifizierungsrichtlinie verwendet einen JWKS als Quelle für öffentliche Schlüssel, das signierte JWT enthält jedoch kein kid -Attribut im Header. |
steps.jwt.KeyParsingFailed |
401 | Der öffentliche Schlüssel konnte anhand der angegebenen Schlüsselinformationen nicht geparst werden. |
steps.jwt.NoAlgorithmFoundInHeader |
401 | Tritt auf, wenn das JWT keinen Algorithmus-Header enthält. |
steps.jwt.NoMatchingPublicKey |
401 | Die Verifizierungsrichtlinie verwendet einen JWKS als Quelle für öffentliche Schlüssel, aber kid im signierten JWT ist nicht in JWKS aufgeführt. |
steps.jwt.SigningFailed |
401 | In GenerateJWT, für Schlüssel, die kleiner als die Mindestgröße für den HS384- oder HS512-Algorithmus sind |
steps.jwt.TokenExpired |
401 | Die Richtlinie versucht, ein abgelaufenes Token zu bestätigen. |
steps.jwt.TokenNotYetValid |
401 | Das Token ist noch nicht gültig. |
steps.jwt.UnhandledCriticalHeader |
401 | Ein Header, der von der JWT-Richtlinie im Header crit gefunden wurde, ist nicht in KnownHeaders aufgeführt. |
steps.jwt.UnknownException |
401 | Es ist eine unbekannte Ausnahme aufgetreten. |
steps.jwt.WrongKeyType |
401 | Falscher Schlüsseltyp angegeben. Wenn Sie beispielsweise einen RSA-Schlüssel für einen Elliptic Curve-Algorithmus oder einen Kurvenschlüssel für einen RSA-Algorithmus angeben. |
Bereitstellungsfehler
Diese Fehler können auftreten, wenn Sie einen Proxy bereitstellen, der diese Richtlinie enthält.
Fehlername | Ursache | Problembehebung |
---|---|---|
InvalidNameForAdditionalClaim |
Die Bereitstellung schlägt fehl, wenn die im untergeordneten Element <Claim> des Elements <AdditionalClaims> verwendete Anforderung einer der folgenden registrierten Namen ist: kid , iss , sub , aud , iat , exp , nbf oder jti .
|
build |
InvalidTypeForAdditionalClaim |
Wenn die im untergeordneten Element <Claim> des <AdditionalClaims> -Elements verwendete Anforderung nicht vom Typ string , number , boolean oder map ist, schlägt die Bereitstellung fehl.
|
build |
MissingNameForAdditionalClaim |
Wenn der Name der Anforderung nicht im untergeordneten Element <Claim> des Elements <AdditionalClaims> angegeben ist, schlägt die Bereitstellung fehl.
|
build |
InvalidNameForAdditionalHeader |
Dieser Fehler tritt auf, wenn der Name der im untergeordneten Element <Claim> des <AdditionalClaims> -Elements verwendeten Anforderung entweder alg oder typ ist.
|
build |
InvalidTypeForAdditionalHeader |
Wenn der im untergeordneten Element <Claim> des <AdditionalClaims> -Elements verwendete Anforderungstyp nicht vom Typ string , number , boolean oder map ist, schlägt die Bereitstellung fehl.
|
build |
InvalidValueOfArrayAttribute |
Dieser Fehler tritt auf, wenn der Wert des Array-Attributs im untergeordneten Element <Claim> des <AdditionalClaims> -Elements nicht auf true oder false festgelegt ist.
|
build |
InvalidValueForElement |
Wenn der im Element <Algorithm> angegebene Wert kein unterstützter Wert ist, schlägt die Bereitstellung fehl.
|
build |
MissingConfigurationElement |
Dieser Fehler tritt auf, wenn das Element <PrivateKey> nicht mit RSA-Familienalgorithmen oder das Element <SecretKey> nicht mit Algorithmen der HS-Familie verwendet wird.
|
build |
InvalidKeyConfiguration |
Wenn das untergeordnete Element <Value> nicht in den Elementen <PrivateKey> oder <SecretKey> definiert ist, schlägt die Bereitstellung fehl.
|
build |
EmptyElementForKeyConfiguration |
Wenn das ref-Attribut des untergeordneten Elements <Value> der Elemente <PrivateKey> oder <SecretKey> leer oder nicht angegeben ist, schlägt die Bereitstellung fehl.
|
build |
InvalidConfigurationForVerify |
Dieser Fehler tritt auf, wenn das Element <Id> im Element <SecretKey> definiert ist.
|
build |
InvalidEmptyElement |
Dieser Fehler tritt auf, wenn das <Source> -Element der Verify JWT-Richtlinie leer ist. Falls vorhanden, muss sie mit einem Edge-Flow-Variablennamen definiert werden.
|
build |
InvalidPublicKeyValue |
Wenn der im untergeordneten Element <JWKS> des Elements <PublicKey> verwendete Wert kein gültiges in RFC 7517 angegebenes Format hat, schlägt die Bereitstellung fehl.
|
build |
InvalidConfigurationForActionAndAlgorithm |
Wenn das Element <PrivateKey> mit HS-Family-Algorithmen oder das <SecretKey> -Element mit RSA-Family-Algorithmen verwendet wird, schlägt die Bereitstellung fehl.
|
build |
Fehlervariablen
Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.
Variablen | Wo | Beispiel |
---|---|---|
fault.name="fault_name" |
fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. | fault.name Matches "TokenExpired" |
JWT.failed |
Bei allen JWT-Richtlinien wird im Fall eines Fehlers dieselbe Variable festgelegt. | JWT.failed = true |
Beispiel für eine Fehlerantwort
Bei der Fehlerbehandlung besteht die Best Practice darin, den errorcode
-Teil der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring
. Er kann sich ändern.
Beispiel für eine Fehlerregel
<FaultRules> <FaultRule name="JWT Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "TokenExpired")</Condition> </Step> <Condition>JWT.failed=true</Condition> </FaultRule> </FaultRules>