Ispezionare un JWKS ed estrarre le chiavi pubbliche in PEM

Cos'è un JWKS?

Un JWKS (JSON Web Key Set, RFC 7517) è un documento JSON che raggruppa una lista di chiavi pubbliche in forma strutturata. Serve a pubblicare le chiavi che un emettitore di JWT usa per firmare i suoi token, affinché qualsiasi consumatore possa recuperarle e verificare la firma dei token che riceve. Il formato si presenta sempre così:

{
  "keys": [
    { "kty": "RSA", "kid": "abc123", "use": "sig", "alg": "RS256", "n": "...", "e": "AQAB" },
    { "kty": "EC",  "kid": "def456", "use": "sig", "alg": "ES256", "crv": "P-256", "x": "...", "y": "..." }
  ]
}

Ogni voce dell'array keys è una JWK (JSON Web Key) che descrive una chiave pubblica: tipo di chiave (kty), identificatore (kid), uso previsto (use), algoritmo target (alg) e componenti crittografiche.

Quando serve un JWKS?

Il JWKS è la spina dorsale delle architetture OAuth2 e OpenID Connect moderne. Lo incontrerete in vari contesti:

• Discovery OIDC: ogni provider OpenID Connect espone un documento di configurazione a /.well-known/openid-configuration che contiene un campo jwks_uri. A questo URL si trova un JWKS che elenca le chiavi pubbliche attive.
• Verifica di JWT: quando la vostra API riceve un token firmato in RS256 o ES256, legge il kid dell'header, scarica il JWKS dell'emettitore, ritrova la chiave corrispondente, ne deriva la chiave pubblica nel formato PEM, e verifica la firma.
• Rotazione di chiavi: un emettitore può pubblicare più chiavi simultaneamente, il che permette di introdurre una nuova chiave per firmare i nuovi token mantenendo l'antica in servizio finché i token in circolazione scadono.
• Federazioni: SAML, SCIM, servizi interconnessi, la pubblicazione di un JWKS evita di dover scambiare manualmente certificati X.509 tra partner.

Campi essenziali di una JWK

Alcuni campi ricorrono sistematicamente in una JWK. Questo strumento li estrae e li mostra per ogni chiave del JWKS analizzato:

• kid (key ID): identificatore unico della chiave. È questo valore che l'header di un JWT mette nel suo campo kid per indicare quale chiave del JWKS deve servire alla verifica.
• kty (key type): famiglia crittografica. I due valori dominanti sono RSA (chiavi RSA classiche, usate con RS256, RS384, RS512) ed EC (curve ellittiche, usate con ES256, ES384, ES512).
• alg (algorithm): algoritmo di firma per il quale questa chiave è prevista. Campo facoltativo ma spesso indicato. Permette di filtrare rapidamente le chiavi utilizzabili per un dato JWT.
• use: uso della chiave. sig per la firma (caso usuale), enc per la cifratura (raro, usato con JWE).

Perché convertire una JWK in PEM?

La maggior parte delle librerie crittografiche classiche (OpenSSL, openssl_verify in PHP, crypto in Node.js, la JCA in Java) accetta le chiavi pubbliche nel formato PEM (Base64 incorniciato da -----BEGIN PUBLIC KEY-----), non direttamente nel formato JWK. Convertire una JWK in PEM è quindi indispensabile per:

• Verificare manualmente la firma di un JWT da uno script o uno strumento da riga di comando (jwt, jose, step crypto).
• Importare la chiave in uno strumento di debug come JWT Verifier che attende una chiave PEM nel suo campo "chiave pubblica".
• Memorizzare una chiave in cache locale o in un file di configurazione in una forma universale e leggibile.
• Confrontare rapidamente due chiavi (il formato PEM facilita i diff visivi).

Limiti e avvertenze

• La conversione si effettua in una sola direzione: JWKS verso PEM. La ricostruzione di una JWK a partire da una chiave PEM esistente non è coperta da questa versione.
• Il JWKS deve essere incollato così com'è come testo JSON. Il recupero automatico da un URL jwks_uri o un endpoint OIDC non è fatto lato server, per evitare chiamate uscenti impreviste.
• Le chiavi private non dovrebbero apparire in un JWKS pubblico, e questo strumento estrae solo le componenti pubbliche anche se una chiave privata fosse presente.

Come usarlo

1. Recuperate il JWKS dell'emettitore che volete ispezionare. Per un provider OIDC, l'indirizzo è generalmente https://esempio.com/.well-known/jwks.json o https://esempio.com/oauth2/jwks.
2. Copiate l'intero documento JSON (l'oggetto contenente la chiave keys).
3. Incollatelo nella zona di input dello strumento e avviate l'analisi.
4. Per ogni chiave del JWKS, lo strumento mostra il suo kid, il suo kty, il suo alg, il suo use e la chiave pubblica convertita nel formato PEM.
5. Cliccate su "copia" per recuperare la PEM e usarla in uno script di verifica, nel nostro JWT Verifier, o in qualsiasi strumento compatibile OpenSSL.

Domande frequenti

Esempio di richiesta

curl -X POST https://cdrn.fr/api/v1/tools/jwks-inspector/execute \
  -H "Content-Type: application/json" \
  -d '{"jwks":"..."}'

Schema di input

Endpoint

• GET https://cdrn.fr/api/v1/tools - elenca tutti gli strumenti disponibili
• GET https://cdrn.fr/api/v1/tools/jwks-inspector - recupera lo schema di questo strumento
• POST https://cdrn.fr/api/v1/tools/jwks-inspector/execute - esegue questo strumento con un payload JSON