Criterio VerifyJWT

Norme standard

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio VerifyJWT verifica un JWT firmato o decripta e verifica un JWT criptato ricevuto da client o altri sistemi. Queste norme estraggono anche le rivendicazioni in variabili di contesto in modo che le norme o le condizioni successive possano esaminare questi valori per prendere decisioni di autorizzazione o routing. Per un'introduzione dettagliata, consulta la panoramica dei criteri JWS e JWT.

Quando questo criterio viene eseguito, nel caso di un JWT firmato, Apigee verifica la firma del JWT utilizzando la chiave di verifica fornita. Nel caso di un JWT criptato, Apigee lo decripta utilizzando la chiave di decriptazione. In entrambi i casi, Apigee verifica successivamente che il JWT sia valido in base alle ore di scadenza e di inizio validità, se presenti. La norma può anche verificare facoltativamente i valori di rivendicazioni specifiche nel JWT, come il soggetto, l'emittente, il pubblico o il valore di rivendicazioni aggiuntive.

Se il JWT viene verificato ed è valido, tutte le rivendicazioni contenute al suo interno vengono estratte in variabili di contesto per l'utilizzo da parte di criteri o condizioni successivi e la richiesta può procedere. Se la firma JWT non può essere verificata o se il JWT non è valido a causa di uno dei timestamp, tutta l'elaborazione si interrompe e nella risposta viene restituito un errore.

Se la policy verifica un JWT firmato o criptato dipende dall'elemento che utilizzi per specificare l'algoritmo che verifica il JWT:

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Per informazioni sulle parti di un JWT e su come vengono criptate e firmate, consulta RFC7519.

Verificare un JWT firmato

Questa sezione spiega come verificare un JWT firmato. Per un JWT firmato, utilizza l'elemento <Algorithm> per specificare l'algoritmo per la firma della chiave.

Esempi di un JWT firmato

Gli esempi riportati di seguito mostrano come verificare un JWT firmato.

Algoritmo HS256

Questo criterio di esempio verifica un JWT firmato con l'algoritmo di crittografia HS256, HMAC utilizzando un checksum SHA-256. Il JWT viene passato nella richiesta proxy utilizzando un parametro del modulo denominato jwt. La chiave è contenuta in una variabile denominata private.secretkey. Guarda il video qui sopra per un esempio completo, incluso come presentare una richiesta relativa alle norme.

