Criterio DecodeJWS

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Decodifica l'intestazione JWS senza verificare la firma sul JWS e scrive ogni intestazione in 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 allegato, come nel seguente modulo:

header.payload.signature

In alternativa, il JWS può omettere il payload, chiamato payload sganciato, e avere il seguente formato:

header..signature

Il criterio DecodeJWS funziona con entrambi i formati perché decodifica solo la parte dell'intestazione del JWS. Il criterio DecodeJWS funziona anche indipendentemente dall'algoritmo utilizzato per firmare il JWS.

Consulta la Panoramica dei criteri JWS e JWT per un'introduzione dettagliata e una panoramica del formato di un JWS.

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Video

Guarda un breve video per scoprire come decodificare un JWT. Anche se questo video è specifico per 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. Questa variabile deve essere presente e contenere un JWS valido (decodificabile). Il criterio può ottenere il JWS da qualsiasi variabile di flusso.

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

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

jws.policy-name.header.header-name

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

Riferimento elemento per la decodifica JWS

Il riferimento ai criteri descrive gli elementi e gli attributi del criterio Decodifica JWS.

Attributi che si applicano all'elemento di primo livello

<DecodeJWS name="JWS" 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 del criterio. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di Apigee applica ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

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

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

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio.

 falso Facoltativo
abilitato 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 è stato ritirato. falso Ritirato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione 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>JWS-variable</Source>

Se presente, specifica la variabile di flusso in cui il criterio si aspetta di trovare il JWS da decodificare.

Predefinito request.header.authorization (consulta la nota sopra per informazioni importanti sull'impostazione predefinita).
Presenza Facoltativo
Tipo Stringa
Valori validi Un nome di variabile di flusso Apigee

Variabili di flusso

In caso di esito positivo, i criteri Verifica JWS e Decodifica JWS impostano le variabili di contesto in base a questo pattern:

jws.{policy_name}.{variable_name}

Ad esempio, se il nome del criterio è verify-jws, il criterio memorizza l'algoritmo specificato nel JWS in 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. Viene impostata una variabile per ogni intestazione nel payload. Sebbene tu possa utilizzare anche le variabili di flusso header.name, questa è la variabile consigliata per accedere a un'intestazione.
header.algorithm L'algoritmo di firma utilizzato nella JWS. Ad esempio, RS256, HS384 e così via. Per saperne di più, consulta la sezione (Algorithm) Header Parameter (Parametro dell'intestazione (algoritmo)).
header.kid L'ID chiave, se aggiunto al momento della generazione del JWS. Per verificare un JWS, consulta anche "Utilizzo di un insieme di chiavi web JSON (JWKS)" nella panoramica dei criteri JWT e JWS. Per saperne di più, consulta la sezione Parametro dell'intestazione(ID chiave).
header.type Il valore del tipo di intestazione. Per saperne di più, consulta Parametro intestazione(type).
header.name Il valore dell'intestazione denominata (standard o aggiuntiva). Uno di questi verrà impostato per ogni intestazione aggiuntiva nella parte di intestazione del JWS.
header-json L'intestazione in formato JSON.
payload Il payload JWS se il JWS ha un payload allegato. Per un payload scollegato, questa variabile è vuota.
valid Nel caso di VerifyJWS, questa variabile sarà vera quando la firma è verificata e l'ora corrente è precedente alla scadenza del token e successiva al valore notBefore del token, se sono presenti. In caso contrario, false.

Nel caso di DecodeJWS, questa variabile non è impostata.

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 Si verifica quando
steps.jws.FailedToDecode 401 Il criterio non è riuscito a 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 richiesta mancante o una mancata corrispondenza della richiesta oppure per un'intestazione mancante o una mancata corrispondenza dell'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 dei contenuti scollegato.
steps.jws.MissingPayload 401 Il payload JWS non è presente.
steps.jws.NoAlgorithmFoundInHeader 401 Si verifica quando 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 dell'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.

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>