Criterio VerifyJWT

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

Cosa

Verifica la firma su un JWT ricevuto da client o altri sistemi. Queste norme includono inoltre estrae le dichiarazioni in variabili di contesto in modo che le norme 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.

Quando questo criterio viene eseguito, Edge verifica la firma di un JWT e che quest'ultimo sia validi in base alla scadenza e ai tempi di non precedente, se presenti. Il criterio può facoltativamente verificare inoltre i valori di specifiche rivendicazioni sul JWT, quali l’oggetto, l’emittente, pubblico o il valore delle rivendicazioni aggiuntive.

Se il JWT è verificato e valido, tutte le rivendicazioni contenute nel JWT saranno estratte nelle variabili di contesto per essere utilizzate da norme o condizioni successive, e la richiesta viene autorizzati a procedere. Se la firma JWT non può essere verificata o se il JWT non è valido a causa di uno dei timestamp, l'intera elaborazione si interrompe e la risposta restituisce un errore.

Per saperne di più sulle parti di un JWT e su come vengono criptate e firmate, consulta RFC7519.

Video

Guarda un breve video per scoprire come verificare la firma su un JWT.

Campioni

• Verificare un JWT firmato con HS256 algoritmo
• Verifica un JWT firmato con RS256 algoritmo

Verifica un JWT firmato con HS256 algoritmo

Questo criterio di esempio verifica un JWT firmato con l'algoritmo di crittografia HS256, HMAC. utilizzando un checksum SHA-256. Il JWT viene passato nella richiesta proxy utilizzando un parametro del modulo denominato jwt. La chiave è contenuta in una variabile denominata private.secretkey. Guarda il video riportato sopra per un esempio completo, incluso come presentare una richiesta per violazione delle norme.

