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 vengono comunemente utilizzati per condividere rivendicazioni o asserzioni tra applicazioni connesse. I criteri JWS/JWT consentono ai proxy API Apigee di:

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

Quando utilizzi i criteri VerifyJWS o VerifyJWT, un JWS/JWT non valido verrà rifiutato e verrà generata una condizione di errore. Allo stesso modo, quando si utilizzano i criteri DecodeJWS o DecodeJWT, un JWS/JWT non valido 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 dei concetti sono gli stessi per JWS.

Guarda questo breve video per scoprire di più sulla struttura JWT.

Casi d'uso

Puoi utilizzare i criteri JWS/JWT per:

  • Genera un nuovo JWS/JWT sul proxy o sugli endpoint di destinazione di un proxy Apigee. Ad esempio, puoi creare un flusso di richieste 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 richieste di destinazione e lo alleghi alla richiesta inviata alla destinazione. Il JWS/JWT e le relative rivendicazioni sarebbero quindi disponibili per consentire ai servizi di backend di applicare un'ulteriore elaborazione della sicurezza.
  • Verifica ed estrai le rivendicazioni da un JWS/JWT ottenuto da richieste client in entrata, da risposte di servizi di destinazione, da risposte di criteri di callout del servizio o da altre fonti. 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 (vedi IETF RFC 7518).
  • Decodifica un JWS/JWT. La decodifica è più utile se utilizzata in combinazione con il 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 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
  • La policy Genera JWS/JWT crea tutte e tre le parti.
  • Il criterio Verifica JWS/JWT esamina tutte e tre le parti.
  • La policy DecodeJWS esamina solo l'intestazione. La policy DecodeJWT esamina solo l'intestazione e il payload.

Una JWS supporta anche un formato separato che omette il payload dalla JWS:

Header..Signature

Con una firma JWS separata, il payload viene inviato separatamente dalla firma JWS. Utilizzi l'elemento <DetachedContent> del criterio Verifica JWS per specificare il payload JWS non codificato non elaborato. Il criterio Verifica JWS verifica quindi la JWS utilizzando l'intestazione e la firma nella 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

Le norme GenerateJWT e VerifyJWT creeranno o esamineranno 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:

Differenze tra JWS e JWT

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

  • JWT
    • Il payload è sempre un oggetto JSON.
    • Il payload è sempre allegato 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 allegato alla firma 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, le norme GenerateJWT e VerifyJWT di Apigee supportano la gestione dei nomi delle rivendicazioni registrate comuni, come aud, iss, sub e altri. Ciò significa che puoi utilizzare gli elementi del criterio GenerateJWT per impostare queste rivendicazioni nel payload e gli elementi del criterio VerifyJWT per verificarne i valori. Per saperne di più, consulta la sezione Nomi delle rivendicazioni registrate delle specifiche JWT.

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

Quando utilizzi GenerateJWS, fornisci una variabile di contesto che rappresenta 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 GenerateJWS non supporta l'aggiunta di rivendicazioni con nomi arbitrari al payload. È possibile utilizzare il criterio GenerateJWS per aggiungere attestazioni con nomi arbitrari all'intestazione del JWS. Inoltre, le policy JWS supportano un payload separato, in cui JWS omette il payload. Un payload separato consente di inviare la firma JWS e il payload separatamente. L'utilizzo di un payload separato può essere più efficiente in termini di spazio, soprattutto per i payload di grandi dimensioni, ed è richiesto da diversi standard di sicurezza.

Firma e crittografia

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

È possibile utilizzare insieme JWT criptati e firmati, soprattutto quando il JWT criptato utilizza un algoritmo di crittografia asimmetrica (RSA, ECDSA). In questo caso, l'identità del produttore del JWT non può essere determinata perché la chiave di crittografia è pubblica. Per risolvere il problema, combina la firma con la crittografia. Un pattern 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 all'interno di un JWT criptato utilizzando questo approccio fornisce sia la garanzia di non ripudio sia quella di riservatezza. Le norme Apigee possono produrre e decodificare e verificare queste combinazioni.

