Criterio VerifyJWT

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Verifica un JWT firmato o decripta e verifica un JWT criptato ricevuto da client o altri sistemi. Questa norma inoltre estrae 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 instradamento. Per un'introduzione dettagliata, consulta la Panoramica dei criteri JWS e JWT.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.

Quando viene eseguito questo criterio, 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 decripta il JWT utilizzando la chiave di decriptazione. In entrambi i casi, Apigee verifica successivamente che il JWT sia valido in base alle date di scadenza e di validità precedente, se presenti. Facoltativamente, il criterio può anche verificare i valori di rivendicazioni specifiche nel JWT, ad esempio l'oggetto, l'emittente, il pubblico o il valore di rivendicazioni aggiuntive.

Se il JWT è verificato e valido, tutte le rivendicazioni al suo interno vengono ricavate in variabili di contesto per essere utilizzate da norme o condizioni successive 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, l'elaborazione si interrompe e nella risposta viene restituito un errore.

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

Come

Il fatto che il criterio verifichi un JWT firmato o criptato dipende dall'elemento utilizzato per specificare l'algoritmo che verifica il JWT:

Video

Guarda un breve video per scoprire come verificare la firma su un JWT.

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 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 di 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 in base alle norme.

La configurazione del criterio include le informazioni di cui Apigee ha bisogno per decodificare e valutare il JWT, come dove trovare il JWT (in una variabile di flusso specificata nell'elemento Origine), l'algoritmo di firma richiesto, dove trovare la chiave segreta (memorizzata in una variabile di flusso Apigee, che potrebbe essere stata recuperata dalla KVM di Apigee, ad esempio) e un insieme di claim obbligatori e 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 l'output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.

Algoritmo RS256

Questo criterio 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 di modulo denominato jwt. La chiave pubblica è contenuta in una variabile denominata public.publickey. Guarda il video qui sopra per un esempio completo, incluso come presentare una richiesta in base alle norme.

Consulta la sezione di riferimento sugli elementi per informazioni dettagliate sui requisiti e sulle opzioni di ciascun elemento di queste norme di esempio.

<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é il claim "sub" incluso nel JWT non corrisponde al valore richiesto dell'elemento "Subject" come specificato nella configurazione del criterio.

Il criterio scrive l'output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.

I sample 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. La scelta 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 da utilizzare dipende dall'algoritmo scelto, come mostrato nella seguente tabella:

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

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

L'esempio seguente 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 riportato sopra 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. La scelta 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 seguente tabella:

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

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

Nota:la variabile specificata deve risolvere 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 delle firme.

Riferimento elemento

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

Nota:la configurazione varia leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta la sezione Samples per esempi che mostrano le 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 Presence
nome Il nome interno del criterio. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di Apigee applica 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 su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo il fallimento di un criterio.

 falso Facoltativo
abilitato Imposta su true per applicare il criterio.

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

 true Facoltativo
asinc Questo attributo è stato ritirato. falso Ritirato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare insieme 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.
Presence 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 una chiave segreta condivisa. Vedi anche Informazioni sugli algoritmi di crittografia delle firme.

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

Predefinito N/D
Presence Obbligatorio
Tipo Stringa di valori separati da virgole
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 della chiave che deve essere stato utilizzato durante la creazione del JWT criptato. Se vuoi, specifica anche l'algoritmo per la crittografia dei contenuti.

Predefinito N/D
Presence Obbligatorio per 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 dichiarato 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 dichiarato 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 applicare una limitazione all'algoritmo dei contenuti:

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

Algoritmi di crittografia delle chiavi

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

Valore di <Key> (algoritmo di crittografia della chiave) Elemento chiave necessario 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, utilizza l'elemento secondario <Content> dell'elemento <Algorithms>.

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

  • 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'attributo audience nel JWT corrisponda al valore specificato nella configurazione. Se non viene trovata alcuna corrispondenza, il criterio genera un errore. Questo claim identifica i destinatari a cui è destinato il JWT. Si tratta di uno dei diritti registrati menzionati nel RFC7519.

Predefinito N/D
Presence Facoltativo
Tipo Stringa
Valori validi Una stringa o una variabile di flusso che identifica il segmento di 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 i claim aggiuntivi specificati e che i valori dei claim dichiarati corrispondano.

Un'affermazione aggiuntiva utilizza un nome che non è uno dei nomi delle affermazioni JWT standard registrati. Il valore di un'affermazione 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'affermazione di uno di questi tipi può essere specificato esplicitamente nella configurazione del criterio o indirettamente tramite un riferimento a una variabile di flusso.

Predefinito N/D
Presence Facoltativo
Tipo Stringa, numero, booleano o mappa
Array Impostato su true per indicare se il valore è un array di tipi. Valore predefinito: false
Valori validi Qualsiasi valore da utilizzare per un'affermazione aggiuntiva.

L'elemento <Claim> prevede i seguenti attributi:

  • name: (obbligatorio) il nome della rivendicazione.
  • ref: (Facoltativo) il nome di una variabile del flusso. Se presente, il criterio utilizzerà il valore di questa variabile come reclamo. Se vengono specificati sia un attributo ref sia un valore esplicito della rivendicazione, il valore esplicito è predefinito e viene utilizzato se la variabile di flusso a cui si fa riferimento non è risolta.
  • type: (facoltativo) Uno dei seguenti: stringa (valore predefinito), numero, booleano o mappa
  • array: (facoltativo) impostato su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Quando includi l'elemento <Claim>, i nomi dei rivendicatori vengono impostati in modo statico durante la configurazione del criterio. In alternativa, puoi passare un oggetto JSON per specificare i nomi dei rivendicatori. Poiché l'oggetto JSON viene passato come variabile, i nomi delle rivendicazioni vengono determinati in fase di esecuzione.

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 nome/valore dei claim aggiuntivi specificati e che i valori dei claim dichiarati corrispondano.

Un'affermazione aggiuntiva utilizza un nome che non è uno dei nomi delle attestazioni JWT standard registrati. Il valore di un'affermazione 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'affermazione di uno di questi tipi può essere specificato esplicitamente nella configurazione del criterio o indirettamente tramite un riferimento a una variabile di flusso.

Predefinito N/D
Presence Facoltativo
Tipo

Stringa (valore predefinito), numero, booleano o mappa.

Se non viene specificato alcun tipo, il valore predefinito è Stringa.
Array Impostato su true per indicare se il valore è un array di tipi. Valore predefinito: false
Valori validi Qualsiasi valore da utilizzare per un'affermazione aggiuntiva.

L'elemento <Claim> prevede i seguenti attributi:

  • name: (obbligatorio) il nome della rivendicazione.
  • ref: (Facoltativo) il nome di una variabile del flusso. Se presente, il criterio utilizzerà il valore di questa variabile come reclamo. Se vengono specificati sia un attributo ref sia un valore esplicito della rivendicazione, il valore esplicito è predefinito e viene utilizzato se la variabile di flusso a cui si fa riferimento non è risolta.
  • type: (facoltativo) Uno dei seguenti: stringa (valore predefinito), numero, booleano o mappa
  • array: (facoltativo) impostato su true per indicare se il valore è un array di tipi. Valore predefinito: false.

<CustomClaims>

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

<Id>

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

Verifica che il JWT contenga la rivendicazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genera un JTI contenente un UUID casuale. L'attributo ID JWT (jti) è un identificatore univoco per il JWT. Per ulteriori informazioni su JTI, consulta la RFC7519.

Predefinito N/D
Presence 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 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 relativo a un'intestazione mancante.

Predefinito falso
Presence Facoltativo
Tipo Booleano
Valori validi true o false

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta su false (valore predefinito) se vuoi che il criterio generi un errore quando un JWT contiene un claim iat (Issued at) che specifica un'ora futura. Imposta su true per fare in modo che il criterio ignori iat durante la verifica.

Predefinito falso
Presence Facoltativo
Tipo Booleano
Valori validi true o false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

Predefinito falso
Presence Facoltativo
Tipo Booleano
Valori validi true o false

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

Il criterio verifica che l'emittente nel JWT (claim iss) corrisponda alla stringa specificata nell'elemento di configurazione. L'affermazione iss è una delle affermazioni registrate menzionate nella RFC 7519 dell'IETF.

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

<KnownHeaders>

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

or:

<KnownHeaders ref='variable_containing_headers'/>

Il criterio GenerateJWT utilizza l'elemento <CriticalHeaders> per compilare l'crit in un JWT. Ad esempio:

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

Il criterio VerifyJWT esamina l'intestazione crit nel JWT, se esistente, e per ogni intestazione elencata controlla che anche l'elemento <KnownHeaders> la indichi. L'elemento <KnownHeaders> può contenere un superinsieme 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 il fallimento del criterio VerifyJWT.

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

Predefinito N/D
Presence 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. I seguenti caratteri sono validi:

  • 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, il criterio 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é nbf per il calcolo della durata del token.

L'utilizzo dell'elemento MaxLifespan è facoltativo. Se utilizzi questo elemento, puoi utilizzarlo 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 il criterio 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
Presence 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 del criterio 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 codificata in PEM che il criterio utilizzerà per verificare un JWT criptato. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

Predefinito N/D
Presence Obbligatorio per verificare un JWT che è stato 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 del 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-----
cert 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.

Predefinito N/D
Presence 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 stringa o una variabile di flusso.

<JWKS>

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

Un elemento secondario dell'elemento <PublicKey>. Specifica un file JWKS come origine di chiavi pubbliche. Si tratta di un elenco di chiavi che segue il 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 Utilizzare un insieme di chiavi web JSON (JWKS) per verificare un JWT.

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

Predefinito N/D
Presence 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 quattro modi:

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

  • In modo indiretto, con l'attributo ref, specificando una variabile di flusso:

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

    La variabile a cui si fa riferimento deve contenere una stringa che rappresenta un JWKS.

  • In modo indiretto tramite un URI statico, con l'attributo uri:

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

  • In modo indiretto 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.

Predefinito N/D
Presence 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 stringa o una variabile di flusso.

<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 claim che devono essere presenti nel payload JWT durante la verifica di un JWT. L'elemento garantisce che il JWT presentato contenga i claim richiesti, ma non convalida i contenuti dei claim. Se uno dei claim elencati non è presente, il criterio VerifyJWT genera un errore in fase di esecuzione.

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

<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
encoding (attributo) Facoltativo

Specifica in che modo la chiave viene codificata nella variabile a cui viene fatto riferimento. Per impostazione predefinita, se non è presente alcun 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 esadecimale 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 sarà 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 robustezza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è 32 byte, per HS384 è 48 byte e per HS512 è 64 byte. L'utilizzo di una chiave con un'intensità inferiore causa un errore di runtime.

<Source>

<Source>jwt-variable</Source>

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

Con questo elemento, puoi configurare il criterio in modo da recuperare il JWT da una variabile del parametro di query o di un modulo o da qualsiasi altra variabile. Se questo elemento è presente, il criterio non eliminerà 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 di accesso (con il prefisso Bearer), non specificare l'elemento <Source> nella configurazione dei criteri. Ad esempio, non utilizzerai alcun elemento <Source> nella configurazione delle norme se passi il JWT nell'intestazione Authorization come segue:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Predefinito request.header.authorization (consulta la nota sopra per informazioni importanti sull'impostazione predefinita).
Presence 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>

Il criterio verifica che il soggetto nel JWT (claim sub) corrisponda alla stringa specificata nella configurazione del criterio. La rivendicazione sub è una delle rivendicazioni registrate descritte nell'RFC7519.

Predefinito N/D
Presence Facoltativo
Tipo Stringa
Valori validi Qualsiasi valore che identifica 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 i tempi, per tenere conto del disavanzo di clock tra l'emittente e il verificatore di un JWT. Questo vale sia per la scadenza (affermazione exp) sia per la data minima (affermazione nbf). Ad esempio, se il tempo di tolleranza è configurato su 30s, un token JWT scaduto verrà considerato ancora valido per 30 secondi dopo la scadenza dichiarata. Il valore not-before-time verrà valutato in modo simile.

Predefinito 0 secondi (nessun periodo di tolleranza)
Presence Facoltativo
Tipo Stringa
Valori validi Un'espressione relativa all'intervallo di tempo o un riferimento a una variabile del 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 è presente l'elemento <Type>:
    • Se il valore di <Type> è Signed, il criterio verifica un JWT firmato e deve essere presente l'elemento <Algorithm>.
    • Se il valore di <Type> è Encrypted, il criterio verifica un JWT criptato e deve essere presente l'elemento <Algorithms>.
  • Se l'elemento <Type> è assente:
    • Se è presente l'elemento <Algorithm>, il criterio presuppone che <Type> sia Signed.
    • Se è presente l'elemento <Algorithms>, il criterio assume <Type> sia Encrypted.
  • Se non sono presenti né <Algorithm> né <Algorithms>, la configurazione non è valida.
Predefinito N/D
Presence Facoltativo
Tipo Stringa
Valori validi Signed o Encrypted

Variabili di flusso

Se l'operazione riesce, i criteri Verify JWT (Verifica JWT) e Decode JWT (Decodifica JWT) sono stati impostati. variabili di contesto in base a questo pattern:

jwt.{policy_name}.{variable_name}

Ad esempio, se il nome del criterio è jwt-parse-token, il criterio memorizza il soggetto specificato nel JWT nella variabile di contesto denominata jwt.jwt-parse-token.decoded.claim.sub. Per la compatibilità con le versioni precedenti, sarà disponibile anche in jwt.jwt-parse-token.claim.subject.

Nome variabile Descrizione
claim.audience L'attributo del segmento di pubblico JWT. Questo valore può essere una stringa o un array di stringhe.
claim.expiry La data e l'ora di scadenza, espresse in millisecondi dall'epoca.
claim.issuedat La data di emissione del token, espressa in millisecondi dall'epoca.
claim.issuer La rivendicazione dell'emittente JWT.
claim.notbefore Se il JWT include un claim nbf, questa variabile conterrà il valore, expressed in milliseconds since epoch.
claim.subject L'affermazione del soggetto JWT.
claim.name Il valore dell'attestazione denominata (standard o aggiuntiva) nel payload. Uno di questi verrà impostato per ogni rivendicazione nel payload.
decoded.claim.name Il valore decodificabile in JSON dell'affermazione denominata (standard o aggiuntiva) nel payload. È impostata una variabile per ogni richiesta nel payload. Ad esempio, puoi utilizzare decoded.claim.iat per recupera il valore emesso al momento del JWT, espresso in secondi dall'epoca. Mentre puoi anche usare le variabili di flusso claim.name, queste sono variabile consigliata da utilizzare per accedere a una rivendicazione.
decoded.header.name Il valore analizzabile in JSON di un'intestazione nel payload. È impostata una variabile per ogni intestazione nel payload. Sebbene tu possa utilizzare anche le variabili di flusso header.name, questa è la variabile consigliata per accedere a un'intestazione.
expiry_formatted Data e ora di scadenza, formattate come stringa leggibile. Esempio: 2017-09-28T21:30:45.000+0000
header.algorithm L'algoritmo di firma utilizzato nel JWT. Ad esempio, RS256, HS384 e così via. Per saperne di più, consulta Parametro intestazione(algoritmo).
header.kid L'ID chiave, se aggiunto al momento della generazione del JWT. Consulta anche la sezione "Utilizzo di un set di chiavi web JSON (JWKS)" presso JWT panoramica dei criteri per verificare un JWT. Per saperne di più, consulta la sezione Parametro dell'intestazione (ID chiave).
header.type Verrà impostato su JWT.
header.name Il valore dell'intestazione denominata (standard o aggiuntiva). Una di queste sarà impostata su ogni intestazione aggiuntiva nella parte di intestazione del JWT.
header-json L'intestazione in formato JSON.
is_expired true o false
payload-claim-names Un array di attestazioni supportate dal JWT.
payload-json
Il payload in formato JSON.
seconds_remaining Il numero di secondi prima della scadenza del token. Se il token è scaduto, questo numero sarà negativo.
time_remaining_formatted Il tempo rimanente prima della scadenza del token, formattato come stringa leggibile. Esempio: 00:59:59.926
valid Nel caso di VerifyJWT, questa variabile sarà vera quando la firma è verificata e l'ora corrente è precedente alla scadenza del token e successiva al valore notBefore del token, se sono presenti. In caso contrario, false.

Nel caso di DecodeJWT, questa variabile non è impostata.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Si verifica quando
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Si verifica quando il criterio di verifica ha più algoritmi.
steps.jwt.AlgorithmMismatch 401 L'algoritmo specificato nel criterio Generate non corrisponde a quello previsto nel criterio Verify. Gli algoritmi specificati devono corrispondere.
steps.jwt.FailedToDecode 401 Il criterio non è stato in grado di decodificare il JWT. Il JWT potrebbe essere danneggiato.
steps.jwt.GenerationFailed 401 Il criterio non è stato in grado di generare il JWT.
steps.jwt.InsufficientKeyLength 401 Per una chiave inferiore a 32 byte per l'algoritmo HS256, inferiore a 48 byte per l'algoritmo HS386 e inferiore a 64 byte per l'algoritmo HS512.
steps.jwt.InvalidClaim 401 Per una richiesta mancante o una mancata corrispondenza della richiesta oppure per un'intestazione mancante o una mancata corrispondenza dell'intestazione.
steps.jwt.InvalidConfiguration 401 Sono presenti entrambi gli elementi <Algorithm> e <Algorithms>.
steps.jwt.InvalidCurve 401 La curva specificata dalla chiave non è valida per l'algoritmo di curva ellittica.
steps.jwt.InvalidIterationCount 401 Il conteggio delle iterazioni utilizzato nel JWT criptato non è uguale al conteggio delle iterazioni specificato nella configurazione del criterio VerifyJWT. Questo vale solo per i JWT che utilizzano <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 JSON non valido trovato nell'intestazione o nel payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS nell'elemento <PublicKey> non è valido. Il motivo potrebbe essere che l'endpoint URI JWKS non è raggiungibile dall'istanza Apigee. Testa la connettività all'endpoint creando un proxy passthrough e utilizzando l'endpoint JWKS come target.
steps.jwt.InvalidSaltLength 401 La lunghezza del sale utilizzata nel JWT criptato non è uguale alla lunghezza del sale specificata nella configurazione del criterio VerifyJWT. Questo vale solo per i JWT che utilizzano <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 La chiave specificata non soddisfa i requisiti.
steps.jwt.InvalidPrivateKey 401 La chiave specificata non soddisfa i requisiti.
steps.jwt.InvalidPublicKey 401 La chiave specificata non soddisfa i requisiti.
steps.jwt.InvalidSecretKey 401 La chiave specificata non soddisfa i requisiti.
steps.jwt.InvalidToken 401 Questo errore si verifica quando la verifica della firma JWT non va a buon fine.
steps.jwt.JwtAudienceMismatch 401 L'affermazione sul pubblico non è riuscita durante la verifica del token.
steps.jwt.JwtIssuerMismatch 401 L'affermazione dell'emittente non è riuscita durante la verifica del token.
steps.jwt.JwtSubjectMismatch 401 L'affermazione del soggetto non è riuscita durante la verifica del token.
steps.jwt.KeyIdMissing 401 Il criterio Verify utilizza un JWKS come origine per le chiavi pubbliche, ma il JWT firmato non include una proprietà kid nell'intestazione.
steps.jwt.KeyParsingFailed 401 Non è stato possibile analizzare la chiave pubblica dalle informazioni sulla chiave fornite.
steps.jwt.NoAlgorithmFoundInHeader 401 Si verifica quando il JWT non contiene un'intestazione dell'algoritmo.
steps.jwt.NoMatchingPublicKey 401 Il criterio Verify utilizza un file JWKS come origine per le chiavi pubbliche, ma il valore kid nel JWT firmato non è elencato nel file JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, per una chiave inferiore alle dimensioni minime per gli algoritmi HS384 o HS512
steps.jwt.TokenExpired 401 Il criterio tenta di verificare un token scaduto.
steps.jwt.TokenNotYetValid 401 Il token non è ancora valido.
steps.jwt.UnhandledCriticalHeader 401 Un'intestazione trovata dal criterio Verifica JWT nell'intestazione crit non è elencata in KnownHeaders.
steps.jwt.UnknownException 401 Si è verificata un'eccezione sconosciuta.
steps.jwt.WrongKeyType 401 Tipo di chiave specificato errato. Ad esempio, se specifichi una chiave RSA per un algoritmo Elliptic Curve o una chiave a curva per un algoritmo RSA.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore Causa Correggi
InvalidNameForAdditionalClaim Il deployment non andrà a buon fine se il claim utilizzato nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> è uno dei seguenti nomi registrati: kid, iss, sub, aud, iat, exp, nbf o jti.
InvalidTypeForAdditionalClaim Se il claim utilizzato nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> non è di tipo string, number, boolean o map, il deployment non andrà a buon fine.
MissingNameForAdditionalClaim Se il nome della rivendicazione non è specificato nell'elemento secondario <Claim> dell'elemento <AdditionalClaims>, il deployment non andrà a buon fine.
InvalidNameForAdditionalHeader Questo errore si verifica quando il nome della rivendicazione utilizzato nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> è alg o typ.
InvalidTypeForAdditionalHeader Se il tipo di rivendicazione utilizzato nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> non è di tipo string, number, boolean o map, il deployment non andrà a buon fine.
InvalidValueOfArrayAttribute Questo errore si verifica quando il valore dell'attributo array nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> non è impostato su true o false.
InvalidValueForElement Se il valore specificato nell'elemento <Algorithm> non è supportato, il deployment non andrà a buon fine.
MissingConfigurationElement Questo errore si verifica se l'elemento <PrivateKey> non viene utilizzato con gli algoritmi della famiglia RSA o se l'elemento <SecretKey> non viene utilizzato con gli algoritmi della famiglia HS.
InvalidKeyConfiguration Se l'elemento secondario <Value> non è definito negli elementi <PrivateKey> o <SecretKey>, il deployment non andrà a buon fine.
EmptyElementForKeyConfiguration Se l'attributo ref dell'elemento secondario <Value> degli elementi <PrivateKey> o <SecretKey> è vuoto o non specificato, il deployment non andrà a buon fine.
InvalidConfigurationForVerify Questo errore si verifica se l'elemento <Id> è definito all'interno dell'elemento <SecretKey>.
InvalidEmptyElement Questo errore si verifica se l'elemento <Source> del criterio Verifica JWT è vuoto. Se presente, deve essere definito con un nome di variabile del flusso Apigee.
InvalidPublicKeyValue Se il valore utilizzato nell'elemento secondario <JWKS> dell'elemento <PublicKey> non utilizza un formato valido come specificato in RFC 7517, il deployment non andrà a buon fine.
InvalidConfigurationForActionAndAlgorithm Se l'elemento <PrivateKey> viene utilizzato con gli algoritmi della famiglia HS o l'elemento <PrivateKey> viene utilizzato con gli algoritmi della famiglia RSA, il deployment non andrà a buon fine.<SecretKey>

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere 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 di 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>