Panoramica dei criteri JWS e JWT

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo argomento fornisce informazioni generali su JWT (JSON Web Token) e JWS (JSON Web Signature) e sui criteri JWS/JWT di Apigee che potrebbero interessare gli sviluppatori di proxy Apigee.

Introduzione

Sia JWS che JWT sono comunemente utilizzati per condividere attestazioni o asserzioni tra applicazioni collegate. I criteri JWS/JWT consentono ai proxy API Apigee di:

• Genera un JWT firmato o un JWS oppure un JWT criptato.
• Verifica un JWT o un JWS firmato oppure un JWT criptato e verifica le attestazioni selezionate all'interno del JWS/JWT.
• Decodifica un JWT firmato o criptato o un JWS senza convalidare la firma o decriptare il JWT o il JWS criptato. Nel caso di un JWS, il criterio DecodeJWS può decodificare solo le attestazioni nell'intestazione del JWS. Nel caso di un JWT criptato, il criterio DecodeJWT può decodificare solo l'intestazione non criptata.

Negli ultimi due casi, il criterio imposta anche le variabili di flusso. Ciò consente ai criteri successivi nel flusso di Apigee di esaminare le richieste in JWT o JWS e di prendere decisioni in base a queste attestazioni o di propagare queste informazioni ai servizi di backend.

Quando utilizzi i criteri VerificationJWS o VerificationJWT, un JWS/JWT non valido verrà rifiutato e comporterà una condizione di errore. Allo stesso modo, quando utilizzi i criteri DecodeJWS o DecodeJWT, un formato JWS/JWT non corretto genererà una condizione di errore.

Video

Guarda un breve video per una rapida introduzione a JWT. Sebbene questo video sia specifico per la generazione di un JWT, molti concetti sono uguali per JWS.

Che breve video per saperne di più sulla struttura JWT.

Casi d'uso

Puoi utilizzare i criteri JWS/JWT per:

• Genera un nuovo JWS/JWT sul lato proxy o sull'endpoint di destinazione di un proxy Apigee. Ad esempio, puoi creare un flusso di richiesta proxy che genera un JWS/JWT e lo restituisce a un client. In alternativa, puoi progettare un proxy in modo che generi un JWS/JWT nel flusso di richiesta di destinazione e lo colleghi alla richiesta inviata alla destinazione. JWS/JWT e le sue richieste sarebbero quindi disponibili per abilitare i servizi di backend per applicare ulteriori elaborazioni della sicurezza.
• Verifica ed estrai le attestazioni da un JWS/JWT ottenuto da richieste del client in entrata, dalle risposte del servizio di destinazione, dalle risposte dei criteri di callout del servizio o da altre origini. Per un JWS/JWT firmato, Apigee utilizzerà uno degli algoritmi RSA, ECDSA o HMAC per verificare la firma, indipendentemente dal fatto che il JWS/JWT sia stato generato da Apigee o da una terza parte. Per un JWT criptato, Apigee decripta il JWT, utilizzando uno degli algoritmi di crittografia JWA supportati (consulta il documento IETF RFC 7518).
• Decodifica un JWS/JWT. La decodifica è particolarmente utile se utilizzata insieme al criterio Verifica JWS/JWT, nei casi in cui il valore di un'attestazione (JWT) o di un'intestazione (JWS/JWT) all'interno di JWS/JWT deve essere noto prima di verificare un JWS/JWT firmato o di decriptare un JWT criptato.

Parti di un JWS/JWT

Un JWS/JWT firmato codifica le informazioni in tre parti separate da punti:

Header.Payload.Signature

• Il criterio Genera JWS/JWT crea tutte e tre le parti.
• Il criterio Verifica JWS/JWT esamina tutte e tre le parti.
• Il criterio DecodeJWS esamina solo l'intestazione. Il criterio DecodeJWT esamina solo l'intestazione e il payload.

Un JWS supporta anche un modulo detached che omette il payload da JWS:

Header..Signature

Con un JWS scollegato, il payload viene inviato separatamente da JWS. Per specificare il payload JWS non elaborato e non codificato, devi utilizzare l'elemento <DetachedContent> del criterio Verification JWS. Il criterio Verifica JWS verifica quindi il JWS utilizzando l'intestazione e la firma nel JWS e il payload specificato dall'elemento <DetachedContent>.

