Criterio DecodeJWS

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

Cosa

Decodifica l'intestazione JWS senza verificare la firma al suo interno e scrive ogni intestazione in un come una variabile di flusso. Questo criterio è più utile se utilizzato insieme al criterio VerifyJWS. quando il valore di un'intestazione all'interno del JWS deve essere noto prima di verificare la firma del JWS.

Un JWS può avere un payload collegato, ad esempio:

header.payload.signature

In alternativa, JWS può omettere il payload, detto payload scollegato, ed essere in questo formato:

header..signature

Il criterio DecodeJWS funziona con entrambi i moduli perché decodifica solo la parte di intestazione del JWS. Il criterio DecodeJWS funziona anche a prescindere dall'algoritmo utilizzato per firmare il JWS.

Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT. e una panoramica del formato di un JWS.

Video

Guarda un breve video per imparare a decodificare un JWT. Mentre il video è specifici di un JWT, molti dei concetti sono gli stessi per JWS.

Esempio: decodifica di un JWS

Il criterio mostrato di seguito decodifica un JWS trovato nella variabile di flusso var.JWS. Questo deve essere presente e contenere un JWS utilizzabile (decodabile). Il criterio può ottenere il JWS per qualsiasi variabile di flusso.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

Per ogni intestazione nella porzione di intestazione di JWS, il criterio imposta una variabile di flusso denominata:

jws.policy-name.header.header-name

Se JWS ha un payload collegato, imposta jws.policy-name.header.payload di flusso al payload. Per un payload scollegato, payload è vuoto. Consulta Variabili di flusso per un elenco completo delle variabili impostate da questo criterio.

Riferimento degli elementi per la decodifica di JWS

Il riferimento al criterio descrive gli elementi e gli attributi del criterio Decode JWS.

Attributi che applica all'elemento di primo livello

<DecodeJWS name="JWS" 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>JWS-variable</Source>

Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il token JWS per 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

Flow variables

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

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

Variable name Description
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.
header.algorithm The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more.
header.type The header type value. See (Type) Header Parameter for more.
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 JWS.
header-json The header in JSON format.
payload The JWS payload if the JWS has an attached payload. For a detached payload, this variable is empty.
valid In the case of VerifyJWS, 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 DecodeJWS, this variable is not set.

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 Si verifica quando
steps.jws.FailedToDecode 401 Il criterio non è stato in grado di decodificare il JWS. Il JWS potrebbe essere danneggiato.
steps.jws.FailedToResolveVariable 401 Si verifica quando la variabile di flusso specificata nell'elemento <Source> del criterio non esiste.
steps.jws.InvalidClaim 401 Per una rivendicazione mancante o mancata corrispondenza di una rivendicazione oppure una mancata corrispondenza di intestazione o intestazione.
steps.jws.InvalidJsonFormat 401 JSON non valido trovato nell'intestazione JWS.
steps.jws.InvalidJws 401 Questo errore si verifica quando la verifica della firma JWS non va a buon fine.
steps.jws.InvalidPayload 401 Il payload JWS non è valido.
steps.jws.InvalidSignature 401 <DetachedContent> viene omesso e il JWS ha un payload di contenuti scollegato.
steps.jws.MissingPayload 401 Payload JWS mancante.
steps.jws.NoAlgorithmFoundInHeader 401 Si verifica quando il JWS omette l'intestazione dell'algoritmo.
steps.jws.UnknownException 401 Si è verificata un'eccezione sconosciuta.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome errore Si verifica quando
InvalidAlgorithm Gli unici valori validi sono: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Altri possibili errori di deployment.

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"
JWS.failed All JWS policies set the same variable in the case of a failure. jws.JWS-Policy.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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>