La configurazione del criterio include le informazioni necessarie ad Apigee per decodificare e valutare il JWT, ad esempio dove trovare il JWT (in una variabile di flusso specificata nell'elemento Source), l'algoritmo di firma richiesto, dove trovare la chiave segreta (memorizzata in una variabile di flusso Apigee, che potrebbe essere stata recuperata, ad esempio, da Apigee KVM) e un insieme di rivendicazioni richieste e i relativi valori.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

Il criterio scrive il suo output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da queste norme.

Algoritmo RS256

Questa policy di esempio verifica un JWT firmato con l'algoritmo RS256. Per la verifica, devi fornire la chiave pubblica. Il JWT viene passato nella richiesta proxy utilizzando un parametro del modulo denominato jwt. La chiave pubblica è contenuta in una variabile denominata public.publickey. Guarda il video qui sopra per un esempio completo, incluso come effettuare una richiesta alla norma.

Per informazioni dettagliate sui requisiti e sulle opzioni per ogni elemento di queste norme di esempio, consulta la documentazione di riferimento sugli elementi.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

Per la configurazione precedente, un JWT con questa intestazione…

{
  "typ" : "JWT",
  "alg" : "RS256"
}

E questo payload…

{
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

… verrà considerata valida se la firma può essere verificata con la chiave pubblica fornita.

Un JWT con la stessa intestazione, ma con questo payload…

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

… verrà considerato non valido, anche se la firma può essere verificata, perché l'attestazione "sub" inclusa nel JWT non corrisponde al valore richiesto dell'elemento "Subject" come specificato nella configurazione delle norme.

Il criterio scrive il suo output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da queste norme.

Gli esempi precedenti utilizzano l'elemento <Algorithm>, quindi verificano un JWT firmato. L'elemento <PrivateKey> specifica la chiave utilizzata per firmare il JWT. Esistono anche altri elementi chiave. Quello che utilizzi dipende dall'algoritmo specificato dal valore di <Algorithm>, come descritto nella sezione successiva.

Impostazione degli elementi chiave per verificare un JWT firmato

I seguenti elementi specificano la chiave utilizzata per verificare un JWT firmato:

L'elemento che utilizzi dipende dall'algoritmo scelto, come mostrato nella tabella seguente:

Algoritmo Elementi chiave
HS* 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, ES*, PS* 
<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

oppure:

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

oppure:

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>
*Per saperne di più sui requisiti delle chiavi, consulta Informazioni sugli algoritmi di crittografia della firma.

Verificare un JWT criptato

Questa sezione spiega come verificare un JWT criptato. Per un JWT criptato, utilizza l'elemento <Algorithms> per specificare gli algoritmi per la firma della chiave e dei contenuti.

Esempio di JWT criptato

Il seguente esempio mostra come verificare un JWT criptato (con <Type> impostato su Encrypted), in cui:

  • La chiave è criptata con l'algoritmo RSA-OAEP-256.
  • I contenuti sono criptati con l'algoritmo A128GCM.
<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

L'esempio precedente utilizza l'elemento <Algorithms>, quindi verifica un JWT criptato. L'elemento <PrivateKey> specifica la chiave che verrà utilizzata per decriptare il JWT. Esistono anche altri elementi chiave. Quello che utilizzi dipende dall'algoritmo specificato dal valore di <Algorithms>, come descritto nella sezione successiva.

Impostazione degli elementi chiave per verificare un JWT criptato

I seguenti elementi specificano la chiave utilizzata per verificare un JWT criptato:

L'elemento da utilizzare dipende dall'algoritmo di crittografia della chiave scelto, come mostrato nella tabella seguente:

Algoritmo Elementi chiave
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

Nota:la variabile specificata deve essere risolta in una chiave privata RSA in formato con codifica PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Nota:la variabile specificata deve essere risolta in una chiave privata con curva ellittica in formato con codifica PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

Per saperne di più sui requisiti delle chiavi, consulta Informazioni sugli algoritmi di crittografia della firma.

Riferimento elemento

Il riferimento al criterio descrive gli elementi e gli attributi del criterio Verifica JWT.

Nota: la configurazione varia leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta gli esempi per visualizzare configurazioni per casi d'uso specifici.

Attributi che si applicano all'elemento di primo livello

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

I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.

Attributo Descrizione Predefinito Presenza
nome Il nome interno della policy. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee impone ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

Se vuoi, utilizza l'elemento <displayname></displayname> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError Imposta false per restituire un errore quando un criterio non viene rispettato. Questo è il comportamento previsto per la maggior parte delle norme.

Imposta true per continuare l'esecuzione del flusso anche dopo l'errore di un criterio.

 falso Facoltativo
abilitato Imposta su true per applicare la policy.

Imposta false per "disattivare" la policy. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
asinc Questo attributo è stato ritirato. falso Deprecato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

Predefinito Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

<Algorithm>

<Algorithm>HS256</Algorithm>

Specifica l'algoritmo crittografico utilizzato per verificare il token. Utilizza l'elemento <Algorithm> per verificare un JWT firmato.

Gli algoritmi RS*/PS*/ES* utilizzano una coppia di chiavi pubblica/segreta, mentre gli algoritmi HS* utilizzano un segreto condiviso. Vedi anche Informazioni sugli algoritmi di crittografia della firma.

Puoi specificare più valori separati da virgole. Ad esempio, "HS256, HS512" o "RS256, PS256". Tuttavia, non puoi combinare gli algoritmi HS* con altri o gli algoritmi ES* con altri perché richiedono un tipo di chiave specifico. Puoi combinare gli algoritmi RS* e PS*.

Predefinito N/D
Presenza Obbligatorio
Tipo Stringa di valori separati da virgola
Valori validi HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Utilizza l'elemento <Algorithms> per verificare un JWT criptato. Questo elemento specifica l'algoritmo crittografico per la crittografia delle chiavi che deve essere stato utilizzato durante la creazione del JWT criptato. Specifica anche, facoltativamente, l'algoritmo per la crittografia dei contenuti.

Predefinito N/D
Presenza Obbligatorio durante la verifica di un JWT criptato
Tipo Complesso

Elementi secondari di <Algorithms>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <Algorithms>:

Elemento secondario Obbligatorio? Descrizione
<Key> Obbligatorio Specifica l'algoritmo di crittografia per la chiave.
<Content> Facoltativo Specifica l'algoritmo di crittografia per i contenuti.

La verifica non andrà a buon fine se:

  • L'algoritmo asserito nella proprietà alg nell'intestazione del JWT criptato è diverso dall'algoritmo di crittografia della chiave specificato qui nell'elemento <Key>.
  • Il criterio specifica un elemento <Content> e l'algoritmo asserito nella proprietà enc nell'intestazione del JWT criptato è diverso da quello specificato nell'elemento <Content>.

Ad esempio, per verificare un JWT criptato e controllare che l'algoritmo della chiave sia RSA-OAEP-256 e che l'algoritmo dei contenuti sia A128GCM:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

Al contrario, per verificare un JWT criptato e controllare che l'algoritmo della chiave sia RSA-OAEP-256 e non imporre un vincolo all'algoritmo dei contenuti:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

Algoritmi di crittografia delle chiavi

La seguente tabella elenca gli algoritmi disponibili per la crittografia delle chiavi, nonché il tipo di chiave che devi specificare per verificare un JWT utilizzando l'algoritmo di crittografia delle chiavi.

Valore di <Key> (algoritmo di crittografia della chiave) Elemento chiave richiesto per la verifica
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

Consulta Verificare un JWT criptato per un esempio in cui l'algoritmo di crittografia della chiave è RSA-OAEP-256, quindi utilizzi l'elemento <PrivateKey>.

Algoritmi di crittografia dei contenuti

Il criterio VerifyJWT non richiede di specificare un algoritmo per la crittografia dei contenuti. Se vuoi specificare l'algoritmo utilizzato per la crittografia dei contenuti, fallo con l'elemento secondario <Content> dell'elemento <Algorithms>.

Indipendentemente dall'algoritmo di crittografia della chiave, per la crittografia dei contenuti sono supportati i seguenti algoritmi, tutti simmetrici e basati su AES:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Il criterio verifica che l'attestazione del pubblico nel JWT corrisponda al valore specificato nella configurazione. Se non viene trovata alcuna corrispondenza, la norma genera un errore. Questa rivendicazione identifica i destinatari a cui è destinato il JWT. Si tratta di una delle rivendicazioni registrate menzionate nella RFC7519.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Una variabile di flusso o una stringa che identifica il pubblico.

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

Verifica che il payload JWT contenga le rivendicazioni aggiuntive specificate e che i valori delle rivendicazioni asserite corrispondano.

Un'attestazione aggiuntiva utilizza un nome che non è uno dei nomi delle attestazioni JWT standard registrate. Il valore di un'attestazione aggiuntiva può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore. Il valore di un'attestazione di uno di questi tipi può essere specificato in modo esplicito nella configurazione del criterio o indirettamente tramite un riferimento a una variabile di flusso.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa, numero, valore booleano o mappa
Array Imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false
Valori validi Qualsiasi valore che vuoi utilizzare per un'ulteriore rivendicazione.

L'elemento <Claim> prevede i seguenti attributi:

  • name: (obbligatorio) il nome dell'attestazione.
  • ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come rivendicazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è quello predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non viene risolta.
  • type: (facoltativo) uno dei seguenti valori: stringa (impostazione predefinita), numero, booleano o mappa
  • array: (facoltativo) imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Quando includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico quando configuri la policy. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle attestazioni 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 }
  }
}

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

