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 inoltre le attestazioni in variabili di contesto, in modo che criteri o condizioni successivi possano esaminare questi valori per prendere decisioni relative all'autorizzazione o al 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 il JWT sia valido in base alla scadenza e alle tempistiche non precedenti, se presenti. Il criterio può facoltativamente anche verificare i valori di rivendicazioni specifiche sul JWT, ad esempio il soggetto, l'emittente, il pubblico o il valore di rivendicazioni aggiuntive.

Se il JWT è verificato e valido, tutte le attestazioni contenute al suo interno vengono estratte in variabili di contesto per essere utilizzate da criteri o condizioni successive 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 di 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, incluso come presentare una richiesta 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 Source), l'algoritmo di firma richiesto, dove trovare la chiave secret (memorizzata in una variabile di flusso perimetrale, che potrebbe essere stata recuperata dal KVM Edge, ad esempio) e un insieme di attestazioni richieste e 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 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 JWT firmato con l'algoritmo RS256

Questo criterio 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 sopra per un esempio completo, incluso come presentare una richiesta alle norme.

Consulta il riferimento dell'elemento per informazioni dettagliate sui requisiti e sulle opzioni per ogni elemento in questo criterio 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."
}

... saranno considerati validi 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 rivendicazione "sub" inclusa nel JWT non corrisponde al valore richiesto dell'elemento "Subject" come specificato nella configurazione del criterio.

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 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 alle norme descrive gli elementi e gli attributi del criterio Verifica JWT.

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

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

<Audience>

<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 viene rilevata alcuna corrispondenza, il criterio genera un errore. Questa attestazione identifica i destinatari a cui è destinato il JWT. Questa è una delle attestazioni registrate menzionate in RFC7519.

<Rivendicazioni/rivendicazioni aggiuntive>

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

Una rivendicazione aggiuntiva utilizza un nome che non rientra tra i nomi standard delle rivendicazioni JWT registrati. 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.

Se includi l'elemento <Claim>, i nomi delle rivendicazioni vengono impostati in modo statico durante la configurazione del criterio. In alternativa, puoi trasmettere 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 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/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 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 JWT. 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.

<CustomClaims>

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Imposta il valore su false se vuoi che il criterio restituisca un errore quando un'intestazione elencata nell'intestazione crit del JWT non è elencata nell'elemento <KnownHeaders>. Se il criterio viene impostato su true, il criterio VerificationJWT ignora 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.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Imposta il valore false (valore predefinito) se vuoi che il criterio restituisca un errore quando un JWT contiene una rivendicazione iat (emessa a) che specifica un'ora nel futuro. Se il criterio viene impostato su true, in modo che il criterio ignori iat durante la verifica.

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

<Issuer>

<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. Una rivendicazione che identifica l'emittente del JWT. Questo è uno degli insiemi di attestazioni registrate menzionati in RFC7519.

<KnownHeaders>

<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'elemento <KnownHeaders> la elenchi. 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 VerificationJWT.

Facoltativamente, puoi configurare il criterio VerificationJWT in modo da ignorare 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 token 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.

<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 JWT in entrata ha 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 file JWKS per 300 secondi. Alla scadenza della cache, 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 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.

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

<Fonte>

<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 dichiarazione identifica o fa una dichiarazione sull'oggetto del JWT. Questo è uno degli insiemi standard di attestazioni menzionate in RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

Il "periodo di tolleranza" per i tempi. Ad esempio, se il limite di tempo è configurato in modo da essere 60 secondi, un JWT scaduto verrebbe considerato ancora valido, per 60 secondi dopo la scadenza dichiarata. L'orario non precedente 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à il soggetto 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 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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>