Criterio GenerateJWT

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Genera un JWT firmato, con un insieme di attestazioni configurabili. Il JWT può quindi essere restituito trasmessi a destinazioni di backend o utilizzati in altri modi. Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT.

Video

Guarda un breve video per scoprire come generare un JWT firmato.

Esempi

• Genera un JWT firmato con Algoritmo HS256
• Genera un JWT firmato con Algoritmo RS256

Genera un JWT firmato con HS256. algoritmo

Questo criterio di esempio genera un nuovo JWT e lo firma utilizzando l'algoritmo HS256. Si basa su HS256 su un secret condiviso sia per la firma che per la verifica della firma.

Quando viene attivata questa azione del criterio, Edge codifica l'intestazione JWT e il payload, quindi digitalmente firma il JWT. Guarda il video riportato sopra per un esempio completo, incluso come presentare una richiesta per violazione delle norme.

La configurazione dei criteri qui creerà un JWT con un insieme di attestazioni standard come definito la specifica JWT, inclusa una scadenza di 1 ora, nonché una richiesta aggiuntiva. Puoi includere tutte le rivendicazioni aggiuntive che desideri. Consulta la sezione di riferimento dell'elemento per maggiori dettagli in requisiti e opzioni per ogni elemento di questa norma di esempio.

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

Il JWT risultante avrà questa intestazione...

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

... e avranno un payload con contenuti simili a questo:

{ 
  "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."
}

Il valore delle rivendicazioni iat, exp e jti può variare.

Genera un JWT firmato con RS256 algoritmo

Questo criterio di esempio genera un nuovo JWT e lo firma utilizzando l'algoritmo RS256. La generazione di un La firma RS256 si basa su una chiave privata RSA, che deve essere fornita in formato con codifica PEM. Guarda il video riportato sopra per un esempio completo, incluso come presentare una richiesta per violazione delle norme.

Quando viene attivata questa azione del criterio, Edge codifica e firma digitalmente il JWT, incluse le attestazioni. Per saperne di più sulle parti di un JWT e su come vengono criptate e firmate, consulta 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>

Impostare gli elementi chiave

Gli elementi che utilizzi per specificare la chiave usata per generare il JWT dipendono dall'algoritmo scelto, come illustrato nella tabella seguente:

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

Riferimento elemento per Genera JWT

La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio Genera JWT.

Nota:la configurazione varierà leggermente a seconda della crittografia. l'algoritmo utilizzato. Fai riferimento agli esempi per esempi che dimostrano configurazioni per casi d'uso specifici.

Attributi che applica all'elemento di primo livello

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali del criterio.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare, in aggiunta all'attributo name, per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Il criterio genera un JWT contenente un'attestazione aud impostata sul valore specificato valore. Questa dichiarazione identifica i destinatari a cui è destinato il JWT. Questo è uno dei rivendicazioni registrate menzionate in RFC7519.

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

Ti consente di specificare ulteriori coppie nome/valore di rivendicazione nel payload del JWT. Puoi specificare la dichiarazione in modo esplicito come stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di nomi/valori in coppia.

L'elemento <Claim> utilizza i seguenti attributi:

• name - (Obbligatorio) Il nome della rivendicazione.
• ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questo come la dichiarazione. Se vengono specificati sia un attributo ref sia un valore di dichiarazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile del flusso di riferimento non è risolta.
• type: (facoltativo) uno dei seguenti: string (predefinito), numero, booleano o mappa
• array - (Facoltativo) Imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Se includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico quando e configurare il criterio. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle attestazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle attestazioni nel JWT generato vengono determinati in fase di runtime.

Ad esempio:

<AdditionalClaims ref='json_claims'/>

Dove la variabile json_claims contiene un oggetto JSON nel formato:

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

Il JWT generato include tutte le attestazioni nell'oggetto JSON.

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

Consente di inserire le altre coppie nome/valore della rivendicazione nell'intestazione del JWT.

L'elemento <Claim> utilizza i seguenti attributi:

• name - (Obbligatorio) Il nome della rivendicazione.
• ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questo come la dichiarazione. Se vengono specificati sia un attributo ref sia un valore di dichiarazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile del flusso di riferimento non è risolta.
• type: (facoltativo) uno dei seguenti: string (predefinito), numero, booleano o mappa
• array - (Facoltativo) Imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Aggiunge l'intestazione critica, crit, all'intestazione JWT. Intestazione crit è un array di nomi di intestazione che devono essere noti e riconosciuti dal ricevitore JWT. Ad esempio:

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

In fase di runtime, il criterio VerifyJWT esamina l'intestazione crit. Per ogni elemento elencato nell'intestazione crit, viene verificato che l'elemento <KnownHeaders> del criterio VerifyJWT elenca anche quell'intestazione. Qualsiasi intestazione trovata dal criterio VerifyJWT in crit che non è elencato anche in <KnownHeaders>, causa l'errore del criterio VerifyJWT.

<CustomClaims>

Nota: al momento, viene inserito un elemento CustomClaim quando aggiungi una nuova il criterio GeneraJWT tramite l'interfaccia utente. Questo elemento non è funzionale e viene ignorato. Il corretto invece è <AdditionalClaims>. L'interfaccia utente aggiornarli per inserire gli elementi corretti in un secondo momento.

<ExpiresIn>

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

Specifica la durata del JWT in millisecondi, secondi, minuti, ore o giorni.

<Id>

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

Genera un JWT con la specifica dichiarazione jti. Quando il valore text e l'attributo ref sono entrambi vuoto, il criterio genererà un jti contenente un UUID casuale. L'attestazione dell'ID JWT (jti) è un identificatore univoco del JWT. Per ulteriori informazioni su jti, consulta RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore false se vuoi che il criterio generi un errore quando viene specificata una variabile di riferimento. del criterio non è risolvibile. Imposta il valore su true per trattare le variabili irrisolvibili come stringhe vuote (nullo).

<Issuer>

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

Il criterio genera un JWT contenente un'attestazione denominata iss,con un valore impostato al valore specificato. Una dichiarazione che identifica l'emittente del JWT. Questo è uno dei insieme registrato di rivendicazioni menzionate in RFC7519.

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

Specifica l'ora in cui il token diventa valido. Il token non è valido fino all'ora specificata. Puoi specificare un valore di tempo assoluto o un'ora relativa a quando viene generato il token.

Valori di tempo validi per l'elemento NotBefore per valori di tempo assoluti

Per i valori di tempo relativi, specifica un numero intero e un periodo di tempo, ad esempio:

• 10 sec
• 60 min
• 12 ore

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Specifica dove posizionare il JWT generato da questo criterio. Per impostazione predefinita, viene posizionata la variabile di flusso jwt.POLICYNAME.generated_jwt.

<PrivateKey/Id>

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

or

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

Specifica l'ID chiave (kid) da includere nell'intestazione JWT. Utilizza solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<PrivateKey/Password>

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

Specifica la password che il criterio deve utilizzare per decriptare la chiave privata, se necessario. Utilizza la ref per passare la chiave in una variabile di flusso. Utilizza solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<PrivateKey/Value>

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

Specifica una chiave privata con codifica PEM utilizzata per firmare il JWT. Utilizza l'attributo ref per passare chiave in una variabile di flusso. Utilizzare solo se l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<SecretKey/Id>

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

or

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

Specifica l'ID chiave (kid) da includere nell'intestazione JWT di un JWT firmato con un HMAC dell'algoritmo. Da utilizzare solo se l'algoritmo è uno dei seguenti: HS256/HS384/HS512.

<SecretKey/Value>

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

Fornisce la chiave segreta utilizzata per verificare o firmare i token con un algoritmo HMAC. Utilizza solo quando l'algoritmo è uno di HS256/HS384/HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Edge applica una forza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è di 32 byte, per HS384 è di 48 byte e per HS512 è di 64 byte. L'utilizzo di una chiave a potenza inferiore causa un errore di runtime.

<Subject>

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

<Subject ref="flow_variable" />

Ad esempio:

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

Il criterio genera un JWT contenente una rivendicazione sub, impostata sul valore specificato value.Questa dichiarazione identifica o fa una dichiarazione in merito all'oggetto del JWT. Questo è uno dei insieme standard di attestazioni citate in RFC7519.

Variabili di flusso

Il criterio Genera JWT non imposta le variabili di flusso.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

Fault variables

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

Example error response

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 "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>