Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
Decodifica un JWT senza verificare la firma sul JWT. Questo è particolarmente utile se utilizzato insieme al criterio VerifyJWT, quando è necessario conoscere il valore di un'affermazione all'interno del JWT 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 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.
Video
Guarda un breve video per scoprire come decodificare un JWT.
Esempio: decodificare un JWT
Il criterio mostrato di seguito decodifica un JWT trovato nella variabile di flusso var.jwt. Questa variabile deve essere presente e contenere un JWT valido (decodificabile). Il criterio può ottenere il JWT da 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 successivi nel proxy API possano esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.
Riferimento elemento per decodificare JWT
Il riferimento ai criteri descrive gli elementi e gli attributi del criterio Decodifica JWT.
Attributi che si applicano all'elemento di primo livello
<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">
I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
nome |
Il nome interno 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 |
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 |
falso | Facoltativo |
abilitato |
Imposta su true per applicare il criterio.
Imposta su |
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 Apigee con un nome diverso in linguaggio naturale.
Predefinito | Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio. |
Presenza | Facoltativo |
Tipo | Stringa |
<Source>
<Source>jwt-variable</Source>
Se presente, specifica la variabile di flusso in cui il criterio si aspetta di trovare il JWT da decodificare.
Predefinito | request.header.authorization (consulta la nota sopra per informazioni importanti
sull'impostazione predefinita). |
Presenza | Facoltativo |
Tipo | Stringa |
Valori validi | Un nome di variabile di flusso Apigee |
Variabili di flusso
In caso di 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 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 pubblico JWT. Questo valore può essere una stringa o un array di stringhe. |
claim.expiry |
La data/ora di scadenza, espressa in millisecondi dall'epoca. |
claim.issuedat |
La data di emissione del token, espressa in millisecondi dall'epoca. |
claim.issuer |
L'attributo emittente JWT. |
claim.notbefore |
Se il JWT include un claim nbf, questa variabile conterrà il valore, expressed in milliseconds since epoch. |
claim.subject |
L'attributo subject JWT. |
claim.name |
Il valore dell'affermazione 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. Viene impostata una variabile per ogni claim nel payload. Ad esempio, puoi utilizzare decoded.claim.iat per recuperare la data e l'ora di emissione del JWT, espressa in secondi dall'epoca. Anche se puoi utilizzare anche le variabili di flusso claim.name , questa è la variabile consigliata per accedere a una rivendicazione. |
decoded.header.name |
Il valore analizzabile in JSON di un'intestazione nel payload. Viene 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 |
La data/l'ora di scadenza, formattata 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 la sezione (Algorithm) Header Parameter (Parametro dell'intestazione (algoritmo)). |
header.kid |
L'ID chiave, se aggiunto al momento della generazione del JWT. Per verificare un JWT, consulta anche "Utilizzo di un insieme di chiavi web JSON (JWKS)" nella panoramica dei criteri 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). 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 claim supportati 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 | Causa | Correggi |
---|---|---|---|
steps.jwt.FailedToDecode |
401 |
Si verifica quando il criterio non è in grado di decodificare il JWT. Il JWT potrebbe avere un formato non corretto, non essere valido o non essere decodificabile. | 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 o non può essere risolta. |
build |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome dell'errore | Causa | Correggi |
---|---|---|
InvalidEmptyElement |
Si verifica quando la variabile di flusso contenente il JWT da decodificare non è specificata nell'elemento
<Source> del criterio.
|
build |
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. | fault.name Matches "InvalidToken" |
JWT.failed |
Tutti i criteri JWT impostano la stessa variabile in caso di errore. | JWT.failed = true |
Esempio di risposta di errore
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>