Criterio VerifyJWT

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Verifica la firma di un JWT ricevuto da client o altri sistemi. Queste norme estraggono anche le rivendicazioni in variabili di contesto in modo che le norme o le condizioni successive possano esaminare questi valori per prendere decisioni di autorizzazione o routing. Per un'introduzione dettagliata, consulta la panoramica dei criteri JWS e JWT.

Quando questo criterio viene eseguito, Edge verifica la firma di un JWT e che il JWT sia valido in base alle ore di scadenza e di inizio validità, se presenti. La norma può anche verificare facoltativamente i valori di rivendicazioni specifiche nel JWT, come il soggetto, l'emittente, il segmento di pubblico o il valore di rivendicazioni aggiuntive.

Se il JWT viene verificato e convalidato, tutte le rivendicazioni contenute al suo interno vengono estratte in variabili di contesto per l'utilizzo da parte di norme o condizioni successive e la richiesta può procedere. Se la firma JWT non può essere verificata o se il JWT non è valido a causa di uno dei timestamp, tutta l'elaborazione si interrompe e nella risposta viene restituito un errore.

Per informazioni 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 di un JWT.

Campioni

• Verificare un JWT firmato con l'algoritmo HS256
• Verificare un JWT firmato con l'algoritmo RS256

Verificare un JWT firmato con l'algoritmo HS256

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 qui sopra per un esempio completo, incluso come effettuare una richiesta relativa alle norme.

La configurazione del criterio 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 Origine), l'algoritmo di firma richiesto, dove trovare la chiave segreta (memorizzata in una variabile di flusso Edge, che potrebbe essere stata recuperata, ad esempio, da Edge KVM) e un insieme di rivendicazioni richieste 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 il suo output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da queste norme.

Verifica di un JWT firmato con l'algoritmo RS256

Questa policy di esempio verifica un JWT firmato con l'algoritmo RS256. Per la verifica, 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 qui sopra per un esempio completo, incluso come effettuare una richiesta relativa alle norme.

Per informazioni dettagliate sui requisiti e sulle opzioni per ogni elemento di questo criterio di esempio, consulta la documentazione di riferimento sugli elementi.

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

… verrà considerata valida se la firma può essere verificata con la chiave pubblica fornita.

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

… verrà considerato non valido, anche se la firma può essere verificata, perché l'attestazione "sub" inclusa nel JWT non corrisponde al valore richiesto dell'elemento "Subject" come specificato nella configurazione delle norme.

Il criterio scrive il suo output nelle variabili di contesto in modo che i criteri o le condizioni successivi nel proxy API possano esaminare questi valori. Consulta la sezione Variabili di flusso per un elenco delle variabili impostate da queste norme.

Impostazione degli elementi chiave

Gli elementi che utilizzi per specificare la chiave utilizzata per verificare il JWT dipendono dall'algoritmo scelto, come mostrato nella seguente tabella:

<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

Il riferimento al criterio descrive gli elementi e gli attributi del criterio Verifica JWT.

Nota: la configurazione varia leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta gli esempi per visualizzare configurazioni per casi d'uso specifici.

Attributi che si applicano all'elemento di primo livello

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali delle policy.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilizza questo attributo 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* utilizzano una coppia di chiavi pubblica/segreta, mentre gli algoritmi HS* utilizzano 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 puoi combinare gli algoritmi HS* con altri o gli algoritmi ES* con altri perché richiedono un tipo di chiave specifico. Puoi combinare gli algoritmi RS* e PS*.

<Audience>

<Audience>audience-here</Audience>

or:

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

Il criterio verifica che l'attestazione del pubblico nel JWT corrisponda al valore specificato nella configurazione. Se non viene trovata alcuna corrispondenza, la norma genera un errore. Questa rivendicazione identifica i destinatari a cui è destinato il JWT. Si tratta di una delle rivendicazioni registrate menzionate nella 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 rivendicazioni aggiuntive specificate e che i valori delle rivendicazioni asserite corrispondano.

Un'attestazione aggiuntiva utilizza un nome che non è uno dei nomi delle attestazioni JWT standard registrate. Il valore di un'ulteriore rivendicazione può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore. Il valore di un'attestazione 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 della richiesta.
• ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come rivendicazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è quello predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non viene risolta.
• type: (facoltativo) uno dei seguenti valori: stringa (impostazione predefinita), numero, booleano o mappa
• array: (facoltativo) impostalo su true per indicare se il valore è un array di tipi. Valore predefinito: false.