Verifica che l'intestazione JWT contenga le coppie chiave-valore aggiuntive specificate e che i valori delle rivendicazioni asserite corrispondano.

Un'attestazione aggiuntiva utilizza un nome che non è uno dei nomi standard e registrati delle attestazioni JWT. Il valore di un'ulteriore rivendicazione può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore. Il valore di un'attestazione di uno di questi tipi può essere specificato in modo esplicito nella configurazione del criterio o indirettamente tramite un riferimento a una variabile di flusso.

Predefinito N/D
Presenza Facoltativo
Tipo

Stringa (impostazione predefinita), numero, valore booleano o mappa.

Se non viene specificato alcun tipo, il tipo predefinito è Stringa.
Array Imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false
Valori validi Qualsiasi valore che vuoi utilizzare per un'ulteriore rivendicazione.

L'elemento <Claim> prevede i seguenti attributi:

  • name: (obbligatorio) il nome dell'attestazione.
  • ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come rivendicazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è quello predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non viene risolta.
  • type: (facoltativo) uno dei seguenti valori: stringa (impostazione predefinita), numero, booleano o mappa
  • array: (facoltativo) imposta su true per indicare se il valore è un array di tipi. Valore predefinito: false.

<CustomClaims>

Nota:al momento, viene inserito un elemento CustomClaims quando aggiungi un nuovo criterio GenerateJWT tramite la UI. Questo elemento non è funzionale e viene ignorato. L'elemento corretto da utilizzare è <AdditionalClaims>. L'interfaccia utente verrà aggiornata in un secondo momento per inserire gli elementi corretti.

