Panoramica dei criteri JWS e JWT

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

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 rivendicazioni o asserzioni tra applicazioni connesse. I criteri JWS/JWT consentono ai proxy dell'API Edge di:

  • Genera un JWT o JWS firmato.
  • Verifica un JWT o un JWS firmato e le rivendicazioni all'interno di un JWS/JWT.
  • Decodifica un JWT o JWS firmato senza convalidare la firma.

Negli ultimi due casi, il criterio imposta anche variabili che consentono ai criteri aggiuntivi, o ai servizi di backend stessi, di esaminare le attestazioni convalidate e prendere decisioni in base a queste affermazioni.

Quando utilizzi il criterio Verifica JWS/JWT, un JWS/JWT non valido viene rifiutato e genera una condizione di errore. Analogamente, quando utilizzi il criterio di decodifica JWS/JWT, un formato JWS/JWT non corretto genera una condizione di errore.

Video

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

Un 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 Edge. 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 richiesta di destinazione e lo colleghi alla richiesta inviata alla destinazione. Queste attestazioni saranno 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 client in entrata, dalle risposte di servizio di destinazione, dalle risposte delle norme sui callout di servizio o da altre origini. Edge verificherà la firma su un JWS/JWT, se quest'ultimo è stato generato da una terza parte o da Edge stesso, utilizzando algoritmi RSA o HMAC.
  • Decodifica un file JWS/JWT. La decodifica è utile soprattutto se utilizzata insieme al criterio Verifica JWS/JWT, quando è necessario conoscere il valore di un'attestazione (JWT) o di un'intestazione (JWS/JWT) all'interno di JWS/JWT prima di verificare il JWS/JWT.

Parti di un JWS/JWT

Un JWS/JWT firmato codifica le informazioni in tre parti separate da punti: intestazione, payload e firma:

header.payload.signature
  • Il criterio Genera JWS/JWT crea tutte e tre le parti.
  • Il criterio di verifica JWS/JWT esamina tutte e tre le parti.
  • Il criterio di decodifica JWS/JWT esamina solo l'intestazione e il payload.

Un JWS supporta anche un formato 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 Verification JWS per specificare il payload JWS non elaborato e non codificato. Il criterio Verification JWS verifica quindi il JWS utilizzando l'intestazione e la firma nel JWS e nel payload specificato dall'elemento <DetachedContent>.

Per saperne di più sui token e su come vengono codificati e firmati, consulta:

Differenze tra JWS e JWT

Puoi utilizzare un JWT o un JWS per condividere rivendicazioni o asserzioni tra applicazioni collegate. La differenza principale 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
  • 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

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

Oltre a supportare determinati nomi di attestazioni registrate, il criterio per la generazione di JWT supporta direttamente l'aggiunta di rivendicazioni con nomi arbitrari al JWT. Ogni attestazione è una semplice coppia nome/valore in cui il valore può essere di tipo numero, booleano, stringa, mappa o array.

Poiché un JWS può utilizzare qualsiasi rappresentazione di dati per il payload, non puoi aggiungere attestazioni al payload. Il criterio Genera JWS supporta l'aggiunta di attestazioni con nomi arbitrari all'intestazione del JWS. Inoltre, i criteri JWS supportano un payload scollegato, in cui il JWS omette il payload. Un payload scollegato consente di inviare JWS e payload separatamente ed è richiesto da diversi standard di sicurezza.

Informazioni sugli algoritmi di firma

I criteri JWS/JWT Verification e JWS/JWT di generazione supportano gli algoritmi RSA, RSASSA-PSS, ECDSA e HMAC utilizzando checksum SHA2 con intensità di bit 256, 384 o 512. Il criterio di decodifica JWS/JWT funziona a prescindere dall'algoritmo utilizzato per firmare i file JWS/JWT.

Algoritmo HMAC

L'algoritmo HMAC si basa su un secret condiviso, noto come chiave segreta, per creare la firma (nota anche come firma JWS/JWT) e per verificare la firma.

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

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

algoritmo RSA

L'algoritmo RSA utilizza una coppia di chiavi pubblica/privata per la firma crittografica. 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 dimensioni per le chiavi.

Algoritmo RSASSA-PSS

L'algoritmo RSASSA-PSS è un aggiornamento dell'algoritmo RSA. Come RSS, RSASSA-PSS utilizza una coppia di chiavi pubblica/privata RSA per la firma crittografica. Il formato della chiave è lo stesso dell'RSS. La parte che sottoscrive la firma utilizza una chiave privata per firmare il JWS/JWT, mentre la parte verificante usa la chiave pubblica corrispondente per verificare la firma sul JWS/JWT. Non ci sono requisiti di dimensione per le chiavi.