La configurazione dei criteri include le informazioni necessarie a Edge per decodificare e valutare il JWT, ad esempio dove trovare il JWT (in una variabile di flusso specificata nell'elemento Sorgente), di firma, dove trovare la chiave segreta (memorizzata in una variabile di flusso Edge, sono stati recuperati dalla KVM perimetrale, ad esempio) e un insieme di attestazioni richieste e relative e i relativi valori.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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 JWT firmato con RS256 algoritmo

Questo criterio di esempio verifica un JWT firmato con l'algoritmo RS256. Per verificare: devi fornire la chiave pubblica. Il JWT viene passato nella richiesta proxy utilizzando un parametro del modulo denominato jwt. La chiave pubblica è contenuta in una variabile denominata public.publickey. Guarda il video riportato sopra per un esempio completo, incluso come presentare una richiesta per violazione delle norme.

Consulta la sezione di riferimento dell'elemento per i dettagli sui requisiti e sulle opzioni per ogni elemento di questo una norma di esempio.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Per la configurazione precedente, un JWT con questa intestazione...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

E questo payload...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

...sarà considerata valida, se la firma può essere verificata con il chiave.

Un JWT con la stessa intestazione ma con questo payload...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

...sarà considerata non valida, anche se la firma potrà essere verificata, perché "sotto" dichiarazione inclusa nel JWT non corrisponde al valore richiesto dell'attributo "Oggetto" elemento come specificato nella configurazione del criterio.

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 JWT dipendono dall'algoritmo scelto. come illustrato nella tabella seguente:

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

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

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

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

Riferimento elemento

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

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

<VerifyJWT name="JWT" 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*.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Il criterio verifica che la dichiarazione del pubblico nel JWT corrisponda al valore specificato nel configurazione. Se non viene trovata una corrispondenza, il criterio genera un errore. Questa dichiarazione identifica i destinatari a cui è destinato il JWT. Questa è una delle rivendicazioni registrate menzionate in RFC7519.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Verifica che il payload JWT contenga le attestazioni aggiuntive specificate e che le i valori delle rivendicazioni dichiarate corrispondono.

Per un'altra dichiarazione viene utilizzato un nome che non fa parte dei nomi di attestazione JWT 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.

Se includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico quando e configurare il criterio. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle attestazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle attestazioni vengono determinati in fase di esecuzione.

Ad esempio:

<AdditionalClaims ref='json_claims'/>

Dove la variabile json_claims contiene un oggetto JSON nel formato:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

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

<CustomClaims>

Nota: al momento, viene inserito un elemento CustomClaim quando aggiungi una nuova il criterio GeneraJWT tramite l'interfaccia utente. Questo elemento non è funzionale e viene ignorato. Il corretto invece è <AdditionalClaims>. UI verrà aggiornato per inserire gli elementi corretti in un secondo momento.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Verifica che il JWT presenti la dichiarazione jti specifica. Quando il valore di testo e ref sono entrambi vuoti, il criterio genererà un jti contenente un UUID casuale. ID JWT (jti) è un identificatore univoco del JWT. Per ulteriori informazioni su jti, consulta RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Impostalo su false se desideri che il criterio generi un errore quando qualsiasi intestazione elencata nel L'intestazione crit del JWT non è elencata nell'elemento <KnownHeaders>. Il valore viene impostato su true per fare in modo che il criterio VerifyJWT ignori l'intestazione crit.

Un motivo per impostare questo elemento su true è se ti trovi in un ambiente di test e non sei ancora pronto a causare un errore in un'intestazione mancante.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta il valore false (predefinito) se desideri che il criterio generi un errore quando un JWT contiene un token Rivendicazione di iat (inviata alle) che specifica un'ora futura. Se viene impostato su true, il criterio ignora iat durante la verifica.

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Il criterio verifica che l'emittente nel JWT corrisponda alla stringa specificata nel di configurazione. Una dichiarazione che identifica l'emittente del JWT. Questo è uno dei insieme registrato di rivendicazioni menzionate in RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

Il criterio VerifyJWT esamina l'intestazione crit nel JWT, se esistente, e per ogni intestazione elencata 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 è elencato anche in <KnownHeaders>, causa l'errore del criterio VerifyJWT.

Facoltativamente, puoi configurare il criterio VerifyJWT in modo da ignorare l'intestazione crit impostando l'elemento <IgnoreCriticalHeaders> su true.

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Specifica il certificato firmato utilizzato per verificare la firma nel JWT. Utilizza l'attributo ref per Trasmettere il certificato firmato in una variabile di flusso o specificare direttamente il certificato con codifica PEM. Utilizzare solo se l'algoritmo è uno di RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<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 JWT in entrata porta un ID chiave presente nell'insieme JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWT. Per maggiori dettagli su questa funzione. Vedi Utilizzo di un set di chiavi web JSON (JWKS) per verificare un JWT.

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.publickeyorcert"/>
</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 o il certificato pubblico utilizzato per verificare la firma nel JWT. Utilizza l'attributo ref per passa la chiave/certificato in una variabile di flusso o specifica 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 encoding="base16|hex|base64|base64url">
  <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.

<Source>

<Source>jwt-variable</Source>

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

<Subject>

<Subject>subject-string-here</Subject>

Il criterio consente di verificare che il soggetto nel JWT corrisponda alla stringa specificata nel criterio. configurazione. Questa dichiarazione identifica o fa una dichiarazione in merito all'oggetto del JWT. Questo è uno degli insiemi di attestazioni standard menzionati in RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Il "periodo di tolleranza" per volte. Ad esempio, se il margine di tempo è configurato su 60 secondi, un JWT scaduto verrebbe considerato ancora valido per 60 secondi dalla data di scadenza dichiarata. La non prima della data verrà valutato in modo simile. Il valore predefinito è 0 secondi (nessun periodo di tolleranza).

Variabili di flusso

Se l'operazione riesce, i criteri Verify JWT (Verifica JWT) e Decode JWT (Decodifica JWT) sono stati impostati. variabili di contesto in base a questo pattern:

jwt.{policy_name}.{variable_name}

Ad esempio, se il nome del criterio è jwt-parse-token , il criterio archivierà l'oggetto specificato nel JWT alla variabile di contesto denominata jwt.jwt-parse-token.decoded.claim.sub. Per la compatibilità con le versioni precedenti, sarà disponibile anche in jwt.jwt-parse-token.claim.subject.

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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>