Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza documentazione di Apigee Edge.
Cosa
Decodifica un JWT senza verificare la firma sul JWT. Ciò è particolarmente utile quando utilizzato con la normaVerifyJWT, quando il valore di una dichiarazione all'interno del JWT deve essere noto prima di verificare la firma del JWT.
Il criterio di decodifica JWT funziona indipendentemente dall'algoritmo utilizzato per firmare il JWT. Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Non tutte gli utenti devono conoscere i tipi di criteri e di ambiente. Per informazioni sui tipi di criteri e sulla disponibilità per ciascun tipo di ambiente, consulta Tipi di criteri.
Video
Guarda un breve video per imparare a decodificare un JWT.
Esempio: decodifica di un JWT
Il criterio mostrato di seguito decodifica un JWT trovato nella variabile di flusso var.jwt. Questo deve essere presente e contenere un JWT utilizzabile (decodabile). Il criterio può ottenere il JWT per qualsiasi variabile di flusso.
<DecodeJWT name="JWT-Decode-HS256"> <DisplayName>JWT Verify HS256</DisplayName> <Source>var.jwt</Source> </DecodeJWT>
Il criterio scrive l'output nelle variabili di contesto in modo che i criteri o le condizioni successive nel proxy API possono esaminare questi valori. Consulta Variabili di flusso per un delle variabili impostate da questo criterio.
Riferimento degli elementi per la decodifica JWT
La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio Decode JWT.
Attributi che applica all'elemento di primo livello
<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">
I seguenti attributi sono comuni a tutti gli elementi principali del criterio.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
nome |
Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a:
A-Z0-9._\-$ % . Tuttavia, la UI di Apigee applica
come la rimozione automatica di caratteri non alfanumerici.
Se vuoi, puoi usare l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Si tratta di un comportamento previsto
comportamento per la maggior parte dei criteri.
Imposta su |
falso | Facoltativo |
abilitato |
Imposta il valore su true per applicare il criterio.
Imposta su |
true | Facoltativo |
asinc | Questo attributo è obsoleto. | falso | Ritirato |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Da utilizzare in aggiunta all'attributo name per etichettare il criterio nell'editor proxy della UI di Apigee con un nome diverso in linguaggio naturale.
Predefinito | Se ometti questo elemento, viene utilizzato il valore dell'attributo nome del criterio. |
Presenza | Facoltativo |
Tipo | Stringa |
<Source>
<Source>jwt-variable</Source>
Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il JWT da decodificare.
Predefinito | request.header.authorization (vedi la nota sopra per informazioni importanti)
sulle impostazioni predefinite). |
Presenza | Facoltativo |
Tipo | Stringa |
Valori validi | Nome della variabile di flusso Apigee |
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
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Correggi |
---|---|---|---|
steps.jwt.FailedToDecode |
401 |
Si verifica quando il criterio non è in grado di decodificare il JWT. Il JWT potrebbe non essere valido, non valido o non può essere decodificato. | build |
steps.jwt.FailedToResolveVariable |
401 |
Si verifica quando la variabile di flusso specificata nell'elemento <Source> del
criterio non esiste. |
|
steps.jwt.InvalidToken |
401 |
Si verifica quando la variabile di flusso specificata nell'elemento <Source> del criterio non rientra nell'ambito di applicazione o non può essere risolta. |
build |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa | Correggi |
---|---|---|
InvalidEmptyElement |
Si verifica quando la variabile di flusso contenente il JWT da decodifica non è specificata
nell'elemento <Source> del criterio.
|
build |
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
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>