Criterio DecodeJWT

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

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.

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 Predefinita Presenza
nome Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di gestione perimetrale applica come la rimozione automatica di caratteri non alfanumerici.

Se vuoi, puoi usare l'elemento <displayname></displayname> per etichetta il criterio nell'editor proxy dell'interfaccia utente di gestione con un linguaggio naturale diverso nome.

 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 per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

 falso Facoltativo
abilitata Imposta il valore su true per applicare il criterio.

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

 true Facoltativo
asinc Questo attributo è obsoleto. falso Deprecato

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

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

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

&lt;Source&gt;

<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 (vedi la nota sopra per informazioni importanti) sulle impostazioni predefinite).
Presenza Facoltativo
Tipo Stringa
Valori validi Nome variabile di flusso perimetrale

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.jwt.FailedToDecode 401 Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
steps.jwt.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jwt.InvalidToken 401 Occurs when the flow variable specified in the <Source> element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidEmptyElement Occurs when the flow variable containing the JWT to be decoded is not specified in the <Source> element of the policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "TokenExpired"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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