Gestione delle credenziali

Ottenere il primo token è solo l’inizio. Una volta che un’applicazione OAuth è in produzione, le sue credenziali devono essere archiviate in modo sicuro, ruotate di tanto in tanto e revocate rapidamente se qualcosa va storto. Sono esattamente le domande che pone una revisione di sicurezza. Questa pagina copre tutti e tre i punti, oltre a cosa può effettivamente raggiungere un token trapelato e cosa fare in caso di fuga di credenziali.

Dove deve stare un client secret

Conservalo in una variabile d’ambiente o in un secrets manager (AWS Secrets Manager, Vault o simili), mai nel controllo versione, e mai in un file di configurazione che viene committato insieme al codice.
Non includerlo mai in un’applicazione desktop o in un client basato su browser. Tutto ciò che è installato sulla macchina di un utente o servito a un browser può avere il proprio bundle ispezionato, quindi qualsiasi secret incorporato lì va trattato come pubblico dal momento in cui viene rilasciato.
È esattamente per questo che il flusso Native Application non emette alcun client secret: è pensato per integrazioni desktop e CLI che non hanno modo di tenerne uno riservato, e si affida invece a PKCE (una prova per richiesta legata al codice di autorizzazione). Anche il flusso Authorization Code + redirect HTTPS personalizzato usa PKCE, e permette di aggiungere un client secret solo per client riservati il cui gestore di redirect gira su un server che controlli tu. Un’implementazione solo browser (SPA) di questo flusso dovrebbe fare a meno del secret, per lo stesso motivo per cui il flusso Native non ne ha mai avuto uno. Vedi Per iniziare: Scegli un flusso OAuth.
Client Credentials è un flusso da server a server e richiede sempre un secret: conservalo con le stesse regole di qualsiasi altra credenziale lato server.

Ruotare un client secret senza downtime

Rigenerare un secret da Settings → OAuth sulla tua applicazione lo sostituisce completamente. Non esiste una finestra in cui il vecchio e il nuovo secret sono entrambi validi: un chiamante che presenta ancora il vecchio secret viene rifiutato a partire dalla sua prossima richiesta di token o di refresh.

Questo non significa che ogni richiesta in corso fallisca nell’istante in cui ruoti il secret. Un access token già emesso continua a funzionare finché non scade la sua TTL (circa un’ora, vedi Ciclo di vita del token), indipendentemente da cosa succede in seguito al secret che lo ha emesso originariamente. Solo una nuova richiesta di token o un refresh richiedono il nuovo secret.

Sequenza di passaggio consigliata:

Rigenera il secret.
Nello stesso cambiamento, aggiorna ogni luogo in cui la tua integrazione archivia il secret (configurazione, secrets manager, ogni istanza o worker) prima che una di esse debba emettere o rinnovare un token.
Conferma che le nuove richieste di token abbiano successo con il nuovo secret.

Se non puoi aggiornare ogni istanza in modo atomico, pianifica la rotazione come un deploy coordinato piuttosto che un rollout graduale: un’istanza che detiene ancora il vecchio secret fallisce completamente la prossima volta che ha bisogno di un token, non torna elegantemente a quello vecchio.

Revocare l’accesso

Esistono due modi per interrompere l’accesso, ed entrambi fermano il nuovo accesso:

Revocare una singola autorizzazione da Settings → Third-party access. L’applicazione non può più rinnovare né ottenere token tramite quell’autorizzazione, senza conseguenze per gli altri utenti dell’applicazione.
Eliminare l’applicazione OAuth da Settings → OAuth. In questo modo viene revocata per tutti: non è più possibile emettere access token o refresh token per essa, e il suo client secret smette di funzionare esattamente come dopo una rotazione. Per un’applicazione che usa le client credentials, disattiva anche l’utente di servizio dell’applicazione nella stessa operazione.

Revocare un’autorizzazione, eliminare l’applicazione e ruotare il suo secret non toccano un access token già emesso: nessuna di queste azioni ne forza la scadenza. Considera quel token utilizzabile, con i suoi scope originali, finché non scade la sua TTL. Vedi Ciclo di vita del token per il quadro completo di cosa influisce, o non influisce, su un token attivo.

Cosa può raggiungere un token trapelato

Un token trapelato non è una fuga dell’intera organizzazione: è limitato due volte, secondo il modello di sicurezza a tre livelli:

I suoi scope OAuth (livello 1): fissati nel token al momento dell’emissione. Rimuovere uno scope dall’applicazione in seguito non riduce un token già emesso; questo ha effetto solo la prossima volta che il token viene rinnovato o riemesso.
L’accesso ai contenuti e il ruolo dell’utente di servizio (livelli 2 e 3): quali nodi (organizzazioni, divisioni, siti) può vedere l’utente di servizio del token, e cosa può farci. A differenza degli scope, questo non è fissato nel token: viene valutato rispetto alla tua configurazione attuale a ogni richiesta.

La conclusione pratica: quanto più stringi l’ambito dell’applicazione e del suo utente di servizio fin dall’inizio, tanto meno vale un token trapelato.

Dopo una sospetta fuga di credenziali

Procedi in quest’ordine:

Ruota subito il client secret (Settings → OAuth → la tua applicazione). È la cosa più rapida che puoi fare, e impedisce immediatamente che qualsiasi nuova richiesta di token o di refresh vada a buon fine con il vecchio secret.
Elimina l’applicazione OAuth se non intendi continuare a usarla, o sospetti che la compromissione vada oltre un singolo secret. Per un’applicazione client credentials, questo disattiva anche il suo utente di servizio, interrompendo del tutto l’emissione di nuovi token.
Restringi o rimuovi l’accesso ai contenuti dell’utente di servizio. Poiché l’accesso a contenuti e ruoli (livelli 2-3) viene verificato in tempo reale anziché fissato nel token, questo riduce immediatamente ciò che un token trapelato ancora valido può raggiungere, anche prima che la sua TTL scada.
Considera il token attivo per un’ulteriore finestra di TTL (circa un’ora). Nessuno dei passaggi precedenti forza la scadenza di un token già emesso.
Emetti nuove credenziali (un nuovo secret, o una nuova applicazione) e aggiorna la tua integrazione prima di riprendere l’uso normale.

Cosa c’è dopo?

Ciclo di vita del token per TTL, cache e comportamento di refresh
Per iniziare: Modello di sicurezza per capire come si combinano scope, accesso ai contenuti e ruoli