Chiavi di firma
Consultare, ruotare e revocare le chiavi che firmano i token OIDC e SAML, e capire perché la rotazione è importante per le applicazioni collegate.
La piattaforma firma i token che emette, ossia gli ID token e gli access token OIDC e le assertion OAuth/OIDC, con una chiave di firma privata. Le applicazioni collegate verificano quelle firme rispetto alla chiave pubblica corrispondente, che la piattaforma pubblica sul proprio endpoint JWKS (/.well-known/jwks). La scheda Chiavi di firma permette di esaminare, ruotare e revocare queste chiavi.

Ciclo di vita di una chiave
Si segua un token: al momento dell'emissione viene firmato con la chiave attuale e ne porta l'identificatore (kid) nell'header. L'applicazione legge il kid, cerca la chiave nel key set pubblicato e verifica la firma. Il key set contiene al massimo tre chiavi: quella che firmerà a partire dalla prossima rotazione, quella che firma adesso e quella che ha firmato fino all'ultima rotazione. Finché una chiave resta nel set, i token che portano il suo kid risultano verificabili; una chiave revocata esce dal set e da quel momento i suoi token non superano più la verifica.
La scheda Chiavi di firma mostra queste tre chiavi con il rispettivo stato:
| Stato | Ruolo |
|---|---|
| Prossima in coda | Pubblicata in anticipo, così che le applicazioni la conoscano già quando inizia a firmare. |
| Attualmente in uso | Firma ogni token emesso in questo momento. |
| Usata in precedenza | Ha firmato fino all'ultima rotazione. È ancora nel key set, quindi i token che portano il suo kid restano verificabili fino alla revoca. |
Ogni chiave è identificata da un ID della chiave (kid), che le applicazioni usano per scegliere la chiave pubblica corretta durante la verifica di un token. Un badge accanto all'ID della chiave indica la lunghezza della chiave in bit. Le chiavi generate di recente sono RSA a 3072 bit; le chiavi più vecchie a 2048 bit restano valide per la verifica e vengono sostituite dalla lunghezza più robusta man mano che si effettuano le rotazioni.
Consultare ed esportare una chiave
Per qualsiasi chiave dell'elenco, aprire il menu delle azioni per:
- Copia certificato di firma, per copiare il certificato di firma negli appunti.
- Visualizza certificato di firma, per consultarne i dettagli.
- Scarica certificato di firma, per scaricare il certificato come file
.pem.
Questo è utile quando un'applicazione richiede il certificato configurato manualmente anziché recuperato dall'endpoint JWKS.
Perché la rotazione è importante
Ruotare regolarmente le chiavi di firma limita i danni nel caso in cui una chiave venga compromessa ed è un requisito di conformità diffuso. Quanto lavoro comporti una rotazione dipende da come ciascuna applicazione ha ottenuto la chiave:
- Un Service Provider SAML o WS-Federation che considera attendibile un unico certificato fissato deve ricevere il certificato della chiave Prossima in coda prima della rotazione, altrimenti la sua verifica della firma fallisce dopo la modifica.
- Un'applicazione OIDC con una chiave configurata manualmente richiede la stessa preparazione.
- Un'applicazione che recupera il key set dall'endpoint JWKS adotta la nuova chiave da sé, perché l'endpoint pubblica le chiavi pubbliche prossima, attuale e precedente. Per queste applicazioni la rotazione avviene senza interruzioni di servizio.
Nota: la rotazione riguarda le applicazioni OIDC e OAuth. Dopo una rotazione possono trascorrere fino a circa 30 secondi prima che la modifica sia pienamente efficace.
Ruotare e revocare
Le azioni si trovano in Azioni distruttive in fondo alla pagina. Ciascuna richiede una conferma.
| Azione | Che cosa succede | Effetto sui token esistenti |
|---|---|---|
| Rotate key | La chiave Prossima in coda diventa Attualmente in uso; la vecchia chiave attuale diventa Usata in precedenza. Se esisteva già una chiave precedente, viene revocata e passa nell'elenco delle revoche. | La verifica dei token già emessi prosegue; la chiave precedente resta nel key set. |
| Rotate & revoke key | Esegue la rotazione come sopra e revoca immediatamente la chiave precedente. | I token che portano il kid della chiave precedente non superano più la verifica. |
| Revoke key | Revoca la chiave Usata in precedenza senza rotazione. | I token che portano il kid di quella chiave non superano più la verifica. |
Le tre revoche più recenti restano elencate con la rispettiva data, a fini di audit.
Sequenza consigliata
- Assicurarsi che ogni applicazione che fissa manualmente un certificato consideri attendibile la chiave Prossima in coda.
- Usare Rotate key. I nuovi token vengono ora firmati con la nuova chiave; i token più vecchi restano validi.
- Quando si ha la certezza che nessuna applicazione dipende più dalla chiave precedente, revocarla.
Usare Rotate & revoke key solo quando è necessario invalidare immediatamente i token emessi in precedenza, ad esempio dopo una sospetta compromissione della chiave.
Attenzione: revocare una chiave su cui le applicazioni fanno ancora affidamento interrompe la loro verifica dei token. Ruotare prima, verificare che le applicazioni siano passate alla nuova chiave e revocare solo in seguito.
Chiavi centrali e certificato di firma per singola applicazione
Le chiavi di firma compaiono in due punti e non sono la stessa cosa:
- Le chiavi di firma centrali di questa pagina firmano ogni ID token e access token OIDC emesso dalla piattaforma, nonché le Assertion SAML/WS-Federation che produce per impostazione predefinita. Una rotazione effettuata qui riguarda tutte le applicazioni che considerano attendibili le chiavi pubblicate dalla piattaforma.
- Un certificato di firma per singola applicazione può essere configurato in alternativa su una singola applicazione SAML o WS-Federation, quando quel Service Provider si aspetta di considerare attendibile un certificato specifico anziché la chiave centrale della piattaforma.
Se un Service Provider segnala un errore di firma, verificare per prima cosa quale chiave è configurato a considerare attendibile: la chiave centrale pubblicata sull'endpoint JWKS oppure un certificato fissato su quella singola applicazione. Vedere Integrazioni → Applicazioni per sapere dove si impostano le credenziali di un'applicazione.