Algoritmi di firma

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

Algoritmi HMAC

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

La lunghezza minima della chiave segreta dipende dalla forza 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 verifica utilizza la chiave pubblica RSA corrispondente per verificare la firma sul JWS/JWT. Non esistono requisiti di dimensione per le chiavi.

Algoritmi RSASSA-PSS

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

Algoritmi ECDSA

Il set di algoritmi Elliptic Curve Digital Signature Algorithm (ECDSA) sono algoritmi di crittografia ellittica con una curva P-256, P-384 o P-521. Quando utilizzi gli algoritmi ECDSA, l'algoritmo determina il tipo di chiave pubblica e privata che devi specificare:

Algoritmo Curve Requisito della 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 utilizzi GenerateJWT e VerifyJWT per gestire JWT criptati, i criteri supportano questi 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 delle chiavi

Gli standard JOSE, che includono JWS, JWT firmati e criptati e altro ancora, descrivono come utilizzare chiavi di crittografia per firmare o criptare le informazioni. Gli elementi fondamentali per qualsiasi operazione crittografica includono l'algoritmo e la chiave. Algoritmi diversi richiedono tipi di chiavi diversi e, in alcuni casi, dimensioni delle chiavi 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 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: esiste una chiave pubblica e una chiave privata e sono corrispondenti. Nella firma, il firmatario utilizza la chiave privata per firmare e qualsiasi parte può utilizzare la chiave pubblica per verificare la firma. Nella crittografia, il programma di crittografia utilizza la chiave pubblica per criptare, mentre il programma di decrittografia utilizza la chiave privata per decriptare. Le chiavi pubbliche, come suggerisce il nome, sono condivisibili pubblicamente e non devono essere tenute segrete.

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

Formato PEM

Per le chiavi pubbliche o private, è comune utilizzare la codifica PEM, definita in 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 le chiavi private criptate.

Formato JWKS

Una JSON Web Key (JWK) è una struttura di dati JSON che rappresenta una singola chiave crittografica. Un insieme di chiavi web JSON (JWKS) è una struttura JSON che rappresenta un insieme di JWK. JWK e JWKS sono descritti nella RFC7517. Vedi gli esempi di JWKS nell'appendice A. Esempio di set di chiavi web JSON.

JWKS ha lo scopo di consentire a qualsiasi parte di rappresentare un insieme di chiavi in un formato standard. Un caso d'uso chiave è la condivisione di chiavi pubbliche in modo standard, tramite un endpoint HTTP che fornisce dati in formato JWKS. Quando un'azienda o un sistema che genera JWS o JWT firmati, ad esempio un Identity Provider, pubblica le proprie chiavi pubbliche, qualsiasi sistema o applicazione in grado di leggere le chiavi pubbliche può verificare le firme generate dalla parte firmataria. Al contrario, qualsiasi sistema o app che vuole criptare i dati che devono essere letti solo da una determinata persona o azienda, può recuperare le chiavi pubbliche appartenenti a quella persona o azienda e generare un JWT criptato a questo scopo.

Il documento 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 chiave. Può essere qualsiasi valore stringa univoco arbitrario; non devono essere presenti duplicati all'interno di un singolo insieme di chiavi. Se il JWT in entrata contiene un ID chiave presente nel set di JWKS, il criterio VerifyJWS o VerifyJWT utilizzerà la chiave pubblica corretta per verificare la firma JWS/JWT.

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

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

Il seguente JWKS (recuperato originariamente da https://www.googleapis.com/oauth2/v3/certs, ma ora obsoleto) 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",
        }
     ]
  }

Specificare le chiavi per i criteri JWS e JWT

Che tu stia generando o verificando JWS o JWT, devi fornire una chiave da utilizzare nelle operazioni di crittografia.

Quando generi un JWT firmato, devi fornire una chiave che possa produrre la firma.

  • Nel caso di un algoritmo di firma RS*, PS* o ES*, che utilizzano 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 per generare la firma.

Quando verifichi un JWS/JWT firmato, devi fornire una chiave che possa 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 il JWT.

