VerifyJWT-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Was

Verifiziert ein signiertes JWT oder entschlüsselt es und verifiziert ein verschlüsseltes 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.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Wenn diese Richtlinie ausgeführt wird, verifiziert Apigee im Fall eines signierten JWT die Signatur des JWT mithilfe des bereitgestellten Verifizierungsschlüssels. Im Fall eines verschlüsselten JWT entschlüsselt Apigee das JWT mithilfe des Entschlüsselungsschlüssels. In beiden Fällen überprüft Apigee anschließend, ob die JWT gemäß der Ablaufzeit und der Anfangszeit gültig ist, wenn sie vorhanden sind. 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.

Wie

Ob die Richtlinie ein signiertes oder verschlüsseltes JWT verifiziert, hängt von dem Element ab, mit dem Sie den Algorithmus angeben, der das JWT überprüft:

Video

In einem kurzen Video erfahren Sie, wie Sie die Signatur auf einem JWT verifizieren.

Signiertes JWT überprüfen

In diesem Abschnitt wird erläutert, wie Sie ein signiertes JWT verifizieren. Verwenden Sie bei einem signierten JWT das Element <Algorithm>, um den Algorithmus zum Signieren des Schlüssels anzugeben.

Beispiele für ein signiertes JWT

In den folgenden Beispielen wird gezeigt, wie Sie ein signiertes JWT verifizieren.

HS256-Algorithmus

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 gezeigt wird, wie Sie eine Anfrage an die Richtlinie senden.

Die Richtlinienkonfiguration enthält die Informationen, die Apigee zum Decodieren und Auswerten des JWT benötigt, z. B. wo sich das JWT (in einer im Quellelement angegebenen Ablaufvariable) befindet, der erforderliche Signaturalgorithmus, wo sich der (in Apigee gespeicherte) geheime Schlüssel in einer Ablaufvariable befindet, die möglicherweise von der Apigee-CSV-Datei abgerufen wurde, sowie eine Reihe erforderlicher Anforderungen und deren 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 von dieser Richtlinie festgelegten Variablen finden Sie unter Abrufvariabeln.

RS256-Algorithmus

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 von dieser Richtlinie festgelegten Variablen finden Sie unter Abrufvariabeln.

In den obigen Beispielen wird das Element <Algorithm> verwendet, sodass ein signiertes JWT verifiziert wird. Das <PrivateKey>-Element gibt den Schlüssel an, der zum Signieren des JWT verwendet wird. Es gibt noch weitere Schlüsselelemente. Welche davon Sie verwenden, hängt vom Algorithmus ab, der durch den Wert von <Algorithm> angegeben wird, wie im nächsten Abschnitt beschrieben.

Schlüsselelemente für die Überprüfung eines signierten JWT festlegen

Mit den folgenden Elementen wird der Schlüssel angegeben, der zum Überprüfen eines signierten JWT verwendet wird:

Welches Element Sie verwenden, 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.

Verschlüsseltes JWT überprüfen

In diesem Abschnitt wird erläutert, wie Sie ein verschlüsseltes JWT verifizieren. Verwenden Sie für ein verschlüsseltes JWT das Element <Algorithms>, um die Algorithmen zum Signieren des Schlüssels und des Inhalts anzugeben.

Beispiel für ein verschlüsseltes JWT

Das folgende Beispiel zeigt, wie ein verschlüsseltes JWT überprüft wird, wobei <Type> auf Encrypted gesetzt ist. Dabei gilt:

  • Der Schlüssel wird mit dem RSA-OAEP-256-Algorithmus verschlüsselt.
  • Der Inhalt wird mit dem A128GCM-Algorithmus verschlüsselt.
<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

Im obigen Beispiel wird das Element <Algorithms> verwendet, sodass ein verschlüsseltes JWT verifiziert wird. Das <PrivateKey>-Element gibt den Schlüssel an, der zum Entschlüsseln des JWT verwendet wird. Es gibt noch weitere Schlüsselelemente. Welche davon Sie verwenden, hängt vom Algorithmus ab, der durch den Wert von <Algorithms> angegeben wird, wie im nächsten Abschnitt beschrieben.

Schlüsselelemente für die Überprüfung eines verschlüsselten JWT festlegen

Mit den folgenden Elementen wird der Schlüssel angegeben, der zur Überprüfung eines verschlüsselten JWT verwendet wird:

Welches Element Sie verwenden, hängt vom ausgewählten Schlüsselverschlüsselungsalgorithmus ab, wie in der folgenden Tabelle dargestellt:

Algorithmus Schlüsselelemente
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

Hinweis: Die von Ihnen angegebene Variable muss in einen privaten RSA-Schlüssel in PEM-codierter Form aufgelöst werden.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Hinweis: Die von Ihnen angegebene Variable muss in einen privaten Schlüssel mit elliptischen Kurven in PEM-codierter Form aufgelöst werden.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

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 Presence
Name Der interne Name der Richtlinie. Folgende Zeichen sind im Namen zulässig: A-Z0-9._\-$ %. Die Apigee-Benutzeroberfläche erzwingt jedoch zusätzliche Einschränkungen wie das Entfernen von nicht alphanumerischen Zeichen.

Optional können Sie das Element <displayname></displayname> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

 – 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 true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird.

 false Optional
aktiviert Legen Sie true fest, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu "deaktivieren". Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async Dieses Attribut wurde verworfen. false Verworfen

<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.
Presence Optional
Typ String

<Algorithm>

<Algorithm>HS256</Algorithm>

Gibt den kryptografischen Algorithmus an, der zur Überprüfung des Tokens verwendet wird. Verwenden Sie das Element <Algorithm>, um ein signiertes JWT zu überprüfen.

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 –
Presence Erforderlich
Typ String mit kommagetrennten Werten
Zulässige Werte HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Verwenden Sie das Element <Algorithms>, um ein verschlüsseltes JWT zu überprüfen. Mit diesem Element wird der kryptografische Algorithmus für die Schlüsselverschlüsselung angegeben, der beim Erstellen des verschlüsselten JWT verwendet worden sein muss. Außerdem wird der Algorithmus für die Inhaltsverschlüsselung angegeben.

Standard –
Presence Erforderlich, wenn ein verschlüsseltes JWT überprüft wird
Typ Komplex

Untergeordnete Elemente von <Algorithms>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <Algorithms>:

Untergeordnetes Element Erforderlich? Beschreibung
<Key> Erforderlich Gibt den Verschlüsselungsalgorithmus für den Schlüssel an.
<Content> Optional Gibt den Verschlüsselungsalgorithmus für den Inhalt an.

Die Überprüfung schlägt in folgenden Fällen fehl:

  • Der Algorithmus, der im Attribut alg im Header des verschlüsselten JWT bestätigt ist, unterscheidet sich vom hier im Element <Key> angegebenen Schlüsselverschlüsselungsalgorithmus.
  • Die Richtlinie gibt ein <Content>-Element an und der Algorithmus, der im Attribut enc im Header des verschlüsselten JWT bestätigt wird, unterscheidet sich von dem im <Content>-Element angegebenen Algorithmus.

So überprüfen Sie beispielsweise ein verschlüsseltes JWT und prüfen, ob der Schlüsselalgorithmus RSA-OAEP-256 und der Inhaltsalgorithmus A128GCM ist:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

Umgekehrt können Sie ein verschlüsseltes JWT prüfen und überprüfen, ob der Schlüsselalgorithmus RSA-OAEP-256 ist, und keine Einschränkung für den Inhaltsalgorithmus erzwingen:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

Schlüsselverschlüsselungs-Algorithmen

In der folgenden Tabelle sind die verfügbaren Algorithmen für die Schlüsselverschlüsselung sowie der Schlüsseltyp aufgeführt, den Sie zur Überprüfung eines JWT mit diesem Schlüsselverschlüsselungsalgorithmus angeben müssen.

Wert von <Key> (Schlüsselverschlüsselungsalgorithmus) Für die Überprüfung erforderliches Schlüsselelement
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

Unter Verschlüsseltes JWT überprüfen finden Sie ein Beispiel, in dem der Schlüsselverschlüsselungsalgorithmus RSA-OAEP-256 ist, sodass Sie das Element <PrivateKey> verwenden.

Algorithmen für die Inhaltsverschlüsselung

Für die VerifyJWT-Richtlinie müssen Sie keinen Algorithmus für die Inhaltsverschlüsselung angeben. Wenn Sie den Algorithmus für die Inhaltsverschlüsselung angeben möchten, können Sie dies mit dem untergeordneten <Content> des Elements <Algorithms> tun.

Unabhängig vom Schlüsselverschlüsselungsalgorithmus werden die folgenden Algorithmen – alle symmetrischen und AES-basierten – für die Inhaltsverschlüsselung unterstützt:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

<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 –
Presence 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 –
Presence 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 –
Presence 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 –
Presence 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 beheben.