Un JWT criptato codifica le informazioni in cinque parti separate da punti:

Header.Key.InitializationVector.Payload.AuthenticationTag

I criteri generateJWT e VerificationJWT creano o esaminano tutte queste parti. DecodeJWT può esaminare solo l'intestazione non criptata.

Per scoprire di più sui token e su come vengono codificati, firmati o criptati, consulta i documenti relativi agli standard pertinenti:

• JWT: IETF RFC7519
• JWS: IETF RFC7515

Differenze tra JWS e JWT

Puoi utilizzare un JWT o un JWS per condividere rivendicazioni o asserzioni tra applicazioni collegate. La principale differenza tra i due è la rappresentazione del payload:

• JWT
  • Il payload è sempre un oggetto JSON.
  • Il payload è sempre collegato al JWT.
  • L'intestazione typ del token è sempre impostata su JWT.
  • Il payload può essere firmato o criptato.
• JWS
  • Il payload può essere rappresentato da qualsiasi formato, ad esempio un oggetto JSON, un flusso di byte, un flusso di ottetti e altri.
  • Il payload non deve essere collegato a JWS.
  • L'intestazione e il payload sono sempre firmati. JWS non supporta la crittografia.

Poiché il formato JWT utilizza sempre un oggetto JSON per rappresentare il payload, i criteri Apigee generateJWT e VerificationJWT supportano integrati per gestire nomi di attestazioni registrate comuni, come aud, iss, sub e altri. Ciò significa che puoi utilizzare gli elementi del criterio GeneraJWT per impostare queste attestazioni nel payload e gli elementi del criterio VerificationJWT per verificarne i valori. Per saperne di più, consulta la sezione Nomi di attestazioni registrate della specifica JWT.

Oltre a supportare determinati nomi di attestazioni registrate, il criterio GeneraJWT supporta direttamente l'aggiunta di attestazioni con nomi arbitrari al payload o all'intestazione del JWT. Ogni attestazione è una semplice coppia nome/valore, in cui il valore può essere di tipo number, boolean, string, map o array.

Quando utilizzi GeneraJWS, fornisci una variabile di contesto che rappresenti il payload. Poiché un JWS può utilizzare qualsiasi rappresentazione dei dati per il payload, non esiste il concetto di "rivendicazione del payload" in un JWS e il criterio GeneraJWS non supporta l'aggiunta di attestazioni con nomi arbitrari al payload. È possibile utilizzare il criterio GeneraJWS per aggiungere attestazioni con nomi arbitrari all'intestazione del JWS. Inoltre, i criteri JWS supportano un payload scollegato, in cui JWS omette il payload. Un payload scollegato ti consente di inviare JWS e payload separatamente. L'utilizzo di un payload scollegato può ridurre l'efficienza dello spazio, in particolare per i payload di grandi dimensioni, ed è richiesto da diversi standard di sicurezza.

Firma e crittografia

Apigee può generare JWT firmato o criptato. Scegli JWT firmato quando il payload non deve essere segreto, ma è importante fornire ai lettori garanzie di integrità e non rifiuto. Un JWT firmato assicura ai lettori che il payload non è cambiato da quando è stato firmato il JWT e che quest'ultimo è stato firmato dal titolare della chiave privata. Scegli JWT criptato quando il payload deve essere secret. Un JWT criptato garantisce la riservatezza del payload, in quanto solo il titolare della chiave appropriato può decriptarlo.

È possibile utilizzare JWT criptato e firmato insieme, soprattutto quando il JWT criptato utilizza un algoritmo di crittografia asimmetrico (RSA, ECDSA). In questo caso, non è possibile determinare l'identità del producer di quel JWT perché la chiave di crittografia è pubblica. Per risolvere questo problema, combina la firma con la crittografia. Un modello tipico è il seguente:

• Firma un payload per produrre un JWS o un JWT firmato.
• Cripta il risultato firmato per produrre un JWT criptato.

L'incorporamento di un payload firmato in un JWT criptato con questo approccio fornisce garanzie sia di non rifiuto che di riservatezza. I criteri di Apigee possono produrre, decodificare e verificare queste combinazioni.

Algoritmi di firma