Hai due opzioni per fornire le chiavi ai criteri JWS e JWT:

  • Fornisci direttamente il valore della chiave (in genere tramite una variabile di contesto) oppure
  • Fornisci la chiave indirettamente, tramite un kid e un JWKS. Puoi specificare JWKS direttamente o indirettamente tramite un URL HTTP in cui Apigee può recuperare JWKS.

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

I seguenti esempi illustrano i modi in cui puoi 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 che contiene 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, questa norma fornisce una variabile di contesto che contiene la chiave segreta 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 che contiene la chiave pubblica codificata in 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 che contiene 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 delle chiavi durante la verifica di un JWS o di un JWT firmato

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

Ad esempio, supponiamo che un emittente firmi un JWT con una chiave privata. L'"ID chiave" identifica la chiave pubblica corrispondente che deve essere utilizzata per verificare il JWT. L'elenco delle chiavi pubbliche è in genere disponibile in un endpoint noto, ad esempio l'endpoint Google Identity o l'endpoint Firebase Authentication. Altri fornitori avranno i propri endpoint pubblici che pubblicano le 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 dei criteri, specifica l'URI dell'endpoint JWKS nell'elemento <PublicKey/JWKS>. Ad esempio, per il criterio VerifyJWT:

    <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 l'algoritmo non corrisponde a quello configurato nel criterio.
    2. Recupera l'elenco delle 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 (kid). Se il JWT in entrata non include un ID chiave (kid) nell'intestazione, il mapping del kid alla chiave di verifica non è possibile e Apigee genererà un errore.
    4. Estrai da JWKS il JWK con l'ID chiave annotato nell'intestazione JWS/JWT. Genera un errore se non è presente una chiave con questo ID chiave.
    5. Verifica che l'algoritmo per la JWK corrisponda a quello specificato nella configurazione dei criteri. Rifiuta la verifica e genera un errore se gli algoritmi non corrispondono.
    6. Utilizza questa chiave pubblica per verificare la firma sul JWS/JWT. Rifiuta la verifica e genera un errore se la firma non viene verificata.

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

    Ad esempio, per il criterio VerifyJWT:

    <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 descritti sopra, tranne che recupererà il JWKS non da un URI hardcoded, ma dall'URI specificato nella variabile a cui fa riferimento l'attributo uriRef. La memorizzazione nella cache è ancora valida.

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

    Ad esempio, per il criterio VerifyJWT:

    <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 descritti sopra, tranne che recupererà i JWKS non da un URI, ma dalla variabile di contesto specificata nell'attributo ref. In genere, questa variabile di contesto viene caricata da un ServiceCallout, da un KVM o da un file di proprietà associato al proxy.

JWKS come origine delle chiavi durante la generazione di un JWT criptato

Quando generi un JWT criptato tramite un algoritmo asimmetrico (RSA-OAEP-256 o una delle varianti ECDH-*), utilizzi la chiave pubblica per la criptografia. Hai diverse opzioni per fornire la chiave alla policy GenerateJWT

Un approccio tipico consiste nello specificare nell'elemento <PublicKey/JWKS> l'URI dell'endpoint JWKS nella configurazione dei criteri. 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 e l'intestazione non codificati per il JWT in base alla configurazione delle norme.
  2. Recupera l'elenco delle chiavi con i relativi ID dall'endpoint JWKS specificato o da una cache interna se questo endpoint JWKS è stato utilizzato in precedenza. Attualmente il TTL della cache è di 5 minuti.
  3. Estrai la JWK con l'ID chiave indicato nell'elemento PublicKey/Id dalla JWKS. Genera un errore se non è presente una chiave con questo ID chiave.
  4. Verifica che l'algoritmo per la 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.

Un'alternativa è utilizzare l'attributo uriRef per specificare una variabile che contiene 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 descritti sopra, tranne che recupererà il set di chiavi JSON Web Key (JWKS) dall'URI specificato nella variabile a cui fa riferimento l'attributo uriRef, anziché da un URI hardcoded. Apigee leggerà il JWKS da una cache interna se questo endpoint JWKS è già stato utilizzato.