Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
Decodifica l'intestazione JWS senza verificare la firma nel file JWS e scrive ogni intestazione in una variabile di flusso. Questo criterio è particolarmente utile se utilizzato insieme al criterio VerificationJWS, 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
Oppure, JWS può omettere il payload, chiamato payload detached, ed essere nel seguente formato:
header..signature
Il criterio DecodeJWS funziona con entrambi i moduli perché decodifica solo la parte dell'intestazione del JWS. Anche il criterio DecodeJWS funziona a prescindere 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 estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.
Video
Guarda un breve video per scoprire come decodificare un JWT. Questo video è specifico per un JWT, ma molti dei concetti sono gli stessi.
Esempio: decodifica di un file 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 utilizzabile (decodabile). 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 file JWS, il criterio imposta una variabile di flusso denominata:
jws.policy-name.header.header-name
Se JWS ha un payload collegato, imposta la variabile di flusso jws.policy-name.header.payload
sul payload. Per un payload scollegato, il valore payload
è vuoto.
Consulta Variabili di flusso per un elenco completo delle variabili impostate da questo criterio.
Riferimento elemento per Decode JWS
Il riferimento ai criteri descrive gli elementi e gli attributi del criterio JWS di decodifica.
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 del criterio.
Attributo | Description | Predefinito | Presenza |
---|---|---|---|
comune |
Il nome interno del criterio. I caratteri che puoi usare nel nome sono limitati a:
A-Z0-9._\-$ % . Tuttavia, la UI di Apigee applica limitazioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Imposta il criterio su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.
Impostalo su |
false | Facoltativo |
abilitato |
Imposta il criterio su true per applicare il criterio.
Imposta il criterio su |
true | Facoltativo |
async | Questo attributo è obsoleto. | false | Deprecata |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Utilizzalo in aggiunta all'attributo nome 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 |
<Fonte>
<Source>JWS-variable</Source>
Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il JWS da decodificare.
Predefinito | request.header.authorization (vedi la nota sopra per informazioni importanti sull'impostazione predefinita). |
Presenza | Facoltativo |
Tipo | Stringa |
Valori validi | Nome della variabile di flusso Apigee |
Variabili di flusso
Se l'operazione ha 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 archivierà l'algoritmo specificato nel JWS in questa variabile di contesto:
jws.verify-jws.header.algorithm
Nome variabile | Descrizione |
---|---|
decoded.header.name |
Il valore analizzabile JSON di un'intestazione nel payload. Nel payload viene impostata una variabile per ogni intestazione. Sebbene sia possibile utilizzare anche le variabili di flusso header.name ,
questa è la variabile consigliata da utilizzare per accedere a un'intestazione. |
header.algorithm |
L'algoritmo di firma utilizzato sul JWS. Per esempio, RS256, HS384, ecc. Per saperne di più, consulta Parametro intestazione(algoritmo). |
header.kid |
L'ID chiave, se aggiunto al momento della generazione del JWS. Vedi anche "Utilizzo di un set di chiavi web JSON (JWKS)" nella panoramica dei criteri JWT e JWS 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). 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 a JWS è collegato un payload. Per un paylod scollegato, questa variabile è vuota. |
valid |
Nel caso di VerificationJWS, questa variabile sarà vera quando la firma viene verificata e l'ora attuale è precedente alla scadenza del token e dopo il valore notBefore del token, se sono presenti. Altrimenti false.
Nel caso di DecodeJWS, questa variabile non è impostata. |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee 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 . |
|
Altri possibili errori di deployment. |
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di 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 prevede il trap della parte errorcode
della risposta di errore. Non fare affidamento sul testo nel 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>