Norme di VerificationJWT

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Cosa

Verifica la firma su un JWT ricevuto da client o altri sistemi. Questo criterio estrae le rivendicazioni anche in variabili di contesto, in modo che i criteri o le condizioni successivi possano esaminare questi valori per prendere decisioni di autorizzazione o di 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 verifica che quest'ultimo sia valido in base alla scadenza e a volte precedenti, se presenti. La norma facoltativamente può anche verificare i valori di rivendicazioni specifiche sul JWT, ad esempio il soggetto, l'emittente, il pubblico o il valore delle rivendicazioni aggiuntive.

Se il JWT è verificato e valido, tutte le rivendicazioni contenute al suo interno vengono estratte nelle variabili di contesto per essere utilizzate da criteri o condizioni successivi e la richiesta può procedere. Se non è possibile verificare la firma JWT o se il JWT non è valido a causa di uno dei timestamp, l'intera elaborazione si interrompe e viene restituito un errore nella risposta.

Per informazioni sulle parti di un JWT e su come vengono criptate e firmate, fai riferimento a RFC7519.

Video

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

Esempi

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

Verifica 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 sopra per un esempio completo, che include anche come presentare una richiesta di applicazione 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 Source), l'algoritmo di firma richiesto, dove trovare la chiave segreta (memorizzata in una variabile di flusso perimetrale, che potrebbe essere stata recuperata dal KVM Edge, ad esempio) e un insieme di attestazioni 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 l'output nelle 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 JWT firmato con l'algoritmo RS256

Questo criterio di esempio verifica un JWT firmato con l'algoritmo RS256. Per eseguire 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 sopra per un esempio completo, che include anche come presentare una richiesta di applicazione delle norme.

Consulta il riferimento Elemento per i dettagli sui requisiti e sulle opzioni per ogni elemento in questa 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 riportata sopra, 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."
}

... saranno considerate valide 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 è possibile verificare la firma, perché la dichiarazione "sub" inclusa nel JWT non corrisponde al valore richiesto dell'elemento "Subject" specificato nella configurazione del criterio.

Il criterio scrive l'output nelle 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.

Impostazione degli elementi chiave

Gli elementi utilizzati per specificare la chiave utilizzata per verificare il JWT dipendono dall'algoritmo scelto, come mostrato 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

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

Nota: la configurazione varierà leggermente a seconda dell'algoritmo di crittografia utilizzato. Consulta gli esempi per esempi che mostrano 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 dei criteri.

<NomeVisualizzazione>

<DisplayName>Policy Display Name</DisplayName>

Utilizzalo in aggiunta all'attributo nome per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<Algoritmo>

<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* impiegano un secret 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*.

<Pubblico>

<Audience>audience-here</Audience>

or:

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

Il criterio verifica che la rivendicazione del segmento di pubblico nel JWT corrisponda al valore specificato nella configurazione. Se non esiste 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.

<Rivendicazioni aggiuntive/Rivendicazioni>

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

Convalida che il payload JWT contiene le rivendicazioni aggiuntive specificate e che i valori della rivendicazione dichiarati corrispondono.

Una rivendicazione aggiuntiva utilizza un nome che non fa parte dei nomi di rivendicazioni 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 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 della rivendicazione.
• ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come 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 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.

Se includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico durante la configurazione del criterio. In alternativa, puoi passare un oggetto JSON per specificare i nomi delle rivendicazioni. Poiché l'oggetto JSON viene passato come variabile, i nomi delle rivendicazioni 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 }
  }
}

<Intestazioni aggiuntive/Rivendicazione>

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

Convalida che l'intestazione JWT contiene le coppie di nome/valore aggiuntive specificate e che i valori della rivendicazione dichiarati corrispondono.

Una rivendicazione aggiuntiva utilizza un nome diverso da quelli standard registrati per le rivendicazioni JWT. Il valore di una dichiarazione 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 della rivendicazione.
• ref - (Facoltativo) Il nome di una variabile di flusso. Se presente, il criterio utilizzerà il valore di questa variabile come 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 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.

