Criterio VerificationJWS

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:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

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.

<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.

<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*.

<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.

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).

<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.

<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).

<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.

<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.

<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.

<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.

<Fonte>

<Source>JWS-variable</Source>

Se presente, specifica la variabile di flusso in cui il criterio prevede di trovare il JWS da verificare.

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

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.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

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.

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>