GenerateJWS-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie 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 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, Edge codiert den JWS-Header und die Nutzlast und fügt dann die codierte Signatur zum digitalen Signieren der JWS hinzu.

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 generiert damit die codierte Signatur. 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:

Algorithmus Schlüsselelemente
HS{256/384/512}*
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}*
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Die Elemente <Password> und <Id> sind optional.

* Weitere Informationen zu den Schlüsselanforderungen finden Sie unter Signaturverschlüsselungsalgorithmen.

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.

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

Gibt den Verschlüsselungsalgorithmus zum Signieren des Tokens an.

Default
Präsenz Erforderlich
Typ String
Zulässige Werte HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

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

Default
Präsenz Optional
Zulässige Werte Jeder Wert, den Sie für eine zusätzliche Anforderung verwenden möchten. Sie können die Anforderung explizit als String, Zahl, booleschen Wert, Zuordnung oder Array angeben.

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

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

Standard
Präsenz Optional
Typ Kommagetrenntes Stringarray
Zulässige Werte Entweder ein Array oder der Name einer Variable, die das Array enthält.

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

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"

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

Standard jws.POLICYNAME.generated_jws
Präsenz Optional
Typ String (Name einer Ablaufvariablen)

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

Standard
Präsenz Erforderlich
Typ String, Byte-Array, Stream oder eine andere Darstellung der nicht codierten JWS-Nutzlast.

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

Standard
Präsenz Optional
Typ String
Zulässige Werte Eine Ablaufvariable oder ein String

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

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

Hinweis: Sie müssen eine Ablaufvariable angeben. Edge wird als ungültig abgelehnt Richtlinienkonfiguration, bei der das Passwort als Klartext angegeben wird. Die Ablaufvariable muss das Präfix "private" haben. Beispiel: private.mypassword.

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

Standard
Präsenz Zum Generieren einer JWS mithilfe des RS256-Algorithmus erforderlich.
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

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

Standard
Präsenz Optional
Typ String
Zulässige Werte Eine Ablaufvariable oder ein String

<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 Mindestschlüsselstärke für die HS256/HS384/HS512-Algorithmen. 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.

Standard
Präsenz Erforderlich für HMAC-Algorithmen.
Typ String
Zulässige Werte Eine Ablaufvariable, die auf einen String verweist.

Hinweis: Wenn eine Ablaufvariable vorhanden ist, muss sie das Präfix "private" haben. Beispiel: private.mysecret

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.

Fehlercode HTTP-Status Tritt auf, wenn Folgendes eintritt
steps.jws.GenerationFailed 401 Die Richtlinie konnte das JWS nicht generieren.
steps.jws.InsufficientKeyLength 401 Für Schlüssel mit weniger als 32 Byte für den HS256-Algorithmus
steps.jws.InvalidClaim 401 Bei einem fehlenden Anspruch oder nicht übereinstimmenden Ansprüchen oder einem fehlenden Header oder Header.
steps.jws.InvalidCurve 401 Die vom Schlüssel angegebene Kurve ist für den Elliptic-Curve-Algorithmus ungültig.
steps.jws.InvalidJsonFormat 401 Ungültige JSON-Datei im JWS-Header
steps.jws.InvalidPayload 401 Die JWS-Nutzlast ist ungültig.
steps.jws.InvalidSignature 401 <DetachedContent> wird weggelassen und das JWS hat eine separate Inhaltsnutzlast.
steps.jws.KeyIdMissing 401 Die Überprüfungsrichtlinie verwendet eine JWKS als Quelle für öffentliche Schlüssel. Die signierte JWS enthält jedoch keine kid-Property im Header.
steps.jws.KeyParsingFailed 401 Der öffentliche Schlüssel konnte anhand der angegebenen Schlüsselinformationen nicht geparst werden.
steps.jws.MissingPayload 401 Die JWS-Nutzlast fehlt.
steps.jws.NoAlgorithmFoundInHeader 401 Tritt auf, wenn der JWS den Algorithmusheader weglässt.
steps.jws.SigningFailed 401 In GenerateJWS, für Schlüssel, die kleiner als die Mindestgröße für den HS384- oder HS512-Algorithmus sind
steps.jws.UnknownException 401 Es ist eine unbekannte Ausnahme aufgetreten.
steps.jws.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 mit dieser Richtlinie bereitstellen.

Fehlername Tritt auf, wenn Folgendes eintritt
InvalidAlgorithm Die einzigen gültigen Werte sind: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Andere mögliche Bereitstellungsfehler.

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"
JWS.failed Bei allen JWT-Richtlinien wird im Fall eines Fehlers dieselbe Variable festgelegt. jws.JWS-Policy.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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>