Criterio VerifyJWS

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Verifica la firma su un JWS ricevuto da client o da altri sistemi. Queste norme includono inoltre estrae le intestazioni in variabili di contesto in modo che i criteri o le condizioni successive possano esaminare quei valori per prendere decisioni in merito all'autorizzazione o al routing. Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT.

Se il JWS è verificato e valido, la richiesta viene autorizzati a procedere. Se la firma JWS non può essere verificata o se il JWS non è valido a causa di qualche tipo di errore, tutta l'elaborazione si interrompe e nella risposta viene restituito un errore.

Per informazioni sulle parti di un JWS e su come vengono criptate e firmate, consulta RFC7515.

Video

Guarda un breve video per scoprire come verificare la firma su un JWS. Mentre il video è specifici per la verifica di un JWT, molti dei concetti sono gli stessi per JWS.

Campioni

• Verifica un JWS allegato firmato con HS256 algoritmo
• Verifica un JWS scollegato firmato con RS256 algoritmo

Verifica un JWS allegato firmato con HS256. algoritmo

Questo criterio di esempio verifica un JWS collegato che è stato firmato con l'algoritmo di crittografia HS256, HMAC. utilizzando un checksum SHA-256. JWS viene passato nella richiesta proxy utilizzando un parametro del modulo denominato JWS. La chiave è contenuta in una variabile denominata private.secretkey.

Un JWS allegato contiene l'intestazione, il payload e la firma codificati:

header.payload.signature

La configurazione dei criteri include le informazioni necessarie a Edge per decodificare e valutare 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 secret (archiviata in una variabile di flusso perimetrale, recuperate da 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 nelle variabili di contesto in modo che i criteri o le condizioni successive nel proxy API possono esaminare questi valori. Consulta Variabili di flusso per un delle variabili impostate da questo criterio.

Verificare un JWS scollegato firmato con RS256 algoritmo

Questo criterio di esempio verifica un JWS scollegato che è stato firmato con l'algoritmo RS256. Per verificare: devi fornire la chiave pubblica. JWS viene passato nella richiesta proxy utilizzando un parametro del 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 VerifyJWS specificando il nome della variabile contenente il payload al Elemento <DetachedContent>. I contenuti specificati in <DetachedContent> deve essere nel formato originale non codificato che era al momento della creazione della 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 nelle variabili di contesto in modo che i criteri o le condizioni successive nel proxy API possono esaminare questi valori. Consulta Variabili di flusso per un delle variabili impostate da questo criterio.

Impostare gli elementi chiave

Gli elementi che utilizzi per specificare la chiave usata per verificare il JWS dipendono dall'algoritmo scelto, come illustrato nella tabella seguente:

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

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

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

Riferimento elemento

La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio Verifica JWS.

Nota:la configurazione varierà leggermente a seconda della crittografia. l'algoritmo utilizzato. Fai riferimento agli esempi per esempi che dimostrano configurazioni per casi d'uso specifici.

Attributi che si applicano elemento di primo livello

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali del criterio.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare, in aggiunta all'attributo name, 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* impiegano una coppia di chiavi pubbliche/segrete, mentre gli algoritmi di HS* impiegano un segreto condiviso. Vedi anche Informazioni sugli algoritmi di crittografia della firma.

Puoi specificare più valori separati da virgole. Ad esempio "HS256, HS512" o "RS256, PS256". Tuttavia, non è possibile combinare gli algoritmi HS* con altri o algoritmi ES* con altri, in quanto richiedono un tipo di chiave specifico. È possibile combinare gli algoritmi RS* e PS*.

<AdditionalHeaders/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 la coppia o le coppie nome/valore aggiuntive specificate e che i valori della rivendicazione dichiarata corrispondono.

Un'attestazione aggiuntiva utilizza un nome che non fa parte dei nomi di attestazione JWS standard registrati. Il valore di una dichiarazione aggiuntiva può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore. È possibile specificare il valore di una rivendicazione di uno di questi tipi esplicitamente nella configurazione dei criteri o indirettamente tramite un riferimento a una variabile di flusso.

L'elemento <Claim> utilizza i seguenti attributi:

• name - (Obbligatorio) Il nome della rivendicazione.
• ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questo come la dichiarazione. Se vengono specificati sia un attributo ref sia un valore di dichiarazione esplicito, il valore esplicito è il valore predefinito e viene utilizzato se la variabile del flusso di riferimento non è risolta.
• type: (facoltativo) uno dei seguenti: string (predefinito), numero, booleano o mappa
• array - (Facoltativo) Imposta 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 GenerateJWS per creare un payload scollegato, il JWS generato omette il payload e viene nel formato:

header..signature

Per un payload scollegato, spetta a te passare il payload al criterio VerifyJWS utilizzando Elemento <DetachedContent>. Il payload specificato per i contenuti deve trovarsi la forma originale non codificata che era al momento della creazione della firma JWS.

Il criterio genera un errore quando:

• <DetachedContent> viene specificato quando il JWS non include contenuti scollegati payload (il codice di errore è steps.jws.ContentIsNotDetached).
• <DetachedContent> è stato 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 desideri che il criterio generi un errore quando qualsiasi intestazione elencata nel L'intestazione crit di JWS non è elencata nell'elemento <KnownHeaders>. Il valore viene impostato su true per fare in modo che il criterio VerifyJWS ignori 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>

Imposta il valore false se vuoi che il criterio generi un errore quando viene specificata una variabile di riferimento. del criterio non è risolvibile. Imposta il valore su true per trattare le variabili irrisolvibili come stringhe vuote (nullo).

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Il criterio GenerateJWS utilizza l'elemento <CriticalHeaders> per compilare il crit in un token. Ad esempio:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Il criterio VerifyJWS esamina l'intestazione crit nel JWS, se esistente, e per ogni elemento elencato verifica che l'intestazione sia elencata anche nell'elemento <KnownHeaders>. La L'elemento <KnownHeaders> può contenere un soprainsieme di elementi elencati in crit. È solo necessario che tutte le intestazioni elencate in crit siano elencate nella sezione Elemento <KnownHeaders>. Qualsiasi intestazione che le norme trovano in crit che non è anche elencato in <KnownHeaders>, fa sì che il criterio VerifyJWS non vada a buon fine.

Facoltativamente, puoi configurare il criterio VerifyJWS in modo che ignori 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 nel formato JWKS (RFC 7517) contenente un set di chiavi pubbliche. Utilizzare solo se l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Se il JWS in entrata porta un ID chiave presente nell'insieme JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWS. Per maggiori dettagli su questa funzione. Vedi Utilizzo di un set di chiavi web JSON (JWKS) per verificare un JWS.

Se recuperi il valore da un URL pubblico, Edge memorizza nella cache il JWKS per un periodo di 300 secondi. Quando la cache scade, Edge recupera di nuovo 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 o specificare direttamente la chiave con codifica PEM. Da utilizzare solo se L'algoritmo è uno tra 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. Utilizza solo quando l'algoritmo è uno di HS256, HS384 o HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso.

<Source>

<Source>JWS-variable</Source>

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

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

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

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>