VerifyJWS-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was

Verifiziert die Signatur auf einer JWS, die von Clients oder anderen Systemen empfangen wurde. Diese Richtlinie extrahiert auch Header 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 die JWS überprüft wurde und gültig ist, kann die Anfrage fortgesetzt werden. Wenn die JWS-Signatur nicht überprüft werden kann oder wenn die JWS aufgrund eines bestimmten Fehlers ungültig ist, wird die gesamte Verarbeitung beendet und in der Antwort wird ein Fehler zurückgegeben.

Informationen zu den Teilen einer JWS und deren Verschlüsselung und Signatur finden Sie unter RFC7515.

Video

In einem kurzen Video erfahren Sie, wie Sie die Signatur auf einer JWS überprüfen können. Dieses Video ist speziell für die Überprüfung eines JWT vorgesehen, viele der Konzepte sind jedoch für JWS identisch.

Beispiele

• Prüfen Sie eine angehängte JWS, die mit dem HS256-Algorithmus signiert ist.
• Prüfen Sie eine angehängte JWS, die mit dem RS256-Algorithmus signiert ist.

Angehängte JWS mit dem HS256-Algorithmus signieren überprüfen

Diese Beispielrichtlinie verifiziert eine angehängte JWS, die mit dem HS256-Verschlüsselungsalgorithmus HMAC mit einem SHA-256-Prüfsumme signiert wurde. Die JWS wird in der Proxyanfrage mit einem Formularparameter namens JWS übergeben. Der Schlüssel ist in einer Variablen mit dem Namen private.secretkey enthalten.

Eine angehängte JWS enthält den codierten Header, die Nutzlast und die Signatur:

header.payload.signature

Die Richtlinienkonfiguration enthält die Informationen, die Edge zum Decodieren und Auswerten der JWS benötigt, z. B. wo die JWS zu finden ist (in einer im Element <Source> angegebenen Flussvariablen), den erforderlichen Signaturalgorithmus und den Ort, an dem der geheime Schlüssel zu finden ist (gespeichert in einer Edge-Flussvariablen, die beispielsweise aus der Edge-KVM abgerufen werden könnte).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

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.

Separates JWS, das mit dem RS256-Algorithmus signiert wurde

Diese Beispielrichtlinie verifiziert eine getrennte JWS, die mit dem RS256-Algorithmus signiert wurde. Zur Überprüfung müssen Sie den öffentlichen Schlüssel angeben. Die JWS wird in der Proxyanfrage mithilfe eines Formularparameters mit dem Namen JWS übergeben. Der öffentliche Schlüssel ist in einer Variablen mit dem Namen public.publickey enthalten.

Eine getrennte JWS lässt die Nutzlast der JWS aus:

header..signature

Sie können die Nutzlast an die VerifyJWS-Richtlinie übergeben. Dazu geben Sie den Variablennamen, der die Nutzlast enthält, an das Element <DetachedContent> an. Der angegebene Inhalt in <DetachedContent> muss im ursprünglichen nicht codierten Format angegeben werden, als es die JWS-Signatur erstellt hat.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

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 verwenden, um den Schlüssel zur Überprüfung des JWS anzugeben, hängt vom ausgewählten Algorithmus ab, wie in der folgenden Tabelle dargestellt:

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

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

Elementverweis

In der Richtlinienreferenz werden die Elemente und Attribute der Richtlinie zum Verifizieren des JWS 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

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

Die folgenden Attribute gelten für alle übergeordneten Richtlinienelemente.

<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.

<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.

<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 JWS-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 JWS-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.

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.

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

Eine generierte JWS mit einer Inhaltsnutzlast hat folgendes Format:

header.payload.signature

Wenn Sie die GenerateJWS-Richtlinie zum Erstellen einer getrennten Nutzlast verwenden, wird die Nutzlast im generierten JWS weggelassen. Sie hat das folgende Format:

header..signature

Bei einer getrennten Nutzlast müssen Sie die Nutzlast mithilfe des <DetachedContent> - Elements an die VerifyJWS-Richtlinie übergeben. Die angegebene Inhaltsnutzlast muss in der ursprünglichen, nicht codierten Form angegeben werden, die sie hatte, als die JWS-Signatur erstellt wurde.

Die Richtlinie gibt einen Fehler aus, wenn:

• <DetachedContent> wird angegeben, wenn die JWS keine getrennte Inhaltsnutzlast enthält (Fehlercode steps.jws.ContentIsNotDetached).
• <DetachedContent> wird weggelassen und die JWS hat eine getrennte Inhaltsnutzlast (Fehlercode ist steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Auf "false" setzen, wenn die Richtlinie einen Fehler ausgibt, wenn ein im Crit-Header des JWS nicht im <KnownHeaders>-Element aufgelistet ist. Setzen Sie den Wert auf "true", damit die VerifyJWS-Richtlinie den Header crit ignoriert.

Ein Grund, dieses Element auf „true“ zu setzen, ist, wenn Sie sich in einer Testumgebung befinden und nicht möchten, dass die Richtlinie aufgrund eines fehlenden Headers fehlschlägt.

<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).

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Die GenerateJWS-Richtlinie verwendet das Element <CriticalHeaders>, um den crit-Header in einen Token zu füllen. Beispiel:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Die VerifyJWS-Richtlinie prüft den Header crit in der JWS, sofern vorhanden, und für jedes aufgeführte Element prüft, ob das Element <KnownHeaders> auch diesen Header enthält. 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, aber nicht in der <KnownHeaders>-Liste aufgeführt ist, lässt die VerifyJWS-Richtlinie fehlschlagen.

Sie können die VerifyJWS-Richtlinie optional konfigurieren, um den Header crit zu ignorieren. Dazu setzen Sie das Element <IgnoreCriticalHeaders> auf true.

<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 die eingehende JWS eine Schlüssel-ID enthält, die im Satz von JWKS vorhanden ist, verwendet die Richtlinie den richtigen öffentlichen Schlüssel, um die JWS-Signatur zu überprüfen. Weitere Informationen zu dieser Funktion finden Sie unter JSON Web Key Set (JWKS) zur Überprüfung einer JWS verwenden.

Wenn Sie den Wert von einer öffentlichen URL abrufen, speichert Edge den JWKS für einen Zeitraum von 300 Sekunden im Cache. Wenn der Cache abläuft, ruft Edge den JWKS erneut ab.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</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 an, mit dem die Signatur auf dem JWS überprüft wird. Verwenden Sie das ref-Attribut, um den Schlüssel 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.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Stellt den geheimen Schlüssel bereit, mit dem Tokens mit einem HMAC-Algorithmus überprüft oder signiert werden. Nur verwenden, wenn der Algorithmus eines der HS256, HS384 oder HS512 ist. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben.

<Source>

<Source>JWS-variable</Source>

Wenn dieses Flag angegeben ist, wird die Ablaufvariable angegeben, in der die Richtlinie die zu suchende JWS erwartet.

Ablaufvariablen

Bei Erfolg legen die Richtlinien VerifyJWS und DecodeJWS Kontextvariablen gemäß diesem Muster fest:

jws.{policy_name}.{variable_name}

Beispiel: Lautet der Richtlinienname verify-jws, so speichert die Richtlinie den im JWS angegebene Algorithmus in dieser Kontextvariable: jws.verify-jws.header.algorithm

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.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>