Standard false
Presence Optional
Typ Boolesch
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
Presence Optional
Typ Boolesch
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
Presence Optional
Typ Boolesch
Zulässige Werte "true" oder "false"

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

Die Richtlinie verifiziert, ob der Aussteller im JWT (die Anforderung iss) mit dem im Konfigurationselement angegebenen String übereinstimmt. Die iss-Anforderung ist eine der in IETF RFC 7519 genannten registrierten Ansprüche.

Standard –
Presence 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. Beispiele:

{
  "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 –
Presence Optional
Typ Kommagetrenntes Stringarray
Zulässige Werte Entweder ein Array oder der Name einer Variable, die das Array enthält.

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

Konfiguriert die VerifyJWT-Richtlinie, um zu prüfen, ob die Lebensdauer eines Tokens einen angegebenen Grenzwert nicht überschreitet. Sie können den Grenzwert mithilfe einer Zahl gefolgt von einem Zeichen angeben. Diese gibt die Anzahl der Sekunden, Minuten, Stunden, Tage oder Wochen an. Die folgenden Zeichen sind gültig:

  • s - Sekunden
  • m - Minuten
  • h - Stunden
  • d - Tage
  • w - Wochen

Sie können beispielsweise einen der folgenden Werte angeben: 120s, 10m, 1h, 7d, 3w.

Die Richtlinie berechnet die tatsächliche Lebensdauer des Tokens durch Subtrahieren des alten Werts (nbf) vom Ablaufwert (exp). Wenn entweder exp oder nbf fehlt, gibt die Richtlinie einen Fehler aus. Wenn die Tokenlebensdauer die angegebene Zeitspanne überschreitet, gibt die Richtlinie einen Fehler aus.

Sie können das optionale Attribut useIssueTime auf true setzen, um den Wert iat anstelle des Werts nbf zu verwenden, wenn die Token-Lebensdauer berechnet wird.

Die Verwendung des Elements MaxLifespan ist optional. Wenn Sie dieses Element verwenden, können Sie es nur einmal verwenden.

<PrivateKey>

Verwenden Sie dieses Element, um den privaten Schlüssel anzugeben, mit dem ein JWT verifiziert werden kann, das mit einem asymmetrischen Algorithmus verschlüsselt wurde. Es folgt eine Beschreibung der möglichen untergeordneten Elemente.

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Ein untergeordnetes Element des <PrivateKey>-Elements. Gibt das Passwort an, das die Richtlinie zum Entschlüsseln des privaten Schlüssels verwenden soll, wenn ein verschlüsseltes JWT überprüft wird. Verwenden Sie das Attribut ref, um das Passwort in einer Ablaufvariable zu übergeben.

Standard –
Presence Optional
Typ String
Zulässige Werte Eine Referenz für eine Ablaufvariable.

Hinweis: Sie müssen eine Ablaufvariable angeben. Apigee lehnt Richtlinienkonfigurationen, in denen das Passwort im Klartext angegeben wird, als ungültig ab. Die Ablaufvariable muss das Präfix "private" haben. z. B. private.mypassword.

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Untergeordnet unter dem Element <PrivateKey>. Gibt einen PEM-codierten privaten Schlüssel an, mit dem die Richtlinie ein verschlüsseltes JWT prüft. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben.

Standard –
Presence Erforderlich, um ein JWT zu überprüfen, das mit einem Verschlüsselungsalgorithmus für asymmetrische Schlüssel verschlüsselt wurde.
Typ String
Zulässige Werte Eine Ablaufvariable mit einem String, der einen privaten PEM-codierten RSA-Schlüsselwert darstellt.

Hinweis: Die Ablaufvariable muss das Präfix "private" haben. Beispiel: private.mykey

<PublicKey>

Gibt die Quelle für den öffentlichen Schlüssel an, der zum Verifizieren eines JWT verwendet wird, das mit einem asymmetrischen Algorithmus signiert wurde. Zu den Unterstützungsalgorithmen gehören RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512. Es folgt eine Beschreibung der möglichen untergeordneten Elemente.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
cert data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Ein untergeordnetes Element des <PublicKey>-Elements. Gibt das signierte Zertifikat an, das als Quelle des öffentlichen Schlüssels verwendet wird. Verwenden Sie das ref-Attribut, um das signierte Zertifikat in einer Ablaufvariablen zu übergeben, oder geben Sie das PEM-codierte Zertifikat direkt an.

Standard –
Presence Optional. Zum Verifizieren eines mit einem asymmetrischen Algorithmus signierten JWT müssen Sie das Element <Certificate>, <JWKS> oder <Value> verwenden, um den öffentlichen Schlüssel bereitzustellen.
Typ String
Zulässige Werte Eine Ablaufvariable oder ein String.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

Ein untergeordnetes Element des <PublicKey>-Elements. Gibt einen JWKS als Quelle öffentlicher Schlüssel an. Dies ist eine Liste der Schlüssel gemäß dem in IETF RFC 7517 – JSON Web Key (JWK) beschriebenen Format.

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 Apigee das JWKS für einen Zeitraum von 300 Sekunden im Cache. Wenn der Cache abläuft, ruft Apigee die JWKS-Datei noch einmal ab.

Standard –
Presence Optional. Zum Verifizieren eines mit einem asymmetrischen Algorithmus signierten JWT müssen Sie das Element <Certificate>, <JWKS> oder <Value> verwenden, um den öffentlichen Schlüssel bereitzustellen.
Typ String
Zulässige Werte

Sie können das JWKS auf eine von vier Arten angeben:

  • Literal als Textwert:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • indirekt mit dem Attribut ref, das eine Ablaufvariable angibt:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    Die referenzierte Variable sollte einen String enthalten, der einen JWKS darstellt.

  • indirekt über einen statischen URI mit dem Attribut uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • indirekt über einen dynamisch bestimmten URI mit dem Attribut uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

Ein untergeordnetes Element des <PublicKey>-Elements. Gibt den öffentlichen Schlüssel an, der zum Verifizieren der Signatur auf einem signierten JWT verwendet werden soll. Verwenden Sie das ref-Attribut, um den Schlüssel in einer Ablaufvariable zu übergeben, oder geben Sie den PEM-codierten Schlüssel direkt an.

Standard –
Presence Optional. Zum Verifizieren eines mit einem asymmetrischen Algorithmus signierten JWT müssen Sie das Element <Certificate>, <JWKS> oder <Value> verwenden, um den öffentlichen Schlüssel bereitzustellen.
Typ String
Zulässige Werte Eine Ablaufvariable oder ein String.

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

Das <RequiredClaims>-Element ist optional. Gibt eine durch Kommas getrennte Liste mit Namen von Anforderungen an, die bei der Verifizierung eines JWT in der JWT-Nutzlast vorhanden sein müssen. Das Element stellt sicher, dass das präsentierte JWT die erforderlichen Anforderungen enthält, validiert aber nicht den Inhalt der Anforderungen. Wenn eine der aufgelisteten Anforderungen nicht vorhanden ist, gibt die VerifyJWT-Richtlinie zur Laufzeit einen Fehler aus.

Standard –
Presence Optional
Typ String
Zulässige Werte Eine durch Kommas getrennte Liste von Anforderungsnamen.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>

Das SecretKey-Element ist optional. Es gibt den geheimen Schlüssel an, der beim Überprüfen eines signierten JWT, das einen symmetrischen Algorithmus (HS*) verwendet, oder beim Überprüfen eines verschlüsselten JWT, das einen symmetrischen Algorithmus (AES) für die Schlüsselverschlüsselung verwendet, angegeben werden soll.

Untergeordnete Elemente von <SecretKey>

In der folgenden Tabelle sind die untergeordneten Elemente und Attribute von <SecretKey> beschrieben:

Kind Presence Beschreibung
encoding (Attribut) Optional

Gibt an, wie der Schlüssel in der referenzierten Variable codiert ist. Wenn kein encoding-Attribut vorhanden ist, wird die Codierung des Schlüssels standardmäßig als UTF-8 behandelt. Gültige Werte für das Attribut sind: „hex“, „base16“, „base64“ und „base64url“. Die Codierungswerte „hex“ und „base16“ sind synonym.

<SecretKey encoding="hex" >
  <Value ref="private.secretkey"/>
</SecretKey>

Da im obigen Beispiel die Codierung hex lautet, wird der Schlüssel als Satz von 9 Byte decodiert, wenn die Variable private.secretkey den Inhalt 494c6f766541504973 hat. Im hex-Format ist das 49 4c 6f 76 65 41 50 49 73.

Value (Element) Erforderlich

Einen codierten geheimen Schlüssel Gibt den geheimen Schlüssel an, mit dem die Nutzlast überprüft wird. Verwenden Sie das Attribut ref, um den Schlüssel indirekt über eine Variable wie private.secret-key bereitzustellen .

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee erzwingt eine Mindestschlüsselstärke für die Algorithmen HS256/HS384/HS512. Die Mindestschlüssellänge für HS256 beträgt 32 Byte, für HS384 48 Byte und für HS512 64 Byte. Die Verwendung eines Schlüssels mit geringerer Stärke führt zu einem Laufzeitfehler.

<Source>

<Source>jwt-variable</Source>

Gibt, sofern vorhanden, die Ablaufvariable an, in der die Richtlinie das zu verifizierende JWT findet.

Mit diesem Element können Sie die Richtlinie so konfigurieren, dass das JWT aus einer Formular- oder Abfrageparametervariablen oder einer anderen Variablen abgerufen wird. Wenn dieses Element vorhanden ist, entfernt die Richtlinie kein vorhandenes Bearer-Präfix. Wenn die Variable nicht vorhanden ist oder die Richtlinie kein JWT in der angegebenen Variable findet, gibt die Richtlinie einen Fehler zurück.

Wenn kein <Source>-Element vorhanden ist, ruft die Richtlinie standardmäßig das JWT ab. Dazu wird die Variable request.header.authorization gelesen und das Präfix Bearer wird entfernt. Wenn Sie das JWT im Autorisierungs-Header als Inhabertoken (mit dem Präfix Bearer) übergeben, geben Sie das Element <Source> in der Richtlinienkonfiguration nicht an. Sie würden beispielsweise kein <Source>-Element in der Richtlinienkonfiguration verwenden, wenn Sie das JWT im Autorisierungs-Header so übergeben:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Standard request.header.authorization (Wichtige Informationen zur Standardeinstellung finden Sie im Hinweis oben).
Presence Optional
Typ String
Zulässige Werte Ein Name für eine Apigee-Ablaufvariable.

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

Die Richtlinie verifiziert, ob das Subjekt im JWT (die Anforderung sub) mit dem in der Richtlinienkonfiguration angegebenen String übereinstimmt. Die Anforderung sub ist eine der in RFC7519 beschriebenen registrierten Anforderungen.

Standard –
Presence Optional
Typ String
Zulässige Werte Jeder Wert, der ein Subjekt eindeutig identifiziert.

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

Der "Kulanzzeitraum" für Zeiten, um die Zeitverzögerung zwischen dem Aussteller und dem Verifizierer eines JWT zu berücksichtigen. Dies gilt sowohl für den Ablauf (die Anforderung exp) als auch für den "Not-before-Time" (die Anforderung nbf). Beispiel: Wenn das Zeitlimit auf 30s festgelegt ist, wird ein abgelaufenes JWT nach dem bestätigten Ablauf für 30 Sekunden als noch gültig behandelt. Das "not-before-time" wird ähnlich ausgewertet.

Standard 0 Sekunden (kein Kulanzzeitraum)
Presence Optional
Typ String
Zulässige Werte Ein Zeitraumausdruck oder ein Verweis auf eine Ablaufvariable, die einen Ausdruck enthält. Zeiträume können mit einer positiven Ganzzahl gefolgt von einem Zeichen angegeben werden, das eine Zeiteinheit angibt:
  • s = Sekunden
  • m = Minuten
  • h = Stunden
  • d = Tage

<Type>

<Type>type-string-here</Type>

Beschreibt, ob die Richtlinie ein signiertes oder ein verschlüsseltes JWT verifiziert. Das <Type>-Element ist optional. Sie können damit Leser über die Konfiguration informieren, unabhängig davon, ob die Richtlinie ein signiertes oder ein verschlüsseltes JWT generiert.

  • Wenn das Element <Type> vorhanden ist:
    • Wenn <Type> den Wert Signed hat, bestätigt die Richtlinie ein signiertes JWT und das Element <Algorithm> muss vorhanden sein.
    • Wenn <Type> den Wert Encrypted hat, bestätigt die Richtlinie ein verschlüsseltes JWT und das Element <Algorithms> muss vorhanden sein.
  • Wenn das Element <Type> nicht vorhanden ist:
    • Wenn das Element <Algorithm> vorhanden ist, geht die Richtlinie davon aus, dass <Type> den Wert Signed hat.
    • Wenn das Element <Algorithms> vorhanden ist, geht die Richtlinie davon aus, dass <Type> den Wert Encrypted hat.
  • Wenn weder <Algorithm> noch <Algorithms> vorhanden ist, ist die Konfiguration ungültig.
Standard –
Presence Optional
Typ String
Zulässige Werte Signed oder Encrypted.

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWT, this variable is not set.

Fehlerreferenz

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration 401 Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidIterationCount 401 The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS in the <PublicKey> element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
steps.jwt.InvalidSaltLength 401 The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "InvalidToken"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>