Algoritmo ECDSA

L'algoritmo Elliptic Curve Digital Signature Algorithm (ECDSA) è un algoritmo di crittografia a curva ellittica con una curva P-256, P-384 e P-521. Quando utilizzi gli 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 delle chiavi

I criteri JWS/JWT supportano tutti gli algoritmi di crittografia delle chiavi supportati da OpenSSL.

Utilizzo di un set di chiavi web JSON (JWKS) per verificare un oggetto JWS/JWT

Quando verifichi un JWS/JWT firmato, devi fornire la chiave pubblica associata alla chiave privata utilizzata per firmare il token. Hai due opzioni per fornire la chiave pubblica per i criteri di verifica JWS/JWT:

  • utilizzano l'effettivo valore della chiave pubblica (in genere fornito in una variabile di flusso) oppure
  • una chiave pubblica con wrapping in un JWKS.

Informazioni su JWKS

Un JWKS è una struttura JSON che rappresenta un set di chiavi web JSON (JWK). Un JWK è una struttura di dati JSON che rappresenta una chiave di crittografia. JWK e JWKS sono descritti in RFC7517. Vedi gli esempi di JKWS nell'Appendice A. Esempi di set di chiavi web JSON

Struttura JWKS

RFC7517 descrive gli elementi chiave JWKS per ciascun tipo di chiave, ad esempio "RSA" o "EC". Ad esempio, a seconda del tipo di chiave, questi parametri possono includere:

  • kty: il tipo di chiave, ad esempio "RSA" o "EC".
  • kid (ID chiave): può essere qualsiasi valore arbitrario (non sono presenti duplicati all'interno di un set di chiavi). Se il JWT in entrata ha un ID chiave presente nel set di JWKS, il criterio 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 nel JWS/JWT.
  • use: se presente, deve essere sig.

Il seguente JWKS include gli elementi e i valori richiesti e sarebbe valido su Edge (da https://www.googleapis.com/oauth2/v3/certs):

{  
   "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",
      }
   ]
}

Progettazione del proxy per l'utilizzo di JWKS

Quando un JWS/JWT viene ottenuto da un emittente, spesso quest'ultimo inserisce un ID chiave (o bambino) nell'intestazione JWS/JWT. La chiave indica al destinatario del JWS/JWT come trovare la chiave pubblica o segreta necessaria per verificare la firma sul JWS/JWT firmato.

Supponiamo, ad esempio, che un emittente firmi un JWT con una chiave privata. "ID chiave" identifica la chiave pubblica corrispondente da utilizzare per verificare il JWT. L'elenco di chiavi pubbliche è in genere disponibile presso alcuni endpoint molto noti, ad esempio: https://www.googleapis.com/oauth2/v3/certs.

Questa è la sequenza di base che Edge (o qualsiasi piattaforma che funziona con JWKS) deve eseguire per lavorare con un JWS/JWT che abbia un JWKS:

  1. Esamina l'intestazione JWS/JWT per trovare l'ID chiave (kid).
  2. Esamina l'intestazione JWS/JWT per trovare l'algoritmo di firma (alg), ad esempio RS256.
  3. Recupera l'elenco di chiavi e ID dal JWKS dell'endpoint noto di un determinato emittente.
  4. Estrai la chiave pubblica dall'elenco delle chiavi con l'ID chiave indicato nell'intestazione JWS/JWT e con l'algoritmo di corrispondenza, se la chiave JWKS specifica l'algoritmo.
  5. Utilizza la chiave pubblica per verificare la firma sul JWS/JWT.

In qualità di sviluppatore di proxy API Edge, devi svolgere le seguenti operazioni per eseguire la verifica JWS/JWT:

  1. Recupera l'elenco di chiavi e ID dall'endpoint noto di un determinato emittente. Per questo passaggio puoi utilizzare una norma sui callout di servizio.
  2. Nel criterio Verifica JWS/JWT, specifica la località di JWS/JWT nell'elemento <Source> e il payload 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 ref="public.jwks"/>
    </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>

Il criterio di verifica JWT fa tutto il resto:

  • Se una chiave con un ID chiave corrispondente all'ID chiave (kid) dichiarato nel JWT non viene trovata nel JWKS, il criterio JWT di verifica genera un errore e non convalida il JWT.
  • Se il JWT in entrata non ha un ID chiave (kid) nell'intestazione, questo mapping di keyid-to-verification-key non è possibile.

In qualità di designer proxy, sei responsabile di determinare la chiave da utilizzare; in alcuni casi, può essere una chiave fissa e hardcoded.