Per JWT firmato, i criteri di verifica JWS/JWT e di generazione JWS/JWT supportano gli algoritmi RSA, RSASSA-PSS, ECDSA e HMAC utilizzando checksum SHA2 con forza di bit 256, 384 o 512. I criteri DecodeJWS e DecodeJWT funzionano a prescindere dall'algoritmo utilizzato per firmare JWS/JWT.

Nota: tutti gli algoritmi utilizzati da JWS/JWT, e le chiavi che richiedono, sono descritti nella specifica JWA, RFC 7518.

Algoritmi HMAC

Gli algoritmi HMAC si basano su un secret condiviso, chiamato chiave segreta, per creare la firma (nota anche come firma JWS/JWT) e verificare la firma.

La lunghezza minima della chiave segreta dipende dalla potenza in bit dell'algoritmo:

• HS256: lunghezza minima della chiave di 32 byte
• HS384: lunghezza minima della chiave di 48 byte
• HS512: lunghezza minima della chiave di 64 byte

Algoritmi RSA

Gli algoritmi RSA utilizzano una coppia di chiave pubblica/privata per la firma crittografica. La specifica JWA utilizza i moniker RS256, RS384 e RS512 per rappresentare queste opzioni. Con le firme RSA, la parte che firma utilizza una chiave privata RSA per firmare il JWS/JWT, mentre la parte che esegue la verifica utilizza la chiave pubblica RSA corrispondente per verificare la firma sul JWS/JWT. Non sono previsti requisiti di dimensioni dei tasti.

Algoritmi RSASSA-PSS

Gli algoritmi RSASSA-PSS sono un aggiornamento degli algoritmi RSA e utilizzano i nomi PS256, PS384 e PS512. Come le varianti RS*, RSASSA-PSS utilizza una coppia di chiavi RSA pubblica/privata per la firma crittografica. I limiti di formato, meccanismo e dimensioni della chiave sono gli stessi degli algoritmi RS*.

Algoritmi ECDSA

L'insieme di algoritmi di Elliptic Curve Digital Signature Algorithm (ECDSA) è costituito da algoritmi di crittografia a curva ellittica con una curva P-256, P-384 o P-521. Quando utilizzi gli algoritmi ECDSA, questi determinano il tipo di chiave pubblica e privata che devi specificare:

Algoritmo	Curva	Requisito chiave
ES256	P-256	Una chiave generata dalla curva P-256 (nota anche come secp256r1 o prime256v1)
ES384	P-384	Una chiave generata dalla curva P-384 (nota anche come secp384r1)
ES512	P-521	Una chiave generata dalla curva P-521 (nota anche come secp521r1)

Algoritmi di crittografia

Quando si utilizza GeneraJWT e VerificationJWT per gestire JWT criptato, i criteri supportano i seguenti algoritmi:

• dir
• RSA-OAEP-256
• A128KW, A192KW, A256KW
• A128GCMKW, A192GCMKW, A256GCMKW
• PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
• ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW

Chiavi e rappresentazioni chiave

Gli standard JOSE, che riguardano JWS, JWT firmato e criptato e altri ancora, descrivono come utilizzare le chiavi di crittografia per firmare o criptare le informazioni. Gli elementi fondamentali per qualsiasi operazione crittografica sono l'algoritmo e la chiave. Algoritmi diversi richiedono tipi di chiavi diversi e, in alcuni casi, dimensioni di chiave diverse.

Gli algoritmi simmetrici, come la famiglia HS* per la firma o l'algoritmo A128KW per la crittografia, richiedono chiavi simmetriche o condivise: la stessa chiave viene utilizzata per la firma e la verifica oppure la stessa chiave viene utilizzata per la crittografia e la decrittografia. Gli algoritmi asimmetrici, come gli algoritmi RS*, PS* ed ES* per la firma, o gli algoritmi ECDH* per la crittografia, utilizzano coppie di chiavi: una chiave pubblica e una chiave privata vengono abbinate. Durante la firma, il firmatario utilizza la chiave privata per firmare e chiunque può utilizzare la chiave pubblica per verificare la firma. Durante la crittografia, l'utilità di crittografia utilizza la chiave pubblica per eseguire la crittografia e l'utilità di decrittografia utilizza la chiave privata per la decriptazione. Le chiavi pubbliche, come suggerito dal nome, sono condivisibili pubblicamente e non devono essere tenute segrete.

