GenerateJWS-Richtlinie

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

Was

Generiert ein signiertes JWS mit einem konfigurierbaren Satz von Anforderungen. Das JWT kann dann an Clients zurückgegeben, an Back-End-Ziele übertragen oder auf andere Weise genutzt werden. Eine detaillierte Einführung finden Sie unter Übersicht über JWS- und JWT-Richtlinien.

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

Video

In diesem kurzen Video erfahren Sie, wie Sie ein signiertes JWT generieren. Obwohl dieses Video speziell für die Generierung eines JWT gedacht ist, sind viele der Konzepte für JWS identisch.

Beispiele

• Angehängte mit dem HS256-Algorithmus signierte JWS generieren
• Getrennte JWS generieren, die mit dem RS256-Algorithmus signiert wurde

Angehängte mit dem HS256-Algorithmus signierte JWS verifizieren

Diese Beispielrichtlinie generiert eine angehängte JWS und signiert sie mit dem HS256-Algorithmus. HS256 stützt sich auf ein gemeinsames Secret für die Signatur und die Verifizierung der Signatur.

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

header.payload.signature

Setzen Sie <DetachContent> auf „wahr“, um getrennte Inhalte zu generieren. Weitere Informationen zur Struktur und zum Format von JWS finden Sie unter Teile eines JWS/JWT.

Mit dem Element <Payload> geben Sie die nicht codierte JWS-Rohnutzlast an. In diesem Beispiel enthält eine Variable die Nutzlast. Wenn diese Richtlinienaktion ausgelöst wird, codiert Edge den JWS-Header und die Nutzlast und fügt dann die codierte Signatur hinzu, um die JWS digital zu signieren.

Die unten stehende Richtlinienkonfiguration erstellt eine JWS aus einer Nutzlast, die in der Variable private.payload enthalten ist.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Eine getrennte JWS generieren, die mit dem RS256-Algorithmus signiert wurde

Diese Beispielrichtlinie generiert eine getrennte JWS und signiert sie mit dem RS256-Algorithmus. Das Generieren einer RS256-Signatur benötigt einen privaten RSA-Schlüssel, der in PEM-codierter Form bereitgestellt werden muss.

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

header..signature

Mit dem Element <Payload> geben Sie die nicht codierte JWS-Rohnutzlast an. Wenn diese Richtlinie ausgelöst wird, codiert Edge den JWS-Header und die Nutzlast und verwendet diese dann, um die codierte Signatur zu generieren. In der generierten JWS wird die Nutzlast jedoch weggelassen. Sie können die Nutzlast mithilfe des Elements <DetachedContent> der VerifyJWS-Richtlinie an die VerifyJWS-Richtlinie übergeben.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Schlüsselelemente festlegen

Welche Elemente Sie verwenden, um den Schlüssel zur Generierung der JWS anzugeben, hängt vom ausgewählten Algorithmus ab, wie in der folgenden Tabelle dargestellt:

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

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

Elementreferenz für GenerateJWS

Die Richtlinienreferenz beschreibt die Elemente und Attribute der GenerateJWS-Richtlinie.

Hinweis: Die Konfiguration variiert je nach verwendetem Verschlüsselungsalgorithmus. In den Beispielen finden Sie Beispiele für Konfigurationen von bestimmten Anwendungsfällen.

Attribute, die auf das oberste Element angewendet werden

<GenerateJWS 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>algorithm-here</Algorithm>

Gibt den Verschlüsselungsalgorithmus zum Signieren des Tokens an.

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

Fügt die zusätzlichen Paare aus Anforderungsname/Wert in den Header für die JWS ein.

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.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Fügt der JWS den kritischen Header crit hinzu. Der Header crit ist ein Array aus Headernamen, die bekannt sein und vom JWS-Empfänger erkannt werden müssen. Beispiel:

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

Zur Laufzeit untersucht die VerifyJWS-Richtlinie den crit-Header. Für jeden im crit-Header aufgeführten Header wird überprüft, ob das Element <KnownHeaders> der VerifyJWS-Richtlinie auch diesen Header enthält. Jeder Header, den die VerifyJWS-Richtlinie in crit findet, der aber nicht in <KnownHeaders> aufgeführt ist, lässt die VerifyJWS-Richtlinie fehlschlagen.

<DetachContent>

<DetachContent>true|false</DetachContent>

Gibt an, ob die JWS mit einer getrennten Nutzlast (<DetachContent>true</DetachContent>) oder nicht (<DetachContent>false</DetachContent>) generiert werden soll.

Wenn Sie "false" angeben, hat die standardmäßig erstellte JWS folgendes Format:

header.payload.signature

Wenn Sie "true" festlegen, um getrennte Nutzlasten zu erstellen, wird die Nutzlast in der erzeugten JWS weggelassen und sie hat folgendes Format:

header..signature

Bei einer getrennten Nutzlast können Sie die ursprüngliche, nicht codierte Nutzlast mithilfe des Elements <DetachedContent> der VerifyJWS-Richtlinie übergeben.

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Gibt an, wo die von dieser Richtlinie generierte JWS platziert werden soll. Standardmäßig wird sie in die Ablaufvariable jws.POLICYNAME.generated_jws eingefügt.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Gibt die unformatierte nicht codierte JWS-Nutzlast an. Geben Sie eine Variable mit der Nutzlast oder einen String an.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Gibt die Schlüssel-ID (kid) an, die im JWS-Header enthalten sein muss. Nur verwenden, wenn der Algorithmus RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512 ist.

<PrivateKey/Password>

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

Falls erforderlich, geben Sie das Passwort an, das die Richtlinie zum Entschlüsseln des privaten Schlüssels verwenden soll. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben. Nur verwenden, wenn der Algorithmus RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512 ist.

<PrivateKey/Value>

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

Gibt einen PEM-codierten privaten Schlüssel an, der zum Signieren der JWS verwendet wird. Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben. Nur verwenden, wenn der Algorithmus RS256/RS384/RS512, PS256/PS384/PS512 oder ES256/ES384/ES512 ist.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Gibt die Schlüssel-ID (kid) an, die in den JWS-Header einer JWS mit einem HMAC-Algorithmus enthalten sein soll. Nur verwenden, wenn der Algorithmus einer von HS256/HS384/HS512 ist.

<SecretKey/Value>

<SecretKey>
  <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 folgenden Algorithmen verwendet wurde: HS256/HS384/HS512 Verwenden Sie das Attribut ref, um den Schlüssel in einer Ablaufvariable zu übergeben.

Edge erzwingt eine minimale Schlü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.

Ablaufvariablen

Die GenerateJWS-Richtlinie legt keine Ablaufvariablen fest.

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>