Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
Questo argomento fornisce informazioni generali su JWT (JSON Web Token) e JWS (JSON Web Signature) e sui criteri di Apigee JWS/JWT che potrebbero interessare gli sviluppatori di proxy Apigee.
Introduzione
Sia JWS che JWT sono comunemente utilizzati per condividere rivendicazioni o asserzioni tra applicazioni collegate. I criteri JWS/JWT consentono ai proxy API Apigee di:
- Genera un JWT firmato, un JWS o un JWT criptato.
- Verifica un JWT o un JWS firmato o un JWT criptato e verifica le attestazioni selezionate all'interno del JWS/JWT.
- Decodifica un JWT o un JWS firmato o criptato senza convalidare la firma o decriptare il JWT o 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. In questo modo, i criteri successivi nel flusso Apigee possono esaminare le attestazioni nel JWT o JWS e prendere decisioni in base a queste dichiarazioni o di propagare le informazioni ai servizi di backend.
Quando utilizzi i criteri VerifyJWS o VerifyJWT, i valori JWS/JWT non validi vengono rifiutati e produrranno una condizione di errore. Analogamente, quando utilizzi i criteri DecodeJWS o DecodeJWT, un formato JWS/JWT in un formato 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 gli stessi per JWS.
Un 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 lato del proxy o dell'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 richieste di destinazione e lo colleghi alla richiesta inviata alla destinazione. I JWS/JWT e le relative attestazioni saranno quindi disponibili per consentire ai servizi di backend di applicare ulteriori elaborazioni di sicurezza.
- Verifica ed estrai le attestazioni da un JWS/JWT ottenuto da richieste del client in entrata, da risposte del servizio di destinazione, da risposte ai criteri di callout del servizio o da altre origini. Per un modello JWS/JWT firmato, Apigee utilizzerà uno degli algoritmi RSA, ECDSA o HMAC per verificare la firma, sia 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 è utile soprattutto se utilizzata insieme al criterio Verify JWS/JWT (Verifica JWS/JWT) nei casi in cui il valore di una dichiarazione (JWT) o di un'intestazione (JWS/JWT) all'interno del JWS/JWT sia 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 dal JWS:
Header..Signature
Con un JWS scollegato, il payload viene inviato separatamente dal JWS. Puoi utilizzare l'elemento <DetachedContent> del criterio di verifica JWS per specificare il payload JWS non elaborato e non codificato.
Il criterio Verifica JWS verifica quindi il JWS utilizzando l'intestazione e la firma al suo interno 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 CreateJWT e VerifyJWT creeranno o esamineranno tutte queste parti. DecodeJWT può esaminare solo l'intestazione non criptata.
Per ulteriori informazioni sui token e su come vengono codificati, firmati o criptati, consulta i documenti degli 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 le 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
typdel token è sempre impostata suJWT. - 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 al 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 CreateJWT e VerifyJWT hanno integrato il supporto per gestire i nomi di attestazioni registrate comuni, come aud, iss, sub e altri. Ciò significa che puoi utilizzare elementi del criterioGenerateJWT per impostare queste attestazioni nel payload, nonché elementi del criterio VerifyJWT per verificarne i valori. Per ulteriori informazioni, consulta la sezione Nomi delle attestazioni registrate della specifica JWT.
Oltre a supportare determinati nomi di attestazioni registrate, il criterio CreateJWT supporta direttamente l'aggiunta di attestazioni con nomi arbitrari al payload o all'intestazione del JWT. Ogni dichiarazione è 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 rappresenta il payload. Poiché un JWS può utilizzare qualsiasi rappresentazione dei dati per il payload, non esiste il concetto di "attestazione 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 lo omette. Un payload scollegato ti consente di inviare JWS e payload separatamente. L'utilizzo di un payload scollegato 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 un JWT firmato o criptato. Scegli il JWT firmato quando non è necessario che il payload sia segreto, ma è importante fornire ai lettori garanzie di integrità e non ripudio. Un JWT firmato assicura ai lettori che il payload non sia 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 secret. Un JWT criptato fornisce riservatezza per il payload, poiché solo il proprietario della chiave appropriato può decriptarlo.
È possibile utilizzare JWT criptato e firmato insieme, soprattutto se il JWT criptato utilizza un algoritmo di crittografia asimmetrica (RSA, ECDSA). In questo caso, non è possibile determinare l'identità del producer di quel JWT, perché la chiave di crittografia è pubblica. Per risolvere il problema, combina firma e 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 garantisce la non ripudio e la garanzia di riservatezza. I criteri di Apigee possono produrre, decodificare e verificare queste combinazioni.
Algoritmi di firma
Per il 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 intensità di bit 256, 384 o 512. I criteri DecodeJWS e DecodeJWT funzionano a prescindere dall'algoritmo utilizzato per firmare i JWS/JWT.
Algoritmi HMAC
Gli algoritmi HMAC si basano su un secret condiviso, noto come chiave segreta, per la creazione della firma (nota anche come firma del JWS/JWT) e per la verifica della firma.
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 le sigle 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 verificante utilizza la chiave pubblica RSA corrispondente per verificare la firma sul JWS/JWT. Non sono previsti requisiti di dimensione per le chiavi.
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 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 dell'algoritmo Elliptic Curve Digital Signature (ECDSA) è costituito da algoritmi di crittografia ellittica con una curva P-256, P-384 o P-521. Quando utilizzi algoritmi ECDSA, l'algoritmo determina 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 utilizzi GeneraJWT e VerifyJWT per gestire JWT criptato, 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 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 alla base di 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 decriptazione. Gli algoritmi asimmetrici, come gli algoritmi RS*, PS* ed ES* per la firma o gli algoritmi ECDH* per la crittografia, utilizzano coppie di chiavi: esistono una chiave pubblica e una chiave privata e entrambe sono abbinate. Durante la firma, il firmatario utilizza la chiave privata per la firma e qualsiasi parte può utilizzare la chiave pubblica per verificare la firma. Durante la crittografia, l'utente utilizza la chiave pubblica per la crittografia, mentre l'autore della decriptazione utilizza la chiave privata per la decriptazione. 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 testo. I criteri di Apigee accettano chiavi serializzate in varie forme: con codifica PEM, JWKS o, per le chiavi condivise, 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 per chiavi private criptate.
Formato JWKS
Una chiave web JSON (JWK) è una struttura di dati JSON che rappresenta una singola chiave di crittografia. Un JSON Web Key Set (JWKS) è una struttura JSON che rappresenta un insieme di JWK. JWK e JWKS sono descritti in RFC7517. Vedi esempi di JWKS nell'Appendice A. Set di chiavi web JSON di esempio.
JWKS è pensato per consentire a qualsiasi parte di rappresentare un set di chiavi in un formato standard. Un caso d'uso chiave è la condivisione delle chiavi pubbliche in modo standard, tramite un endpoint HTTP che fornisce i dati in formato JWKS. Quando un'azienda o un sistema che genera JWS o JWT firmati, 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 coinvolta. Al contrario, qualsiasi sistema o app che voglia criptare dati che devono essere letti solo da una determinata parte o azienda 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 ciascun tipo di chiave, ad esempio RSA o EC. Questi elementi
devono essere sempre presenti:
- kty - Il tipo di chiave, ad esempio
RSAoEC. - kid: l'ID chiave. Può essere qualsiasi valore di stringa univoco arbitrario; non dovrebbero 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 VerifyJWS o VerifyJWT utilizzerà la chiave pubblica corretta per verificare la firma JWS/JWT.
Di seguito sono riportati alcuni esempi di elementi facoltativi e dei relativi valori:
- alg: l'algoritmo chiave. Deve corrispondere all'algoritmo di firma in 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 decriptazione.
Il seguente JWKS (originariamente recuperato da https://www.googleapis.com/oauth2/v3/certs, ma ora non aggiornato) include gli elementi e i valori richiesti e potrebbe essere utilizzato 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
Che tu stia generando o verificando JWS o JWT, devi fornire una chiave da utilizzare all'interno delle operazioni crittografiche.
Quando generi un JWT firmato, devi fornire una chiave in grado di riprodurre la firma.
- Nel caso di un algoritmo di firma RS*, PS* o ES* che utilizza 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 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 utilizzata originariamente 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 chiave (in genere tramite una variabile di contesto) oppure
- Fornisci la chiave indirettamente, tramite
kide JWKS. Puoi specificare il JWKS direttamente o indirettamente tramite un URL http da cui Apigee può recuperare il JWKS.
L'opzione URL JWKS viene in genere utilizzata solo come fonte di chiavi pubbliche utilizzabili con algoritmi asimmetrici, poiché gli URL JWKS sono generalmente pubblici.
I seguenti esempi illustrano alcuni modi per 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 secret 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 che contiene la chiave secret con codifica 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 che è stato firmato con l'algoritmo PS256. In questo caso, la chiave richiesta è una chiave RSA pubblica. Questo criterio fornisce una variabile di contesto che contiene 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> -
Generare un JWT firmato con l'algoritmo PS256. In questo caso, la chiave richiesta è 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 della chiave durante la verifica di un JWS o di un JWT firmato
Quando un sistema o un'app genera un JWS/JWT, in genere inserisce un identificatore
chiave (la dichiarazione kid) nell'intestazione JWS/JWT. La chiave comunica a qualsiasi lettore di JWS/JWT quale chiave è necessaria per verificare la firma nel JWS/JWT firmato o per decriptare il JWT criptato.
Ad esempio, supponiamo che un emittente firmi un JWT con una chiave privata. "Key ID" (ID chiave) identifica la chiave pubblica corrispondente da utilizzare 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. Altri provider 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 a disposizione 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:
- 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.
- Recupera l'elenco delle chiavi con i relativi ID dall'endpoint JWKS specificato o da una cache interna se questo endpoint JWKS è già stato utilizzato.
- Esamina l'intestazione JWS/JWT per trovare l'ID chiave (bambino). Se il JWT in entrata non include un ID chiave (kid) nell'intestazione, significa che la mappatura del bambino alla chiave di verifica non è possibile e Apigee genera un errore.
- Estrai il codice 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.
- Verifica che l'algoritmo per il JWK corrisponda a quello specificato nella configurazione del criterio. Rifiuta la verifica e genera un errore se gli algoritmi non corrispondono.
- e utilizzala per verificare la firma nel file JWS/JWT. Rifiuta la verifica e genera un errore se la firma non viene verificata.
Opzione 2: nella configurazione dei criteri, 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 in precedenza, tranne per il fatto che Apigee recupererà i JWKS non da un URI hardcoded, ma dall'URI specificato nella variabile a cui fa riferimento l'attributo
uriRef. La memorizzazione nella cache continua a essere applicata.Opzione 3: nella configurazione dei criteri, specifica una variabile che contenga i dati JWKS hardcoded 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 di cui sopra, con la differenza che Apigee 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, una KVM o un file delle proprietà associato al proxy.
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 variante ECDH-*), utilizzi la chiave pubblica per la crittografia. Puoi scegliere di fornire la chiave per il criterioGenerateJWT
Un approccio tipico consiste nello 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:
- Assembla il payload non codificato e l'intestazione per il JWT in base alla configurazione del criterio.
- Recupera l'elenco delle 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.
- Estrai il JWK con l'ID chiave indicato nell'elemento
PublicKey/Iddal JWKS. Genera un errore se non è presente una chiave con quell'ID chiave. - Verifica che l'algoritmo per il JWK corrisponda a quello specificato nella configurazione del criterio. Genera un errore se gli algoritmi non corrispondono.
- Genera una sequenza casuale da utilizzare come chiave di crittografia dei contenuti.
- Usa la chiave pubblica selezionata per criptare la chiave di crittografia dei contenuti.
- Utilizza la chiave di crittografia dei contenuti per criptare il payload.
- Infine, assembla tutte le parti in un JWT criptato serializzato.
In alternativa, puoi 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 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 è già stato utilizzato.