Esistono diversi modi per serializzare le chiavi di crittografia in formato testo. I criteri di Apigee accettano chiavi serializzate in varie forme: con codifica PEM, modulo JWKS o, per chiavi condivise, con codifica UTF-8 o Base64.

Formato PEM

Per le chiavi pubbliche o private, viene comunemente utilizzato la codifica PEM, definita nel documento IETF RFC 7468. Ecco un esempio di chiave privata rappresentata in formato PEM:

-----BEGIN PRIVATE KEY-----
MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf
jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK
H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ
-----END PRIVATE KEY-----

Esistono formati PEM simili per le chiavi pubbliche o per le chiavi private criptate.

Formato JWKS

Una chiave web JSON (JWK) è una struttura di dati JSON che rappresenta una singola chiave di crittografia. Un set di chiavi web JSON (JWKS) è una struttura JSON che rappresenta un set di JWK. JWK e JWKS sono descritti in RFC7517. Consulta gli esempi di JWKS in Appendice A. Esempi di insiemi di chiavi web JSON di esempio.

JWKS ha lo scopo di consentire a chiunque di rappresentare un set di chiavi in un formato standard. Un caso d'uso delle chiavi è la condivisione standard delle chiavi pubbliche, tramite un endpoint HTTP che fornisce dati in formato JWKS. Quando un'azienda o un sistema che genera JWS o JWT firmato, ad esempio un provider di identità, pubblica le proprie chiavi pubbliche, qualsiasi sistema o applicazione in grado di leggere le chiavi pubbliche può verificare le firme generate dalla parte che ha firmato. Al contrario, qualsiasi sistema o app che voglia criptare dati che dovrebbero essere letti solo da una determinata parte o società può recuperare le chiavi pubbliche appartenenti a quella parte o azienda e generare un JWT criptato a questo scopo.

RFC7517 descrive gli elementi chiave JWKS per ogni tipo di chiave, ad esempio RSA o EC. Questi elementi devono essere sempre presenti:

• kty: il tipo di chiave, ad esempio RSA o EC.
• kid: l'ID della chiave. Può trattarsi di qualsiasi valore di stringa univoco arbitrario; non devono esserci duplicati all'interno di un singolo set di chiavi. Se il JWT in entrata ha un ID chiave presente nel set di JWKS, il criterio VerificationJWS o VerificationJWT utilizzerà la chiave pubblica corretta per verificare la firma JWS/JWT.

Di seguito sono riportati alcuni esempi di elementi facoltativi e i relativi valori:

• alg: l'algoritmo chiave. Deve corrispondere all'algoritmo di firma nel JWS/JWT.
• use: l'uso previsto della chiave. I valori tipici sono "sig" per la firma e la verifica o "enc" per la crittografia e la decrittografia.