<Id>

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

Verifica che il JWT abbia l'attestazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genererà un jti contenente un UUID casuale. L'attestazione JWT ID (jti) è un identificatore univoco per il JWT. Per saperne di più su jti, consulta RFC7519.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa o riferimento.
Valori validi Una stringa o il nome di una variabile di flusso contenente l'ID.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Imposta il valore su false se vuoi che il criterio generi un errore quando un'intestazione elencata nell'intestazione crit del JWT non è elencata nell'elemento <KnownHeaders>. Imposta su true per fare in modo che il criterio VerifyJWT ignori l'intestazione crit.

Un motivo per impostare questo elemento su true è se ti trovi in un ambiente di test e non sei ancora pronto a gestire un errore in un'intestazione mancante.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta il valore su false (impostazione predefinita) se vuoi che il criterio generi un errore quando un JWT contiene un attributo iat (Emesso alle) che specifica un orario futuro. Se impostato su true, il criterio ignora iat durante la verifica.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta su false se vuoi che il criterio generi un errore quando qualsiasi variabile a cui viene fatto riferimento specificata nel criterio non è risolvibile. Imposta su true per considerare qualsiasi variabile non risolvibile come una stringa vuota (null).

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

I criteri verificano che l'emittente nel JWT (l'attestazione iss) corrisponda alla stringa specificata nell'elemento di configurazione. L'attestazione iss è una delle attestazioni registrate menzionate nella RFC 7519 di IETF.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa o riferimento
Valori validi Qualsiasi

<KnownHeaders>

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

or:

<KnownHeaders ref='variable_containing_headers'/>

La norma GenerateJWT utilizza l'elemento <CriticalHeaders> per compilare l'intestazione crit in un JWT. Ad esempio:

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

