GenerateJWT-Richtlinie

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

Was

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

Video

In diesem kurzen Video erfahren Sie, wie Sie ein signiertes JWT generieren.

Samples

• Ein mit dem HS256-Algorithmus signiertes JWT generieren
• Ein mit dem RS256-Algorithmus signiertes JWT generieren

Ein mit dem HS256-Algorithmus signiertes JWT generieren

Diese Beispielrichtlinie generiert ein neues JWT und signiert es unter Einsatz des HS256-Algorithmus. HS256 stützt sich auf ein gemeinsames Secret für die Signatur und die Verifizierung der Signatur.

Wenn diese Richtlinienaktion ausgelöst wird, codiert Edge den JWT-Header und die Nutzlast und signiert das JWT digital. Das Video oben zeigt ein umfassendes Beispiel, in dem auch beschrieben wird, wie Sie eine Anfrage an die Richtlinie senden.

Die Richtlinienkonfiguration erstellt in diesem Fall ein JWT mit einem Standardanforderungssatz, wie in der JWT-Spezifikation definiert, einschließlich einer Ablaufzeit von 1 Stunde sowie einer zusätzlichen Anforderung. Sie können beliebig viele zusätzliche Anforderungen hinzufügen. Details zu den Anforderungen und Optionen für die einzelnen Elemente in dieser Beispielrichtlinie finden Sie in der Elementreferenz.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Das resultierende JWT hat dann folgenden Header…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

… und eine Nutzlast mit Inhalten wie diesem:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

Der Wert der Anforderungen iat, exp und jti variiert.

Ein mit dem RS256-Algorithmus signiertes JWT generieren

Diese Beispielrichtlinie generiert ein neues JWT und signiert es unter Einsatz des RS256-Algorithmus. Das Generieren einer RS256-Signatur benötigt einen privaten RSA-Schlüssel, der in PEM-codierter Form bereitgestellt werden muss. Das Video oben zeigt ein umfassendes Beispiel, in dem auch beschrieben wird, wie Sie eine Anfrage an die Richtlinie senden.

Wenn diese Richtlinienaktion ausgelöst wird, codiert Edge das JWT einschließlich der Anforderungen und signiert es digital. Informationen zu den Teilen eines JWT und deren Verschlüsselung und Signatur finden Sie unter RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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 das JWT generieren

Die Richtlinienreferenz beschreibt die Elemente und Attribute der Richtlinie zur JWT-Generierung.

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

<GenerateJWT name="JWT" 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.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Die Richtlinie generiert ein JWT, das eine aud-Anforderung mit dem angegebenen Wert enthält. Diese Anforderung identifiziert die Empfänger, für die das JWT bestimmt ist. Dies ist eine der in RFC7519 genannten registrierten Anforderungen.

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

Ermöglicht die Angabe zusätzlicher Name/Wert-Paare für Anforderungen in der Nutzlast des JWT. Sie können die Anforderung explizit als String, Zahl, booleschen Wert, Zuordnung oder Array angeben. Ein Map ist einfach eine Reihe von Name/Wert-Paaren.

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 im generierten JWT zur Laufzeit bestimmt.

Beispiel:

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

Das generierte JWT enthält alle Anforderungen im JSON-Objekt.

<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 dem JWT-Header den kritischen Header crit hinzu. Der Header crit ist ein Array aus Headernamen, die bekannt sein und vom JWT-Empfänger erkannt werden müssen. Beispiel:

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

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

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

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

Gibt die Lebensdauer des JWT in Millisekunden, Sekunden, Minuten, Stunden oder Tagen an.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Generiert ein JWT mit der spezifischen jti-Anforderung. Wenn der Textwert und das ref-Attribut beide leer sind, generiert die Richtlinie einen 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.

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Die Richtlinie generiert ein JWT, das eine Anforderung mit dem Namen iss, mit einem auf den angegebenen Wert gesetzten Wert enthält. Eine Anforderung, die den Aussteller des JWT identifiziert. Dies ist eine der registrierten Anforderungen, die in RFC7519 erwähnt werden.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Gibt die Uhrzeit an, zu der das Token gültig wird. Das Token ist bis zur angegebenen Zeit ungültig. Sie können entweder einen absoluten Zeitwert oder eine Zeit relativ zum Zeitpunkt der Generierung des Tokens angeben.

Gültige Zeitwerte für das "NotBefore"-Element für absolute Zeitwerte

Geben Sie für relative Zeitwerte eine Ganzzahl und einen Zeitraum an. Beispiel:

• 10s
• 60m
• 12h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Gibt an, wo das von dieser Richtlinie generierte JWS platziert werden soll. Standardmäßig wird es in die Ablaufvariable jwt.POLICYNAME.generated_jwt eingefügt.

<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 JWT-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 des JWT 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 JWT-Header eines mit einem HMAC-Algorithmus signierten JWT einzufügen ist. Nur verwenden, wenn der folgenden Algorithmen verwendet wurde: HS256/HS384/HS512.

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

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

Beispiel:

<Subject ref="apigee.developer.email"/>

Die Richtlinie generiert ein JWT mit einem sub-Anspruch, der auf den angegebenen Wert gesetzt ist. Mit diesem Anspruch wird eine Aussage über das Subjekt des JWT identifiziert oder gemacht. Dies ist einer der Standardansprüche, die in RFC7519 erwähnt werden.

Ablaufvariablen

Die Richtlinie zum Generieren von JWTs 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 bereitstellen, der diese Richtlinie enthält.

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