Panoramica dei criteri JWS e JWT

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Questo argomento fornisce informazioni generali sul token JWT (JSON Web Token) e JWS (JSON Web Signature) e i criteri 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 diverse applicazioni. I criteri JWS/JWT consentono ai proxy API Edge di:

  • Genera un JWT firmato o JWS.
  • Verifica un JWT firmato o JWS e le dichiarazioni all'interno del JWS/JWT.
  • Decodificare un JWT firmato o JWS senza convalidare la firma.

Negli ultimi due casi, il criterio imposta anche variabili che consentono altri criteri, oppure il parametro per esaminare le attestazioni convalidate e prendere decisioni in base a queste rivendicazioni.

Quando si utilizza il criterio Verifica JWS/JWT, i valori JWS/JWT non validi vengono rifiutati e comporteranno un errore. . Analogamente, quando utilizzi il criterio Decodifica JWS/JWT, un formato JWS/JWT non corretto comporterà un errore .

Video

Guarda un breve video per una rapida introduzione a JWT. Mentre il video è specifici per la generazione di un JWT, molti dei 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 Edge. Per Ad esempio, potresti creare un flusso di richieste proxy che genera un JWS/JWT e lo restituisce a un client. In alternativa, potresti progettare un proxy in modo che generi un JWS/JWT nel flusso di richieste di destinazione. lo allega alla richiesta inviata alla destinazione. Queste dichiarazioni saranno quindi disponibili per consentire di backend per applicare ulteriori elaborazioni di sicurezza.
  • Verificare ed estrarre le attestazioni da un JWS/JWT ottenuti dalle richieste del client in entrata, dalla destinazione di servizio, dalle risposte ai criteri relativi ai callout del servizio o da altre origini. Edge Verificare la firma su un JWS/JWT, se il JWS/JWT è stato generato da una terza parte o da Edge utilizzando algoritmi RSA o HMAC.
  • Decodifica un JWS/JWT. La decodifica è utile soprattutto se utilizzata insieme al criterio di verifica JWS/JWT, quando il valore di una dichiarazione (JWT) o di un'intestazione (JWS/JWT) dall'interno del JWS/JWT deve essere noto prima della verifica il JWS/JWT.

Parti di un JWS/JWT

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

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 Decode JWS/JWT esamina solo l'intestazione e il payload.

Un JWS supporta anche un formato scollegato che omette il payload dal JWS:

header..signature

Con un JWS scollegato, il payload viene inviato separatamente dal JWS. Puoi utilizzare 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 nel payload specificato dall'elemento <DetachedContent>.

Per ulteriori informazioni 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 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 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 server JWS

Poiché il formato JWT utilizza sempre un oggetto JSON per rappresentare il payload, il comando e Verifica che i criteri JWT includano il supporto integrato per la gestione dei nomi delle attestazioni registrate più comuni, come aud, iss, sub e altre ancora. Ciò significa che puoi utilizzare elementi Genera il criterio JWT per impostare queste attestazioni nel payload e gli elementi del criterio Verifica JWT per verificarne i valori. Consulta la sezione Nomi delle rivendicazioni registrate della specifica JWT per saperne di più.

Oltre a supportare determinati nomi di rivendicazioni registrate, il criterio Genera JWT direttamente supporta l'aggiunta di attestazioni con nomi arbitrari al JWT. Ogni dichiarazione è 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 dei dati per il payload, non è possibile 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 JWS lo omette. Un payload scollegato consente di inviare JWS e payload separatamente ed è richiesto da diversi standard di sicurezza.

Informazioni sugli algoritmi di firma

I criteri di verifica JWS/JWT e di generazione JWS/JWT supportano gli algoritmi RSA, RSASSA-PSS, ECDSA e HMAC, utilizzando SHA2 checksum dell'intensità di bit 256, 384 o 512. Il criterio di decodifica JWS/JWT funziona indipendentemente dalla utilizzato per firmare il JWS/JWT.

Algoritmo HMAC

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

La lunghezza minima della chiave segreta dipende dalla forza 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 RSA firma, la parte che esegue la firma utilizza una chiave RSA privata 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 nella chiave.

Algoritmo RSASSA-PSS

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

Algoritmo ECDSA

L'algoritmo Elliptic Curve Digital Signature Algorithm (ECDSA) è una crittografia 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 dal OpenSSL.

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

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

  • utilizza l'effettivo valore della chiave pubblica (generalmente fornito in una variabile di flusso) oppure
  • una chiave pubblica sottoposta a wrapping in un JWKS.

Informazioni su JWKS

Un JWKS è una struttura JSON che rappresenta un insieme di chiavi web JSON (JWK). Un JWK è un formato di dati JSON di crittografia che rappresenta una chiave di crittografia. JWK e JWKS sono descritti in RFC7517. Vedi esempi JKWS su Appendice A. Set di chiavi web JSON di esempio

Struttura JWKS

RFC7517 descrive gli elementi chiave di JWKS per ogni 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 (l'ID chiave): può essere qualsiasi valore arbitrario (nessun duplicato all'interno di una chiave). impostata). 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 in 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 utilizza JWKS

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

Ad esempio, supponiamo che un emittente firmi un JWT con una chiave privata. L'"ID chiave" identifica chiave pubblica corrispondente da utilizzare per verificare il JWT. L'elenco delle chiavi pubbliche è in genere disponibile all'indirizzo ad esempio: https://www.googleapis.com/oauth2/v3/certs.

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

  1. Esamina l'intestazione JWS/JWT per trovare l'ID chiave (bambino).
  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 per 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. e utilizzala per verificare la firma nel file JWS/JWT.

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

  1. Recupera l'elenco di chiavi e ID dall'endpoint noto di un determinato emittente. Puoi utilizza un criterio relativo ai callout di servizio per questo passaggio.
  2. Nel criterio Verifica JWS/JWT, specifica la posizione di JWS/JWT in <Source> e il payload 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 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 Verifica JWT esegue tutte le altre operazioni:

  • Se una chiave con un ID chiave che corrisponde all'ID chiave (kid) dichiarato nel JWT non viene trovata in JWKS, il criterio Verifica JWT genera un errore e non convalida il JWT.
  • Se il JWT in entrata non porta un ID chiave (kid) nell'intestazione, allora questa mappatura keyid-to-verification-key non è possibile.

In qualità di progettista del proxy, sei responsabile di determinare la chiave da utilizzare. in alcuni casi questo può essere una chiave fissa, hardcoded.