Il criterio VerifyJWT esamina l'intestazione crit nel JWT, se esiste, e per ogni intestazione elencata verifica che anche l'elemento <KnownHeaders> elenchi l'intestazione. L'elemento <KnownHeaders> può contenere un superset degli elementi elencati in crit. È necessario solo che tutte le intestazioni elencate in crit siano elencate nell'elemento <KnownHeaders>. Qualsiasi intestazione trovata dal criterio in crit che non è elencata anche in <KnownHeaders> causa l'errore del criterio VerifyJWT.

Se vuoi, puoi configurare la policy VerifyJWT in modo che ignori l'intestazione crit impostando l'elemento <IgnoreCriticalHeaders> su true.

Predefinito N/D
Presenza Facoltativo
Tipo Array di stringhe separate da virgole
Valori validi Un array o il nome di una variabile contenente l'array.

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

Configura il criterio VerifyJWT per verificare che la durata di un token non superi una soglia specificata. Puoi specificare la soglia utilizzando un numero seguito da un carattere che indica il numero di secondi, minuti, ore, giorni o settimane. Sono validi i seguenti caratteri:

  • s - secondi
  • m - minuti
  • h - ore
  • d - giorni
  • w - settimane

Ad esempio, puoi specificare uno dei seguenti valori: 120s, 10m, 1h, 7d, 3w.

Il criterio calcola la durata effettiva del token sottraendo il valore not-before (nbf) dal valore di scadenza (exp). Se manca exp o nbf, la policy genera un errore. Se la durata del token supera l'intervallo di tempo specificato, il criterio genera un errore.

Puoi impostare l'attributo facoltativo useIssueTime su true per utilizzare il valore iat anziché il valore nbf durante il calcolo della durata del token.

L'utilizzo dell'elemento MaxLifespan è facoltativo. Se utilizzi questo elemento, puoi farlo una sola volta.

<PrivateKey>

Utilizza questo elemento per specificare la chiave privata che può essere utilizzata per verificare un JWT criptato con un algoritmo asimmetrico. Di seguito è riportata una descrizione dei possibili elementi secondari.

<Password>

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

Un elemento secondario dell'elemento <PrivateKey>. Specifica la password che la policy deve utilizzare per decriptare la chiave privata, se necessario, durante la verifica di un JWT criptato. Utilizza l'attributo ref per passare la password in una variabile di flusso.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Un riferimento a una variabile di flusso.

Nota:devi specificare una variabile di flusso. Apigee rifiuterà come non valida una configurazione dei criteri in cui la password è specificata in testo normale. La variabile di flusso deve avere il prefisso "private". Ad esempio, private.mypassword

<Value>

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

Elemento secondario dell'elemento <PrivateKey>. Specifica una chiave privata con codifica PEM che la policy utilizzerà per verificare un JWT criptato. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Predefinito N/D
Presenza Obbligatorio per verificare un JWT criptato utilizzando un algoritmo di crittografia con chiave asimmetrica.
Tipo Stringa
Valori validi Una variabile di flusso contenente una stringa che rappresenta un valore della chiave privata RSA con codifica PEM.

Nota: la variabile di flusso deve avere il prefisso "private". Ad esempio, private.mykey

<PublicKey>

Specifica l'origine della chiave pubblica utilizzata per verificare un JWT firmato con un algoritmo asimmetrico. Gli algoritmi supportati includono RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512. Di seguito è riportata una descrizione dei possibili elementi secondari.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Un elemento secondario dell'elemento <PublicKey>. Specifica il certificato firmato utilizzato come origine della chiave pubblica. Utilizza l'attributo ref per passare il certificato firmato in una variabile di flusso o specifica direttamente il certificato con codifica PEM. Assicurati di allineare i dati del certificato a sinistra come mostrato nell'esempio di riferimento.

Predefinito N/D
Presenza Facoltativo. Per verificare un JWT firmato con un algoritmo asimmetrico, devi utilizzare l'elemento <Certificate>, <JWKS> o <Value> per fornire la chiave pubblica.
Tipo Stringa
Valori validi Una variabile di flusso o una stringa.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

