Criterio DecodeJWT

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Decodifica un JWT senza verificarne la firma. È più utile se utilizzato insieme al criterio VerifyJWT, quando il valore di una rivendicazione all'interno del JWT deve essere noto prima di verificarne la firma.

Il criterio JWT Decode funziona indipendentemente dall'algoritmo utilizzato per firmare il JWT. Per un'introduzione dettagliata, consulta la panoramica dei criteri JWS e JWT.

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 il suo output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Per un elenco delle variabili impostate da questo criterio, consulta Variabili di flusso.

Riferimento agli elementi per la decodifica del JWT

Il riferimento al criterio descrive gli elementi e gli attributi del criterio Decode 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 Predefinita 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 gestione di Edge applica ulteriori restrizioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

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

 N/D Obbligatorio
continueOnError Imposta su false per restituire un errore quando un criterio non riesce. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo che un criterio non è riuscito.

 false Facoltativo
attivato 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 è deprecato. false Deprecato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

Predefinita 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 prevede di trovare il JWT da decodificare.

Predefinita request.header.authorization (per informazioni importanti sul valore predefinito, consulta la nota sopra ).
Presenza Facoltativo
Tipo Stringa
Valori validi Un nome di variabile di flusso Edge

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 archivierà l'oggetto specificato nel JWT alla 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 del 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 del soggetto JWT.
claim.name Il valore dell'attestazione denominata (standard o aggiuntiva) nel payload. Una di queste sarà impostata su ogni richiesta nel payload.
decoded.claim.name Il valore analizzabile in JSON della dichiarazione 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 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. Puoi usare 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 della 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 Parametro 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, 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à true quando la firma verrà verificata e l'ora corrente è precedente alla scadenza del token e dopo il 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 e i messaggi di errore restituiti e le variabili di errore impostate da Edge 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.
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.

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.

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 elencato nella precedente tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice di errore. fault.name Matches "TokenExpired"
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 è il trap della parte errorcode dell'errore la risposta corretta. 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 "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>