Verifica del criterio JWT

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Verifica la firma su un JWT ricevuto da client o altri sistemi. Questo criterio estrae anche le rivendicazioni in variabili di contesto, in modo che criteri o condizioni successivi possano esaminare tali valori per prendere decisioni in merito all'autorizzazione o al routing. Per un'introduzione dettagliata, consulta la panoramica sui criteri di JWS e JWT.

Quando viene eseguito questo criterio, Apigee verifica la firma di un JWT e verifica che quest'ultimo sia valido in base alla scadenza e non prima, se presenti. Facoltativamente, il criterio può anche verificare i valori di rivendicazioni specifiche sul JWT, ad esempio l'oggetto, l'emittente, il pubblico o il valore di ulteriori rivendicazioni.

Se il JWT viene verificato e valido, tutte le rivendicazioni contenute al suo interno vengono estratte in variabili di contesto che verranno utilizzate da criteri o condizioni successivi e la richiesta potrà procedere. Se non è possibile verificare la firma JWT o se la JWT non è valida a causa di uno dei timestamp, l'intera elaborazione si interrompe e viene restituito un errore nella risposta.

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

Video

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

Campioni

Verifica un JWT firmato con l'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 di proxy utilizzando un parametro del modulo denominato jwt. La chiave è contenuta in una variabile denominata private.secretkey. Guarda il video sopra per un esempio completo, incluso come inviare una richiesta alle norme.

La configurazione del criterio include le informazioni di cui Apigee deve 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 stato recuperato dalla KVM Apigee, ad esempio), e un set di richieste obbligatorie 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>
        <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 in variabili di contesto in modo che criteri o condizioni successivi nel proxy API possano esaminare tali valori. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da questo criterio.

Verifica un JWT firmato con l'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 di proxy utilizzando un parametro di modulo denominato jwt. La chiave pubblica è contenuta in una variabile denominata public.publickey. Guarda il video sopra per un esempio completo, incluso come inviare una richiesta alle norme.

Consulta la sezione Riferimento elemento per i dettagli sui requisiti e sulle opzioni per ogni elemento in questo criterio 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 riportata sopra, 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."
}

... saranno considerate valide 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é la "sub" dichiarazione inclusa in JWT non corrisponde al valore richiesto dell'elemento "Subject" come specificato nella configurazione del criterio.

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

Impostare gli elementi chiave

Gli elementi che utilizzi per specificare la chiave utilizzata per verificare il JWT dipendono dall'algoritmo scelto, come mostrato nella seguente tabella:

Algoritmo Elementi chiave
H* 

<SecretKey>
  <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 ulteriori informazioni sui requisiti chiave, vedi Informazioni sugli algoritmi di crittografia della firma.

Riferimento elemento

Nel riferimento alle norme vengono descritti gli elementi e gli attributi del criterio Verifica JWT.

Nota: la configurazione sarà leggermente diversa a seconda dell'algoritmo di crittografia utilizzato. Fai riferimento agli esempi per esempi che mostrano configurazioni per casi d'uso specifici.

Attributi applicabili 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
name 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 restrizioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

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

 N/D Obbligatorie
continueOnError Imposta su false per restituire un errore quando un criterio ha esito negativo. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo che un criterio ha esito negativo.

 falso Facoltativo
attiva 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 è obsoleto. falso Deprecato

<NomeDisplay>

<DisplayName>Policy Display Name</DisplayName>

Utilizzalo in aggiunta all'attributo del nome per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un altro nome in linguaggio naturale.

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

Algoritmo >

<Algorithm>HS256</Algorithm>

Specifica l'algoritmo di crittografia per firmare il token. Gli algoritmi RS*/PS*/ES* utilizzano una coppia di chiavi pubblica/segreta, mentre gli algoritmi HS* utilizzano un secret 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 Obbligatorie
Tipo Stringa di valori separati da virgole
Valori validi HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

<Audience>

<Audience>audience-here</Audience>

or:

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

Il criterio verifica che la dichiarazione del pubblico nel JWT corrisponda al valore specificato nella configurazione. Se non viene trovata una corrispondenza, il criterio genera un errore. Questa rivendicazione identifica i destinatari a cui è destinato il JWT. Questa è una delle dichiarazioni registrate menzionate nel documento 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'/>

Convalida che il payload JWT contenga le rivendicazioni aggiuntive specificate e che i valori delle attestazioni corrispondano.

