Criterio DecodeJWS

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio DecodeJWS decodifica l'intestazione JWS senza verificare la firma sulla JWS e scrive ogni intestazione in una variabile di flusso. Questo criterio è più utile se utilizzato in combinazione con il 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, nel formato:

header.payload.signature

In alternativa, il JWS può omettere il payload, chiamato payload disaccoppiato, e avere il seguente 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 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.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempio: decodifica di una 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). La policy 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 sezione delle intestazioni del JWS, il criterio imposta una variabile di flusso denominata:

jws.policy-name.header.header-name

Se la firma JWS ha un payload allegato, la variabile di flusso jws.policy-name.header.payload viene impostata sul payload. Per un payload separato, payload è vuoto. Consulta Variabili di flusso per un elenco completo delle variabili impostate da queste norme.

Riferimento all'elemento per Decodifica JWS

Il riferimento al criterio 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 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. 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 false per restituire un errore quando una policy non va a buon fine. Questo è il comportamento previsto per la maggior parte delle norme. Imposta su true per continuare l'esecuzione del flusso anche dopo l'esito negativo 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 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 prevede di trovare il JWS da decodificare.

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

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

Puoi configurare le norme per recuperare il JWS da una variabile di modulo o parametro di query o da qualsiasi altra variabile. Se la variabile non esiste o se le norme non riescono a trovare il JWS, 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 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 paylod, 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 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.

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>