Criterio DecodeJWT

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio DecodeJWT decodifica un JWT senza verificarne la firma. Questo è più utile se utilizzato in combinazione con il criterio VerifyJWT, quando il valore di un'attestazione all'interno del JWT deve essere noto prima di verificare la firma del JWT.

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

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Esempio: decodifica di un JWT

I criteri mostrati di seguito decodificano 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. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da queste norme.

Riferimento all'elemento per Decode JWT

Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri 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 della policy. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici. (Facoltativo) Utilizza l'elemento <displayname></displayname> per etichettare il criterio nell'editor proxy dell'interfaccia utente Apigee con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta false per restituire un errore quando un criterio non viene rispettato. Questo è il comportamento previsto per la maggior parte delle norme. Imposta true per continuare l'esecuzione del flusso anche dopo l'errore di un criterio.	falso	Facoltativo
abilitato	Imposta su true per applicare la policy. Imposta false per "disattivare" la policy. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
asinc	Questo attributo è stato ritirato.	falso	Deprecato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilizza questo attributo in aggiunta 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 prevede di trovare il JWT da decodificare.

Nota: per impostazione predefinita, il JWT viene recuperato dalla variabile request.header.authorization. In questo caso, Apigee cerca il JWT nell'intestazione Authorization della richiesta. Se trasmetti il JWT nell'intestazione Authorization, non devi includere l'elemento Source nella policy; tuttavia, devi includere Bearer nell'intestazione di autenticazione. Ad esempio, puoi passare il JWT nell'intestazione Authorization in questo modo:

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

Puoi configurare il criterio per recuperare il JWT da una variabile di modulo o di parametro di query o da qualsiasi altra variabile. Se la variabile non esiste o se le norme non riescono a trovare il JWT, le norme restituiscono un errore.

Predefinito	request.header.authorization (Per informazioni importanti sul valore predefinito, consulta la nota riportata sopra).
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Nome di una variabile di flusso Apigee

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name	Description
claim.audience	The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry	The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat	The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer	The JWT issuer claim.
claim.notbefore	If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject	The JWT subject claim.
claim.name	The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name	The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name	The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted	The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm	The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid	The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type	Will be set to JWT.
header.name	The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json	The header in JSON format.
is_expired	true or false
payload-claim-names	An array of claims supported by the JWT.
payload-json	The payload in JSON format.
seconds_remaining	The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted	The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid	In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false. In the case of DecodeJWT, this variable is not set.

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

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.

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 "InvalidToken"
JWT.failed	All JWT policies set the same variable in the case of a failure.	JWT.failed = true

Example error response

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 "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>