Il seguente JWKS (precedentemente recuperato da https://www.googleapis.com/oauth2/v3/certs, ma ora non aggiornato) include gli elementi e i valori richiesti e sarebbe utilizzabile da Apigee:

{
     "keys":[
        {
           "kty":"RSA",
           "alg":"RS256",
           "use":"sig",
           "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
           "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
           "e":"AQAB"
        },
        {
            "kty":"EC",
            "alg":"ES256",
            "use":"enc",
            "kid":"k05TUSt7-V7KDjCq0_N"
            "crv":"P-256",
            "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
            "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
        }
     ]
  }
  

Specifica delle chiavi per i criteri JWS e JWT

A prescindere dal fatto che tu stia generando o verificando JWS o JWT, devi fornire una chiave da utilizzare nell'ambito delle operazioni crittografiche.

Quando generi un JWT firmato, devi fornire una chiave in grado di produrre la firma.

• Nel caso di un algoritmo di firma RS*, PS* o ES*, che utilizza tutti chiavi asimmetriche, devi fornire la chiave privata per generare la firma.
• Nel caso di un algoritmo HS*, devi fornire la chiave simmetrica che verrà utilizzata durante la generazione della firma.

Quando verifichi un JWS/JWT firmato, devi fornire una chiave in grado di verificare la firma.

• Nel caso di un algoritmo di firma RS*, PS* o ES*, devi fornire la chiave pubblica associata alla chiave privata originariamente utilizzata per firmare il token.
• Nel caso di un algoritmo HS*, devi fornire la stessa chiave simmetrica utilizzata per firmare il JWS o JWT.

Per fornire le chiavi ai criteri JWS e JWT hai due opzioni:

• Fornisci direttamente il valore chiave (di solito tramite una variabile di contesto) oppure
• Fornisci la chiave indirettamente tramite un kid e un JWKS. Puoi specificare il JWKS direttamente o indirettamente tramite un URL http da cui Apigee può recuperare il JWKS.

L'opzione URL JWKS viene generalmente utilizzata solo come origine di chiavi pubbliche utilizzabili con algoritmi asimmetrici, poiché gli URL JWKS sono generalmente pubblici.

I seguenti esempi illustrano come fornire le chiavi direttamente in vari scenari.

• Genera un JWT firmato con l'algoritmo HS256. La chiave richiesta in questo caso è una chiave simmetrica. Questo criterio fornisce una variabile di contesto contenente la chiave segreta codificata in base64url.

  <GenerateJWT name='gen-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
      <Id ref='variable-containing-desired-keyid'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </GenerateJWT>

• Verifica un JWT firmato con l'algoritmo HS256. La chiave richiesta in questo caso è una chiave simmetrica. Come nell'esempio precedente, questo criterio fornisce una variabile di contesto contenente la chiave secret codificata in base64url.

  <VerifyJWT name='verify-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </VerifyJWT>

• Verifica un JWT firmato con l'algoritmo PS256. La chiave richiesta in questo caso è una chiave RSA pubblica. Questo criterio fornisce una variabile di contesto contenente la chiave pubblica con codifica PEM.

  <VerifyJWT name='JWT-001'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <Value ref='variable-containing-pem-encoded-public-key'/>
    </PublicKey>
    . . .
  </VerifyJWT>

• Genera un JWT firmato con l'algoritmo PS256. La chiave richiesta in questo caso è una chiave RSA privata. Questo criterio fornisce una variabile di contesto contenente la chiave privata con codifica PEM.

  <GenerateJWT name='JWT-002'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
      <Value ref='private.variable-containing-pem-encoded-private-key'/>
    </PrivateKey>
     . . .
  </GenerateJWT>

JWKS come origine chiave durante la verifica di un JWS o di un JWT firmato

Quando un sistema o un'app genera un codice JWS/JWT, in genere l'app o il sistema inserisce un identificatore di chiave (l'attestazione kid) nell'intestazione JWS/JWT. La chiave indica a qualsiasi lettore di JWS/JWT quale chiave è necessaria per verificare la firma sul JWS/JWT firmato o decriptare il JWT criptato.

Supponiamo, ad esempio, che un emittente firma un JWT con una chiave privata. "ID chiave" identifica la chiave pubblica corrispondente che deve essere utilizzata per verificare il JWT. L'elenco delle chiavi pubbliche è in genere disponibile su alcuni endpoint noti, come l'endpoint di Google Identity o l'endpoint di Firebase Authentication. Gli altri provider avranno i propri endpoint pubblici che pubblicano chiavi in formato JWKS.

Quando utilizzi Apigee per verificare un JWS o un JWT firmato con chiavi pubbliche condivise tramite un endpoint JWKS, hai alcune opzioni:

• Opzione 1: nella configurazione del criterio, specifica l'URI dell'endpoint JWKS nell'elemento <PublicKey/JWKS>. Ad esempio, per il criterio VerificationJWT:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS uri="https://www.googleapis.com/oauth2/v3/certs"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  In questo caso, Apigee:

  1. Esamina l'intestazione JWS/JWT per trovare l'algoritmo di firma (alg), ad esempio RS256, e rifiuta il JWT in entrata se non corrisponde a quello configurato nel criterio.
  2. Recupera l'elenco di chiavi con i relativi ID dall'endpoint JWKS specificato o da una cache interna se questo endpoint JWKS è stato utilizzato in precedenza.
  3. Esamina l'intestazione JWS/JWT per trovare l'ID chiave (bambino). Se il JWT in entrata non include un ID chiave (bambino) nell'intestazione, la mappatura del bambino alla chiave di verifica non è possibile e Apigee restituirà un errore.
  4. Estrazione dal JWKS, ovvero il JWK con l'ID chiave indicato nell'intestazione JWS/JWT. Genera un errore se non è presente una chiave con quell'ID chiave.
  5. Verifica che l'algoritmo per JWK corrisponda a quello specificato nella configurazione dei criteri. Rifiutare la verifica e generare un errore se gli algoritmi non corrispondono.
  6. Utilizza questa chiave pubblica per verificare la firma sul JWS/JWT. Rifiutare la verifica e generare un errore se la firma non viene verificata.

• Opzione 2: nella configurazione del criterio, specifica una variabile contenente l'URI dell'endpoint JWKS nell'elemento <PublicKey/JWKS>.

  Ad esempio, per il criterio VerificationJWT:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS uriRef="variable-containing-a-uri"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  In questo caso, Apigee eseguirà gli stessi passaggi di cui sopra, ad eccezione del fatto che Apigee recupererà il JWKS non da un URI hardcoded, ma dall'URI specificato nella variabile indicata dall'attributo uriRef. La memorizzazione nella cache continua a essere applicata.

  Nota: presta attenzione quando utilizzi l'attributo uriRef. In qualità di designer del proxy, hai la responsabilità di assicurarti di non configurare i criteri di verifica in modo da considerare attendibili gli URI non verificati. Ad esempio, sarebbe una pratica non sicura se dovessi decodificare il JWS o JWT in entrata, recuperare un URI JWKS dall'intestazione e quindi verificare il JWS o il JWT da tale URI, senza prima verificare che l'URI sia in un elenco attendibile.

• Opzione 3: nella configurazione del criterio, specifica una variabile contenente i dati JWKS hardcoded nell'elemento <PublicKey/JWKS>.

  Ad esempio, per il criterio VerificationJWT:

  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS ref="variable-that-holds-a-jwks"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  

  In questo caso, Apigee eseguirà gli stessi passaggi di cui sopra, ad eccezione del fatto che Apigee recupererà il JWKS non da un URI, ma dalla variabile di contesto specificata nell'attributo ref. In genere, questa variabile di contesto viene caricata da un file callout di servizio, da un KVM o da un file delle proprietà associato al proxy.

  Nota: se utilizzi un ServiceCallout per recuperare il JWKS, è buona norma memorizzarlo nella cache per evitare di eseguirlo su ogni richiesta.

JWKS come origine chiave durante la generazione di un JWT criptato

Quando generi un JWT criptato tramite un algoritmo asimmetrico (RSA-OAEP-256 o una qualsiasi delle varianti ECDH-*), utilizzi la chiave pubblica per eseguire la crittografia. Hai a disposizione delle opzioni per fornire la chiave del criterio GeneraJWT

Un approccio tipico è specificare nella configurazione dei criteri l'URI dell'endpoint JWKS nell'elemento <PublicKey/JWKS>. Ad esempio:

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uri='https://www.example.com/.well-known/jwks.json'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
    . . .
</GenerateJWT>

In questo caso, Apigee:

1. Assembla il payload non codificato e l'intestazione per il JWT in base alla configurazione dei criteri.
2. Recupera l'elenco di chiavi con i relativi ID dall'endpoint JWKS specificato o da una cache interna se questo endpoint JWKS è già stato utilizzato. Attualmente il TTL della cache è di 5 minuti.
3. Estrai il JWK con l'ID chiave indicato nell'elemento PublicKey/Id dal JWKS. Genera un errore se non è presente una chiave con quell'ID chiave.
4. Verifica che l'algoritmo per JWK corrisponda a quello specificato nella configurazione dei criteri. Genera un errore se gli algoritmi non corrispondono.
5. Genera una sequenza casuale da utilizzare come chiave di crittografia dei contenuti.
6. Utilizza la chiave pubblica selezionata per criptare la chiave di crittografia dei contenuti.
7. Utilizza la chiave di crittografia dei contenuti per criptare il payload.
8. Infine, assembla tutte le parti in un JWT criptato serializzato.

In alternativa, utilizza l'attributo uriRef per specificare una variabile che contenga l'URI di un endpoint JWKS. Ad esempio:

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uriRef='variable-containing-jwks-uri'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
  . . .
</GenerateJWT>

In questo caso, Apigee eseguirà gli stessi passaggi di cui sopra, ad eccezione del fatto che Apigee recupererà il JWKS dall'URI specificato nella variabile a cui fa riferimento l'attributo uriRef, anziché un URI hardcoded. Apigee leggerà il JWKS da una cache interna se questo endpoint JWKS è stato utilizzato in precedenza.