Una rivendicazione aggiuntiva utilizza un nome che non fa parte dei nomi di rivendicazione JWT standard registrati. Il valore di una rivendicazione 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 una rivendicazione di uno di questi tipi può essere specificato esplicitamente nella configurazione del criterio oppure indirettamente tramite un riferimento a una variabile di flusso.

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

L'elemento <Claim> utilizza i seguenti attributi:

  • name (obbligatorio): il nome della rivendicazione.
  • ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come dichiarazione. Se sono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso di riferimento non è risolta.
  • type: (facoltativo) una delle seguenti opzioni: stringa (impostazione predefinita), numero, valore 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 durante la configurazione dei criteri. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene trasmesso 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 aggiuntive specificate per la rivendicazione e che i valori delle rivendicazioni rivendicati corrispondano.

Una rivendicazione aggiuntiva utilizza un nome che non fa parte dei nomi di rivendicazione JWT standard registrati. Il valore di una rivendicazione 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 una rivendicazione di uno di questi tipi può essere specificato esplicitamente nella configurazione del criterio oppure indirettamente tramite un riferimento a una variabile di flusso.

Predefinito N/D
Presenza Facoltativo
Tipo

Stringa (predefinita), numero, booleano o mappa.

Il tipo predefinito è Stringa se non viene specificato alcun tipo.
Array Imposta true per indicare se il valore è un array di tipi. Valore predefinito: false
Valori validi Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva.

L'elemento <Claim> utilizza i seguenti attributi:

  • name (obbligatorio): il nome della rivendicazione.
  • ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come dichiarazione. Se sono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso di riferimento non è risolta.
  • type: (facoltativo) una delle seguenti opzioni: stringa (impostazione predefinita), numero, valore 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 GeneraJWT tramite l'interfaccia utente. Questo elemento non è funzionale e viene ignorato. L'elemento corretto da utilizzare è <AdditionalClaims>. La UI verrà aggiornata per inserire gli elementi corretti in un secondo momento.

<Id&GT; 

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

Verifica che JWT abbia 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. La rivendicazione JWT ID (jti) è un identificatore univoco per JWT. Per ulteriori informazioni su jti, consulta RFC7519.

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

<IgnoraCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Imposta il valore su falso se vuoi che il criterio generi un errore quando un'intestazione elencata nell'intestazione crit di JWT non è elencata nell'elemento <KnownHeaders>. Se il valore è impostato su true, il criterio VerificationJWT ignora 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 provocare un errore in un'intestazione mancante.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<IgnoraProblemadAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta il valore su false (valore predefinito) se vuoi che il criterio generi un errore quando un JWT contiene una rivendicazione iat (emessa alle ore) che specifica un'ora futura. Se il valore è impostato su true, il criterio ignora il criterio iat durante la verifica.

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<IgnoraUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore su falso se vuoi che il criterio restituisca un errore quando una qualsiasi variabile di riferimento specificata nel criterio non è risolvibile. Impostato su true per trattare qualsiasi variabile non risolvibile come una stringa vuota (null).

Predefinito falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

<Issuer>

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

Il criterio verifica che l'emittente nel JWT corrisponda alla stringa specificata nell'elemento di configurazione. Una rivendicazione che identifica l'emittente del JWT. Questo è uno dell'insieme registrato di dichiarazioni riportato in RFC7519.

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

<knownHeaders> 

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

Il criterio Genera JWT utilizza l'elemento <CriticalHeaders> per completare l'intestazione crit in un JWT. Ad esempio:

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

Il criterio VerificationJWT 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 soprainsieme di elementi elencati in crit. È solo necessario che tutte le intestazioni elencate in crit siano elencate nell'elemento <KnownHeaders>. Qualsiasi intestazione trovata nel criterio crit non elencata anche in <KnownHeaders> causa la mancata riuscita del criterio VerificationJWT.

Facoltativamente, puoi configurare il criterio VerificationJWT per ignorare l'intestazione crit impostando l'elemento <IgnoreCriticalHeaders> su true.

Predefinito N/D
Presenza Facoltativo
Tipo Array di stringhe separato da virgole
Valori validi Può essere un array o il nome di una variabile che contiene l'array.

