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

Variabili di flusso

Se l'operazione riesce, i criteri Verify JWS e Decode JWS sono stati impostati. variabili di contesto in base a questo pattern:

jws.{policy_name}.{variable_name}

Ad esempio, se il nome del criterio è verify-jws, verrà archiviato dall'algoritmo specificato nel JWS a questa variabile di contesto: jws.verify-jws.header.algorithm

Nome variabile Descrizione
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.
header.algorithm L'algoritmo di firma utilizzato nel JWS. 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 JWS. Consulta anche la sezione "Utilizzo di un set di chiavi web JSON (JWKS)" presso JWT e JWS panoramica dei criteri per verificare un JWS. Per saperne di più, consulta Parametro intestazione(ID chiave).
header.type Il valore del tipo di intestazione. Per saperne di più, consulta Parametro intestazione(Tipo).
header.name Il valore dell'intestazione denominata (standard o aggiuntiva). Una di queste sarà impostata su ogni intestazione aggiuntiva nella parte di intestazione del JWS.
header-json L'intestazione in formato JSON.
payload Il payload JWS se al JWS è collegato un payload. Per un payload scollegato, questa variabile è vuota.
valid Nel caso di VerifyJWS, questa variabile sarà true dopo la verifica della firma 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 DecodeJWS, 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 Occurs when
steps.jws.FailedToDecode 401 The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidJws 401 This error occurs when the JWS signature verification fails.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.UnknownException 401 An unknown exception occurred.

Deployment errors

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

Error name Occurs when
InvalidAlgorithm The only valid values are: 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

 Other possible deployment errors.

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 "TokenExpired"
JWS.failed Tutti i criteri JWS impostano la stessa variabile in caso di errore. jws.JWS-Policy.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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>