Un elemento secondario dell'elemento <PublicKey>. Specifica un JWKS come origine delle chiavi pubbliche. Si tratta di un elenco di chiavi nel formato descritto in IETF RFC 7517 - JSON Web Key (JWK).

Se il JWT in entrata contiene un ID chiave presente nel JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWT. Per informazioni dettagliate su questa funzionalità, consulta Utilizzo di un set di chiavi web JSON (JWKS) per verificare un JWT.

Se recuperi il valore da un URL pubblico, Apigee memorizza nella cache JWKS per un periodo di 300 secondi. Quando la cache scade, Apigee recupera nuovamente il JWKS.

Predefinito N/D
Presenza Facoltativo. Per verificare un JWT firmato con un algoritmo asimmetrico, devi utilizzare l'elemento <Certificate>, <JWKS> o <Value> per fornire la chiave pubblica.
Tipo Stringa
Valori validi

Puoi specificare il JWKS in uno dei quattro modi seguenti:

  • Letteralmente, come valore di testo:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • Indirettamente, con l'attributo ref, specificando una variabile di flusso:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    La variabile a cui viene fatto riferimento deve contenere una stringa che rappresenta un JWKS.

  • Indirettamente tramite un URI statico, con l'attributo uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • Indirettamente tramite un URI determinato dinamicamente, con l'attributo uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

Un elemento secondario dell'elemento <PublicKey>. Specifica la chiave pubblica da utilizzare per verificare la firma su un JWT firmato. Utilizza l'attributo ref per passare la chiave in una variabile di flusso o specifica direttamente la chiave con codifica PEM. Assicurati di allineare la chiave pubblica a sinistra come mostrato nell'esempio di riferimento.

Predefinito N/D
Presenza Facoltativo. Per verificare un JWT firmato con un algoritmo asimmetrico, devi utilizzare l'elemento <Certificate>, <JWKS> o <Value> per fornire la chiave pubblica.
Tipo Stringa
Valori validi Una variabile di flusso o una stringa.

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

L'elemento <RequiredClaims> è facoltativo. Specifica un elenco separato da virgole di nomi di rivendicazioni che devono essere presenti nel payload JWT durante la verifica di un JWT. L'elemento garantisce che il JWT presentato contenga le rivendicazioni richieste, ma non ne convalida i contenuti. Se una delle rivendicazioni elencate non è presente, la norma VerifyJWT genererà un errore in fase di runtime.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Un elenco di nomi di rivendicazioni separati da virgole.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>

L'elemento SecretKey è facoltativo. Specifica la chiave segreta da utilizzare per verificare un JWT firmato che utilizza un algoritmo simmetrico (HS*) o per verificare un JWT criptato che utilizza un algoritmo simmetrico (AES) per la crittografia della chiave.

Figli di <SecretKey>

La tabella seguente fornisce una descrizione degli elementi secondari e degli attributi di <SecretKey>:

Figlio Presenza Descrizione
codifica (attributo) Facoltativo

Specifica come viene codificata la chiave nella variabile a cui viene fatto riferimento. Per impostazione predefinita, quando non è presente l'attributo encoding, la codifica della chiave viene trattata come UTF-8. I valori validi per l'attributo sono: esadecimale, base16, base64 o base64url. I valori di codifica hex e base16 sono sinonimi.

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

Nell'esempio precedente, poiché la codifica è hex, se i contenuti della variabile private.secretkey sono 494c6f766541504973, la chiave verrà decodificata come un insieme di 9 byte, che in esadecimale saranno 49 4c 6f 76 65 41 50 49 73.

Valore (elemento) Obbligatorio

Una chiave segreta codificata. Specifica la chiave segreta che verrà utilizzata per verificare il payload. Utilizza l'attributo ref per fornire la chiave indirettamente tramite una variabile, ad esempio private.secret-key .

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee applica una lunghezza 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 con una potenza inferiore causa un errore di runtime.