Quando includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico quando configuri la policy. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle attestazioni vengono determinati in fase di runtime.

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 le coppie nome/valore di rivendicazione aggiuntive specificate e che i valori delle rivendicazioni asserite corrispondano.

Un'attestazione aggiuntiva utilizza un nome che non è uno dei nomi standard e registrati delle attestazioni JWT. Il valore di un'ulteriore rivendicazione può essere una stringa, un numero, un valore booleano, una mappa o un array. Una mappa è semplicemente un insieme di coppie nome/valore. Il valore di un'attestazione 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 della richiesta.
• ref: (facoltativo) il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come rivendicazione. Se vengono specificati sia un attributo ref sia un valore di rivendicazione esplicito, il valore esplicito è quello predefinito e viene utilizzato se la variabile di flusso a cui viene fatto riferimento non viene risolta.
• type: (facoltativo) uno dei seguenti valori: stringa (impostazione predefinita), numero, booleano o mappa
• array: (facoltativo) impostalo su true per indicare se il valore è un array di tipi. Valore predefinito: false.

<CustomClaims>

Nota:al momento, viene inserito un elemento CustomClaims quando aggiungi un nuovo criterio GenerateJWT tramite la UI. Questo elemento non è funzionale e viene ignorato. L'elemento corretto da utilizzare è <AdditionalClaims>. L'interfaccia utente verrà aggiornata 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 contenga l'attestazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genererà un jti contenente un UUID casuale. L'attestazione JWT ID (jti) è un identificatore univoco per il JWT. Per saperne di più su jti, consulta RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Imposta il valore su false se vuoi che il criterio generi un errore quando un'intestazione elencata nell'intestazione crit del JWT non è elencata nell'elemento <KnownHeaders>. Imposta 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 su false (impostazione predefinita) se vuoi che il criterio generi un errore quando un JWT contiene un attributo iat (Emesso il) che specifica un orario futuro. Imposta su true per fare in modo che il criterio ignori iat durante la verifica.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta su false se vuoi che il criterio generi un errore quando qualsiasi variabile a cui viene fatto riferimento specificata nel criterio non è risolvibile. Imposta su true per considerare qualsiasi variabile non risolvibile come una stringa vuota (null).

<Issuer>

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

I criteri verificano che l'emittente nel JWT corrisponda alla stringa specificata nell'elemento di configurazione. Un'affermazione che identifica l'emittente del JWT. Si tratta di uno dei set di rivendicazioni registrate menzionate nella RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

La norma GenerateJWT utilizza l'elemento <CriticalHeaders> per compilare l'intestazione crit in un JWT. Ad esempio:

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

Il criterio VerifyJWT esamina l'intestazione crit nel JWT, se presente, e per ogni intestazione elencata verifica che anche l'elemento <KnownHeaders> elenchi l'intestazione. L'elemento <KnownHeaders> può contenere un superset degli elementi elencati in crit. È necessario solo che tutte le intestazioni elencate in crit siano elencate nell'elemento <KnownHeaders>. Qualsiasi intestazione trovata dal criterio in crit che non è elencata anche in <KnownHeaders> causa l'errore del criterio VerifyJWT.

Se vuoi, puoi configurare il criterio VerifyJWT in modo che ignori 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 sul JWT. Utilizza l'attributo ref per trasferire il certificato firmato in una variabile di flusso o specificare direttamente il certificato con codifica PEM. Utilizza solo quando l'algoritmo è 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 in formato JWKS (RFC 7517) contenente un insieme di chiavi pubbliche. Utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Se il JWT in entrata contiene un ID chiave presente nel set di JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWT. Per informazioni dettagliate su questa funzionalità, consulta 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 nuovamente 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 sul JWT. Utilizza l'attributo ref per trasferire la chiave/il certificato in una variabile di flusso o specificare direttamente la chiave con codifica PEM. Utilizzare solo quando l'algoritmo è 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 è 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 verifica che il soggetto nel JWT corrisponda alla stringa specificata nella configurazione del criterio. Questa rivendicazione identifica o fa un'affermazione sull'oggetto del JWT. Si tratta di uno dei set di standard menzionati nella RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Il "periodo di tolleranza" per gli orari. Ad esempio, se il tempo consentito è configurato su 60 secondi, un JWT scaduto verrà considerato ancora valido per 60 secondi dopo la scadenza dichiarata. Il not-before-time 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

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 ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Esempio di risposta di errore

Per la gestione degli errori, la best practice è il trap della parte errorcode dell'errore la risposta corretta. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

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