Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Verifica la firma su un JWS ricevuto da client o altri sistemi. Questo criterio estrae inoltre le intestazioni in variabili di contesto, in modo che criteri o condizioni successivi possano esaminare quei valori per prendere decisioni in merito all'autorizzazione o al routing. Per un'introduzione dettagliata, consulta la panoramica dei criteri JWS e JWT.
Se il JWS è verificato e valido, la richiesta può procedere. Se non è possibile verificare la firma JWS o se il JWS non è valido a causa di un certo tipo di errore, l'intera elaborazione si interrompe e viene restituito un errore nella risposta.
Per saperne di più sulle parti di un JWS e su come vengono criptate e firmate, fai riferimento a RFC7515.
Video
Guarda un breve video per scoprire come verificare la firma di un JWS. Sebbene questo video sia specifico per la verifica di un JWT, molti concetti sono gli stessi per JWS.
Esempi
- Verifica un JWS collegato firmato con l'algoritmo HS256
- Verifica un JWS scollegato firmato con l'algoritmo RS256
Verifica un JWS collegato firmato con l'algoritmo HS256
Questo criterio di esempio verifica un JWS collegato che è stato firmato con l'algoritmo di crittografia HS256, HMAC
utilizzando un checksum SHA-256. Il JWS viene passato nella richiesta proxy utilizzando un parametro del modulo denominato
JWS
. La chiave è contenuta in una variabile denominata private.secretkey
.
Un JWS collegato contiene l'intestazione codificata, il payload e la firma:
header.payload.signature
La configurazione dei criteri include le informazioni necessarie a Edge per decodificare e valutare il JWS, ad esempio dove trovare il JWS (in una variabile di flusso specificata nell'elemento <Source>
), l'algoritmo di firma richiesto e dove trovare la chiave segreta (memorizzata in una variabile di flusso perimetrale che potrebbe essere stata recuperata dal KVM perimetrale, ad esempio).
<VerifyJWS name="JWS-Verify-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </VerifyJWS>
Il criterio scrive l'output in variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.
Verifica un JWS scollegato firmato con l'algoritmo RS256
Questo criterio di esempio verifica un JWS scollegato che è stato firmato con l'algoritmo RS256. Per la verifica, devi fornire la chiave pubblica. Il JWS viene passato nella richiesta proxy utilizzando un parametro modulo denominato JWS
. La chiave pubblica è contenuta in una variabile denominata public.publickey
.
Un JWS scollegato omette il payload dal JWS:
header..signature
Spetta a te passare il payload al criterio VerificationJWS specificando il nome della variabile contenente il payload all'elemento <DetachedContent>
. I contenuti specificati in <DetachedContent>
devono essere nella forma originale non codificata in cui è stata creata la firma JWS.
<VerifyJWS name="JWS-Verify-RS256"> <DisplayName>JWS Verify RS256</DisplayName> <Algorithm>RS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </PublicKey> <DetachedContent>private.payload</DetachedContent> </VerifyJWS>
Il criterio scrive l'output in variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.
Definire gli elementi chiave
Gli elementi utilizzati per specificare la chiave utilizzata per verificare il JWS dipendono dall'algoritmo scelto, come mostrato nella seguente tabella:
Algoritmo | elementi chiave | |
---|---|---|
HS* |
<SecretKey> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key"/> </PublicKey> oppure: <PublicKey> <JWKS ref="jwks_val_ref_or_url"/> </PublicKey> |
|
* Per saperne di più sui requisiti delle chiavi, consulta Informazioni sugli algoritmi di crittografia della firma. |
Riferimento elemento
Il riferimento alle norme descrive gli elementi e gli attributi del criterio Verifica JWS.
Nota: la configurazione varierà leggermente in base all'algoritmo di crittografia utilizzato. Consulta gli esempi per alcuni esempi che mostrano le configurazioni per casi d'uso specifici.
Attributi che si applicano all'elemento di primo livello
<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">
I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.
Attributo | Descrizione | Predefinita | Presenza |
---|---|---|---|
nome |
Il nome interno della norma. I caratteri utilizzabili nel nome sono limitati a:
A-Z0-9._\-$ % . Tuttavia, l'interfaccia utente di gestione perimetrale applica limitazioni aggiuntive, come la rimozione automatica dei caratteri non alfanumerici.
Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.
Imposta su |
false | Facoltativo |
abilitata |
Imposta il criterio su true per applicare il criterio.
Impostalo su |
true | Facoltativo |
async | Questo attributo è obsoleto. | false | Deprecata |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Utilizzalo in aggiunta all'attributo del nome 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 name del criterio. |
Presenza | Facoltativo |
Digitare | Stringa |
<Algorithm>
<Algorithm>HS256</Algorithm>
Specifica l'algoritmo di crittografia per firmare il token. Gli algoritmi RS*/PS*/ES* utilizzano una coppia di chiavi pubbliche/segrete, mentre gli algoritmi HS* utilizzano un secret condiviso. Vedi anche Informazioni sugli algoritmi di crittografia delle firme.
Puoi specificare più valori separati da virgole. Ad esempio "HS256, HS512" o "RS256, PS256". Tuttavia, non puoi combinare gli algoritmi HS* con altri algoritmi o gli algoritmi ES* con altri perché richiedono un tipo di chiave specifico. Puoi combinare gli algoritmi RS* e PS*.
Predefinita | N/A |
Presenza | Obbligatorio |
Digitare | Stringa di valori separati da virgole |
Valori validi | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Intestazioni aggiuntive/claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
Verifica che l'intestazione JWS contenga le coppie nome/valore aggiuntive specificate e che i valori della rivendicazione dichiarati corrispondano.
Una rivendicazione aggiuntiva utilizza un nome che non rientra nei nomi standard registrati per le rivendicazioni JWS. Il valore di un'attestazione aggiuntiva può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa non è altro che un insieme di coppie nome/valore. Il valore di una rivendicazione di uno di questi tipi può essere specificato in modo esplicito nella configurazione del criterio o indirettamente tramite un riferimento a una variabile di flusso.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare |
Stringa (predefinita), numero, valore booleano o mappa. Se non viene specificato alcun tipo, il tipo è Stringa per impostazione predefinita. |
Array | Impostalo su true per indicare se il valore è un array di tipi. Valore predefinito: false |
Valori validi | Qualsiasi valore che vuoi utilizzare per una rivendicazione aggiuntiva. |
L'elemento <Claim>
prevede i seguenti attributi:
- name: (obbligatorio) il nome del reclamo.
- ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, la norma utilizzerà il valore di questa variabile come attestazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non è risolta.
- type - (Facoltativo) Uno dei seguenti valori: stringa (predefinito), numero, booleano o mappa
- array: (facoltativo) impostato su true per indicare se il valore è un array di tipi. Valore predefinito: false.
<DetachedContent>
<DetachedContent>variable-name-here</DetachedContent>
Un JWS generato con un payload di contenuti ha il seguente formato:
header.payload.signature
Se utilizzi il criterio GeneraJWS per creare un payload scollegato, il JWS generato omette il payload ed è nel formato:
header..signature
Per un payload scollegato, sta a te passare il payload al criterio VerificationJWS utilizzando l'elemento <DetachedContent>
. Il payload di contenuti specificato deve essere nella forma originale non codificata in cui è stata creata la firma JWS.
Il criterio genera un errore se:
<DetachedContent>
viene specificato quando il JWS non contiene un payload di contenuti scollegati (il codice di errore èsteps.jws.ContentIsNotDetached
).<DetachedContent>
viene omesso e il JWS ha un payload di contenuti scollegato (il codice di errore èsteps.jws.InvalidSignature
).
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Riferimento variabile |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Impostalo su false se vuoi che il criterio restituisca un errore quando un'intestazione elencata nell'intestazione crit del JWS non è elencata nell'elemento <KnownHeaders>
.
Se il criterio viene impostato su true, il criterio VerificationJWS ignora l'intestazione crit.
Un motivo per impostare questo elemento su true è se ti trovi in un ambiente di test e non vuoi che il criterio abbia esito negativo a causa di un'intestazione mancante.
Predefinita | false |
Presenza | Facoltativo |
Digitare | Booleano |
Valori validi | true o false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Impostalo su false se vuoi che il criterio generi un errore quando una variabile di riferimento specificata nel criterio non è risolvibile. Imposta il valore su true per trattare qualsiasi variabile non risolvibile come stringa vuota (null).
Predefinita | false |
Presenza | Facoltativo |
Digitare | Booleano |
Valori validi | true o false |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Il criterio GeneraJWS utilizza l'elemento <CriticalHeaders>
per compilare l'intestazione crit in un token. Ad esempio:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
Il criterio VerificationJWS esamina l'intestazione crit nel JWS, se esistente, e per ogni elemento elencato verifica che anche l'elemento <KnownHeaders>
elenchi questa intestazione. L'elemento
<KnownHeaders>
può contenere un soprainsieme degli elementi elencati in crit.
È necessario solo che tutte le intestazioni elencate in crit siano elencate nell'elemento <KnownHeaders>
. Qualsiasi intestazione trovata in crit
dal criterio che non è elencata anche in <KnownHeaders>
, determina la mancata riuscita del criterio VerificationJWS.
Facoltativamente, puoi configurare il criterio VerificationJWS in modo da ignorare l'intestazione crit impostando l'elemento <IgnoreCriticalHeaders>
su true
.
Predefinita | N/A |
Presenza | Facoltativo |
Digitare | Array di stringhe separate da virgole |
Valori validi | Un array o il nome di una variabile contenente l'array. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
Specifica un valore in formato JWKS (RFC 7517) contenente un set di chiavi pubbliche. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.
Se il JWS in entrata ha un ID chiave presente nel set di JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWS. Per maggiori dettagli su questa funzionalità, vedi Utilizzare un set di chiavi web JSON (JWKS) per verificare un JWS.
Se recuperi il valore da un URL pubblico, Edge memorizza nella cache il file JWKS per 300 secondi. Alla scadenza della cache, Edge recupera nuovamente il JWKS.
Predefinita | N/A |
Presenza | Per verificare un JWS utilizzando un algoritmo RSA, devi utilizzare l'elemento JWKS o Value. |
Digitare | Stringa |
Valori validi | Una variabile di flusso, un valore stringa o un URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickey"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
Specifica la chiave pubblica utilizzata per verificare la firma nel JWS. Utilizza l'attributo ref per passare la chiave in una variabile di flusso oppure specifica direttamente la chiave con codifica PEM. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.
Predefinita | N/A |
Presenza | Per verificare un JWS firmato con un algoritmo RSA, devi utilizzare gli elementi JWKS o Value. |
Digitare | Stringa |
Valori validi | Una variabile di flusso o una stringa. |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
Fornisce la chiave segreta utilizzata per verificare o firmare i token con un algoritmo HMAC. Da utilizzare solo quando l'algoritmo è HS256, HS384, HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.
Predefinita | N/A |
Presenza | Obbligatorio per gli algoritmi HMAC. |
Digitare | Stringa |
Valori validi |
Una variabile di flusso che fa riferimento a una stringa.
Nota: se si tratta di una variabile di flusso, deve avere il prefisso "private". Ad esempio:
|
<Fonte>
<Source>JWS-variable</Source>
Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il JWS da verificare.
Predefinita | request.header.authorization (vedi la nota sopra per informazioni importanti
sull'impostazione predefinita). |
Presenza | Facoltativo |
Digitare | Stringa |
Valori validi | Il nome di una variabile di flusso perimetrale. |
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 payload 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 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.AlgorithmInTokenNotPresentInConfiguration |
401 | Si verifica quando il criterio di verifica ha più algoritmi |
steps.jws.AlgorithmMismatch |
401 | L'algoritmo specificato nell'intestazione dal criterio di generazione non corrisponde a quello previsto nel criterio di verifica. Gli algoritmi specificati devono corrispondere. |
steps.jws.ContentIsNotDetached |
401 | <DetachedContent> viene specificato quando il JWS non contiene un payload di contenuti scollegati. |
steps.jws.FailedToDecode |
401 | Il criterio non è stato in grado di decodificare il JWS. Il JWS potrebbe essere danneggiato. |
steps.jws.InsufficientKeyLength |
401 | Per una chiave di dimensioni inferiori a 32 byte per l'algoritmo HS256 |
steps.jws.InvalidClaim |
401 | Per una rivendicazione mancante o mancata corrispondenza di una rivendicazione oppure una mancata corrispondenza di intestazione o intestazione. |
steps.jws.InvalidCurve |
401 | La curva specificata dalla chiave non è valida per l'algoritmo Curva ellittica. |
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.KeyIdMissing |
401 | Il criterio di verifica utilizza un JWKS come origine per le chiavi pubbliche, ma il JWS firmato non include una proprietà kid nell'intestazione. |
steps.jws.KeyParsingFailed |
401 | Impossibile analizzare la chiave pubblica a partire dalle informazioni sulla chiave specificate. |
steps.jws.MissingPayload |
401 | Payload JWS mancante. |
steps.jws.NoAlgorithmFoundInHeader |
401 | Si verifica quando il JWS omette l'intestazione dell'algoritmo. |
steps.jws.NoMatchingPublicKey |
401 | Il criterio di verifica utilizza un JWKS come origine per le chiavi pubbliche, ma il kid nel JWS firmato non è elencato nel JWKS. |
steps.jws.UnhandledCriticalHeader |
401 | Un'intestazione trovata dal criterio Verification JWS nell'intestazione crit non è elencata in KnownHeaders . |
steps.jws.UnknownException |
401 | Si è verificata un'eccezione sconosciuta. |
steps.jws.WrongKeyType |
401 | Tipo di chiave specificato errato. Ad esempio, se specifichi una chiave RSA per un algoritmo Elliptic Curve o una chiave curva per un algoritmo RSA. |
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>