<Source>

<Source>jwt-variable</Source>

Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il JWT da verificare.

Con questo elemento, puoi configurare il criterio per recuperare il JWT da una variabile di parametro di query o modulo o da qualsiasi altra variabile. Quando questo elemento è presente, la norma non rimuove alcun prefisso Bearer eventualmente presente. Se la variabile non esiste o se il criterio non trova un JWT nella variabile specificata, il criterio restituisce un errore.

Per impostazione predefinita, quando non è presente alcun elemento <Source>, il criterio recupera il JWT leggendo la variabile request.header.authorization e rimuovendo il prefisso Bearer. Se passi il JWT nell'intestazione Authorization come token bearer (con il prefisso Bearer), non specificare l'elemento <Source> nella configurazione della policy. Ad esempio, non utilizzeresti alcun elemento <Source> nella configurazione della policy se trasmetti il JWT nell'intestazione Authorization nel seguente modo:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Predefinito request.header.authorization (Per informazioni importanti sul valore predefinito, consulta la nota riportata sopra).
Presenza Facoltativo
Tipo Stringa
Valori validi Un nome di variabile di flusso Apigee.

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

I criteri verificano che il soggetto nel JWT (l'attestazione sub) corrisponda alla stringa specificata nella configurazione dei criteri. L'attestazione sub è una delle attestazioni registrate descritte nella RFC7519.

Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Qualsiasi valore che identifichi in modo univoco un soggetto.

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

Il "periodo di tolleranza" per gli orari, per tenere conto del disallineamento dei segnali di clock tra l'emittente e il verificatore di un JWT. Ciò si applicherà sia alla scadenza (l'attestazione exp) sia al not-before-time (l'attestazione nbf). Ad esempio, se la tolleranza temporale è configurata su 30s, un JWT scaduto verrà considerato ancora valido per 30 secondi dopo la scadenza dichiarata. Anche il valore not-before-time verrà valutato in modo simile.

Predefinito 0 secondi (nessun periodo di tolleranza)
Presenza Facoltativo
Tipo Stringa
Valori validi Un'espressione di intervallo di tempo o un riferimento a una variabile di flusso contenente un'espressione. Gli intervalli di tempo possono essere specificati da un numero intero positivo seguito da un carattere che indica un'unità di tempo, come segue:
  • s = secondi
  • m = minuti
  • h = ore
  • d = giorni

<Type>

<Type>type-string-here</Type>

Descrive se il criterio verifica un JWT firmato o un JWT criptato. L'elemento <Type> è facoltativo. Puoi utilizzarlo per informare i lettori della configurazione se il criterio genera un JWT firmato o criptato.

  • Se l'elemento <Type> è presente:
    • Se il valore di <Type> è Signed, il criterio verifica un JWT firmato e l'elemento <Algorithm> deve essere presente.
    • Se il valore di <Type> è Encrypted, il criterio verifica un JWT criptato e l'elemento <Algorithms> deve essere presente.
  • Se l'elemento <Type> è assente:
    • Se è presente l'elemento <Algorithm>, il criterio presuppone che <Type> sia Signed.
    • Se è presente l'elemento <Algorithms>, il criterio presuppone che <Type> sia Encrypted.
  • Se non è presente né <Algorithm> né <Algorithms>, la configurazione non è valida.
Predefinito N/D
Presenza Facoltativo
Tipo Stringa
Valori validi Signed o Encrypted

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWT, this variable is not set.

Messaggi di errore

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

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration 401 Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidIterationCount 401 The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS in the <PublicKey> element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
steps.jwt.InvalidSaltLength 401 The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "InvalidToken"
JWT.failed Tutti i criteri JWT impostano la stessa variabile in caso di errore. JWT.failed = true

Esempio di risposta di errore

Codici di errore dei criteri JWT

Per la gestione degli errori, la best practice è intercettare la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>