<MaxLifespan>

  <VerifyJWT name='xxx'>
  ...
  <!-- 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 VerificationJWT 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 precedente alla data (nbf) dal valore della scadenza (exp). Se manca exp o nbf, il criterio genera un errore. Se la durata del token supera il periodo 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 usarlo una sola volta.

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Specifica il certificato firmato utilizzato per verificare la firma su JWT. Utilizza l'attributo ref per passare il certificato firmato in una variabile di flusso o specifica direttamente il certificato con codifica PEM. Utilizza l'algoritmo solo quando il codice è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predefinito N/D
Presenza Per verificare un JWT firmato con un algoritmo RSA, devi utilizzare gli elementi Certificate, JWKS o Value.
Tipo Stringa
Valori validi Una variabile o stringa di flusso.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Specifica un valore nel formato JWKS (RFC 7517) contenente un set di chiavi pubbliche. Utilizza l'algoritmo solo quando è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Se il JWT in entrata porta un ID chiave presente nel set di JWK, il criterio utilizzerà la chiave pubblica corretta per verificare la firma di JWT. Per i dettagli di questa funzionalità, vedi Utilizzo di un JWKS (JSON Web Key Set) per verificare un JWT.

Se recuperi il valore da un URL pubblico, Apigee memorizza i dati nella JWK per un periodo di 300 secondi. Alla scadenza della cache, Apigee recupera nuovamente il JWKS.

Predefinito N/D
Presenza Per verificare un JWT utilizzando un algoritmo RSA, devi utilizzare l'elemento Certificate, JWKS o Value.
Tipo Stringa
Valori validi Una variabile di flusso, un valore stringa o un URL.

<Chiave pubblica/Valore>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Specifica la chiave pubblica o il certificato pubblico utilizzato per verificare la firma sul JWT. Utilizza l'attributo ref per passare la chiave/certificato in una variabile di flusso o specifica la chiave codificata PEM direttamente. Utilizzalo solo quando l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Predefinito N/D
Presenza Per verificare un JWT firmato con un algoritmo RSA, devi utilizzare gli elementi Certificate, JWKS o Value.
Tipo Stringa
Valori validi Una variabile o stringa di flusso.

<SecretKey/Value&GT;

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

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

Predefinito N/D
Presenza Obbligatorio per gli algoritmi HMAC.
Tipo Stringa
Valori validi Una variabile di flusso che fa riferimento a una stringa.

Nota: se una variabile di flusso deve avere il prefisso "privato". Ad esempio: private.mysecret

<Fonte>

<Source>jwt-variable</Source>

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

Predefinito request.header.authorization (vedi la nota sopra per informazioni importanti sul valore predefinito).
Presenza Facoltativo
Tipo Stringa
Valori validi Il nome di una variabile di flusso Apigee.

<Oggetto>

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

Il criterio verifica che l'oggetto nel JWT corrisponda alla stringa specificata nella configurazione del criterio. Questa rivendicazione identifica o fa una dichiarazione in merito all'oggetto del JWT. Questo è uno degli insiemi di dichiarazioni standard menzionati in RFC7519.

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

<TimeAllowance&GT;

<TimeAllowance>120s</TimeAllowance>

Il "periodo di tolleranza" per i tempi. Ad esempio, se l'intervallo di tempo è configurato su 60 secondi, un JWT scaduto verrà considerato come ancora valido per 60 secondi dopo la scadenza della dichiarazione. La valutazione precedente sarà valutata in modo simile. Il valore predefinito è 0 secondi (nessun periodo di tolleranza).

Predefinito 0 secondi (nessun periodo di tolleranza)
Presenza Facoltativo
Tipo Stringa
Valori validi Un valore o un riferimento a una variabile di flusso contenente il valore. Gli intervalli di tempo possono essere specificati come segue:
  • s = secondi
  • m = minuti
  • H = ore
  • g = giorni

Variabili di flusso