<CustomClaim>

Nota: al momento, un elemento CustomClaims viene inserito quando aggiungi un nuovo criterio generateJWT tramite l'interfaccia utente. Questo elemento non funziona e viene ignorato. L'elemento corretto da utilizzare al suo posto è < AdditionalClaims>. La UI 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 abbia la dichiarazione jti specifica. Quando il valore di testo e l'attributo ref sono entrambi vuoti, il criterio genera un jti contenente un UUID casuale. La rivendicazione dell'ID JWT (jti) è un identificatore univoco per il JWT. Per ulteriori informazioni su Jti, fai riferimento a RFC7519.

<IgnoraCriticalHeaders>

<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>. Impostalo su true per fare in modo che il criterio VerificationJWT 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 su un'intestazione mancante.

<IgnoraIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta il valore false (valore predefinito) se vuoi che il criterio generi un errore quando un JWT contiene una rivendicazione iat (Emesso a) che specifica un'ora futura. Se il criterio viene impostato su true, iat durante la verifica viene ignorato dal criterio.

<IgnoraUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta il valore 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).

<Emittente>

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

Il criterio verifica che l'emittente nel JWT corrisponda alla stringa specificata nell'elemento di configurazione. Un'affermazione che identifica l'emittente del JWT. Questo è uno degli insieme registrati di attestazioni menzionati in RFC7519.

<knownHeaders> (Intestazioni note)

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

Il criterio GeneraJWT utilizza l'elemento <CriticalHeaders> per completare l'intestazione crit in un JWT. Ad esempio:

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

Il criterio VerificationJWT esamina l'intestazione crit nel JWT, se esistente, e per ogni intestazione elencata verifica che anche l'intestazione <KnownHeaders> sia elencata. 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 e non elencata anche in <KnownHeaders> determina la mancata riuscita del criterio VerificationJWT.

Facoltativamente, puoi configurare il criterio VerificationJWT in modo che ignori l'intestazione crit impostando l'elemento <IgnoreCriticalHeaders> su true.

<Chiave pubblica/certificato>

<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 passare il certificato firmato in una variabile di flusso oppure specifica direttamente il certificato con codifica PEM. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

<Chiave pubblica/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. Da utilizzare solo quando l'algoritmo è RS256/RS384/RS512, PS256/PS384/PS512 o ES256/ES384/ES512.

Se il JWT in entrata riporta un ID chiave presente nell'insieme di JWKS, il criterio utilizzerà la chiave pubblica corretta per verificare la firma JWT. Per maggiori dettagli su questa funzionalità, vedi Utilizzare 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. Alla scadenza della cache, Edge recupera di nuovo il JWKS.

<Chiave/valore pubblica>

<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 utilizzati per verificare la firma nel JWT. Utilizza l'attributo ref per passare la chiave/certificato 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.

<Chiave/valore secret>

<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. Da utilizzare solo quando l'algoritmo è HS256, HS384, HS512.

<Sorgente>

<Source>jwt-variable</Source>

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

<Oggetto>

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

Il criterio verifica che l'oggetto nel JWT corrisponda alla stringa specificata nella configurazione del criterio. Questa dichiarazione identifica o fornisce una dichiarazione sull'argomento del JWT. Questo è uno degli insiemi standard di attestazioni menzionati in RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Il "periodo di tolleranza" per i tempi. Ad esempio, se il margine di tempo è configurato su 60 secondi, un JWT scaduto viene considerato ancora valido per 60 secondi dopo la scadenza dichiarata. L'attributo "not-before-time" verrà valutato in modo simile. Il valore predefinito è 0 secondi (nessun periodo di tolleranza).

Variabili di flusso

Se l'operazione ha esito positivo, i criteri Verifica JWT e Decodifica JWT impostano le 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 nella 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 che vengono restituiti e le variabili di errore impostate da Edge quando il criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta le informazioni relative agli errori dei criteri e la gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

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

Esempio di risposta all'errore

Per la gestione degli errori, la best practice consiste nell'intraprendere la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Regola di errore di esempio

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