Se l'operazione ha esito positivo, i criteri Verifica JWT e Decodifica JWT impostano le 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 archivierà 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'affermazione sul pubblico JWT. Questo valore può essere una stringa o un array di stringhe.
claim.expiry Data e 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'attestazione nbf, questa variabile conterrà il valore, espresso in millisecondi dall'epoca.
claim.subject L'affermazione dell'oggetto JWT.
claim.name Il valore dell'attestazione denominata (standard o aggiuntiva) nel payload. Uno di questi verrà impostato per ogni attestazione nel payload.
decoded.claim.name Il valore analizzabile JSON dell'attestazione denominata (standard o aggiuntiva) nel payload. Viene impostata una variabile per ogni attestazione nel payload. Ad esempio, puoi utilizzare decoded.claim.iat per recuperare il valore inviato al momento del JWT, espresso in secondi dall'epoca. Anche se puoi utilizzare anche le variabili di flusso claim.name, questa è la variabile consigliata da utilizzare per accedere a una rivendicazione.
decoded.header.name Il valore analizzabile JSON di un'intestazione nel payload. Nel payload viene impostata una variabile per ogni intestazione. Sebbene sia possibile utilizzare anche le variabili di flusso header.name, questa è la variabile consigliata da utilizzare per accedere a un'intestazione.
expiry_formatted La data e l'ora di scadenza, formattate come stringa leggibile. Esempio: 2017-09-28T21:30:45.000+0000
header.algorithm L'algoritmo di firma utilizzato sul JWT. Per esempio, RS256, HS384, ecc. Per saperne di più, consulta Parametro intestazione(algoritmo).
header.kid L'ID chiave, se aggiunto al momento della generazione del JWT. Vedi anche "Utilizzo di un set di chiavi web JSON (JWKS)" nella panoramica dei criteri JWT per verificare un set di chiavi JWT. Per saperne di più, consulta Parametro intestazione(ID chiave).
header.type Verrà impostato su JWT.
header.name Il valore dell'intestazione denominata (standard o aggiuntiva). Uno di questi verrà impostato per 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 VerificationJWT, questa variabile sarà vera quando la firma viene verificata e l'ora attuale è precedente alla scadenza del token e dopo il valore notBefore del token, se sono presenti. Altrimenti false.

Nel caso di DecodeJWT, questa variabile non è impostata.

Messaggi di errore

In questa sezione vengono descritti i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Questa informazione è importante per sapere se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta le Informazioni sugli errori dei criteri e la gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Si verifica quando
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Si verifica quando il criterio di verifica contiene 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, a meno di 48 byte per l'algoritmo HS386 e a meno di 64 byte per l'algoritmo HS512.
steps.jwt.InvalidClaim 401 Mancata corrispondenza a livello di rivendicazione o di mancata corrispondenza oppure intestazione o intestazione mancante.
steps.jwt.InvalidCurve 401 La curva specificata dalla chiave non è valida per l'algoritmo della curva ellittica.
steps.jwt.InvalidJsonFormat 401 JSON non valido trovato nell'intestazione o nel payload.
steps.jwt.InvalidToken 401 Questo errore si verifica quando la verifica della firma JWT ha esito negativo.
steps.jwt.JwtAudienceMismatch 401 La rivendicazione del pubblico non è riuscita al momento della verifica del token.
steps.jwt.JwtIssuerMismatch 401 La richiesta dell'emittente non è riuscita durante la verifica del token.
steps.jwt.JwtSubjectMismatch 401 La rivendicazione dell'oggetto non è riuscita durante la verifica del token.
steps.jwt.KeyIdMissing 401 Il criterio Verify utilizza un JWK come origine per le chiavi pubbliche, ma quest'ultimo non include una proprietà kid nell'intestazione.
steps.jwt.KeyParsingFailed 401 Impossibile 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 JWK come origine per le chiavi pubbliche, ma il kid nel JWT firmato non è elencato nel JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, per una chiave di dimensioni inferiori alla dimensione minima 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 Il tipo di chiave specificato è errato. Ad esempio, se specifichi una chiave RSA per un algoritmo Elliptic Curve o una chiave curva per un algoritmo RSA.

Errori di deployment

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

Nome errore Causa Correggi
InvalidNameForAdditionalClaim Il deployment non andrà a buon fine se la rivendicazione utilizzata nell'elemento secondario <Claim> dell'elemento <AdditionalClaims> è uno dei seguenti nomi registrati: kid, iss, sub, aud, iat, exp, nbf o jti.
InvalidTypeForAdditionalClaim Se la dichiarazione utilizzata 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 viene restituito quando il nome della dichiarazione utilizzata 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 riuscirà.
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 è un valore supportato, il deployment non riuscirà.
MissingConfigurationElement Questo errore si verifica se l'elemento <PrivateKey> non viene utilizzato con gli algoritmi della famiglia RSA o con l'elemento <SecretKey> non con gli algoritmi della famiglia HS.
InvalidKeyConfiguration Se l'elemento secondario <Value> non è definito negli elementi <PrivateKey> o <SecretKey>, il deployment non riuscirà.
EmptyElementForKeyConfiguration Se l'attributo ref dell'elemento secondario <Value> degli elementi <PrivateKey> o <SecretKey> è vuoto o non specificato, il deployment non riuscirà.
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 Verification JWT è vuoto. Se presente, deve essere definito con un nome di variabile di 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 HS Family o l'elemento <SecretKey> con gli algoritmi RSA Family, il deployment non andrà a buon fine.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è 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 prevede il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo nel 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>