Come ruotare le credenziali di un'API senza lasciare a metà un'integrazione di file

Cosa significa ruotare una credenziale e quando farlo

Ruotare le credenziali API significa sostituire il segreto utilizzato da un'integrazione e verificare che i processi autorizzati funzionino con il nuovo valore. Può trattarsi di una modifica pianificata, di una risposta a una possibile esposizione oppure di un'attività da svolgere dopo l'uscita di una persona che aveva accesso. In ogni caso, è opportuno definire il motivo e l'ambito: quale credenziale verrà cambiata, quali sistemi la utilizzano e chi coordinerà l'operazione. La rotazione, da sola, non costituisce una revisione completa delle autorizzazioni.

Se una persona non deve più avere accesso, revocare o modificare le sue autorizzazioni è un'azione distinta, che può essere necessaria anche se la credenziale di un'applicazione non cambia. Al contrario, sostituire una chiave non garantisce che siano stati eliminati gli accessi personali non necessari. Tieni separati questi due obiettivi nel piano. Se sospetti un'esposizione, dai priorità alla limitazione dell'uso del segreto interessato e segui la procedura di risposta della tua organizzazione e del fornitore, senza aspettare una normale finestra di manutenzione.

• Modifica pianificata: definisci responsabili, ambito e finestra di esecuzione.
• Esposizione sospetta: considera il segreto potenzialmente compromesso ed evita di copiarlo nei canali di coordinamento.
• Uscita di una persona: rivedi anche le autorizzazioni individuali, non solo la credenziale tecnica.

Fai l'inventario dei sistemi che usano la credenziale prima di modificarla

Inizia consultando la documentazione aggiornata dell'API specifica. Verifica il tipo di autenticazione, le modalità di emissione e revoca delle credenziali, le autorizzazioni associabili e le risposte previste quando una credenziale non è valida. Non dedurre la procedura da quella di un altro servizio: alcuni fornitori offrono un'opzione specifica di rotazione o un limite temporale, ma questo non dimostra che la tua API disponga della stessa funzione. In Apification, le integrazioni possono utilizzare REST API, OpenAPI, webhook, iframe e JavaScript; verifica nella documentazione pertinente quale meccanismo utilizza la tua integrazione.

Poi individua ogni sistema che usa il segreto. L'inventario deve includere applicazioni e ambienti, per esempio test e produzione, oltre a worker, attività pianificate, processi di importazione o esportazione e servizi in esecuzione al di fuori del normale orario lavorativo. Cerca anche configurazioni duplicate e vecchie copie delle distribuzioni. Un elenco incompleto spesso si manifesta con errori intermittenti: l'applicazione principale funziona, ma un'attività notturna conserva il valore precedente.

• Annota responsabile, ambiente, posizione della configurazione e frequenza di esecuzione per ogni sistema che usa la credenziale.
• Includi processi in background e repliche che potrebbero essere ancora attive.
• Non salvare il valore della credenziale nell'inventario.

Prepara l'emissione, la distribuzione e l'eventuale sovrapposizione

Prima della modifica, verifica chi è autorizzato a emettere una nuova credenziale e chi può ritirare quella precedente. Decidi come distribuire il segreto in modo protetto, come aggiornare le istanze e chi controllerà ogni fase. Usa i meccanismi di gestione dei segreti e di distribuzione già approvati dalla tua organizzazione; non usare e-mail, ticket o codice sorgente come archivi di credenziali. Se non esiste una procedura definita, concordane una prima di generare o spostare il segreto.

Chiedi espressamente al fornitore se è possibile mantenere valide due credenziali durante la transizione, quanto dura questa sovrapposizione e come revocare ciascuna credenziale. Non darlo per scontato: le informazioni disponibili non consentono di affermare che Apification supporti credenziali simultanee, rotazione automatica o un periodo di sovrapposizione. Se l'API non consente una transizione parallela, pianifica una finestra coordinata, individua l'ordine delle azioni indicato nella documentazione e concorda come limitare l'impatto in caso di problemi.

• Prima di procedere, verifica la procedura attuale nella documentazione ufficiale.
• Assicurati che i responsabili dell'applicazione, delle operazioni e dell'API siano disponibili durante la modifica.
• Non generare una credenziale senza avere individuato un responsabile e i sistemi che la useranno.

Aggiorna la configurazione in modo controllato

Quando il fornitore ha emesso la credenziale e la procedura è chiara, aggiorna la configurazione protetta usando il meccanismo definito. Evita di inserirla nel repository, in file condivisi senza controlli, in comandi che rimangono nella cronologia del terminale o nei log di debug. Verifica anche che i messaggi di errore non stampino intestazioni, parametri o valori sensibili. Nei ticket di modifica registra lo stato e l'ora di ogni passaggio, mai il segreto né schermate che permettano di recuperarlo.

Se l'architettura e il metodo di autenticazione lo consentono, distribuisci la modifica per fasi: prima a un sistema che usa la credenziale e ha un ambito limitato, poi agli altri e infine ai processi meno frequenti. A ogni fase, controlla il risultato prima di proseguire. Se non è possibile aggiornare gradualmente, coordina la modifica come un'unica operazione e comunica quali servizi potrebbero interrompersi temporaneamente. Non confondere il completamento della distribuzione con la verifica: un processo può avviarsi correttamente e non riuscire a eseguire una specifica operazione sui file.

• Aggiorna tutti gli ambienti previsti e conferma quali istanze hanno ricevuto la configurazione.
• Non pubblicare il segreto in codice, log, conversazioni o richieste di assistenza.
• Interrompi la procedura se compaiono errori non spiegati o se un'istanza conserva una configurazione precedente.

Verifica il flusso effettivo dei file

Prima di iniziare, definisci un test piccolo e rappresentativo. Verifica innanzitutto che il sistema si autentichi e che la risposta dell'API corrisponda all'operazione prevista. Poi controlla le autorizzazioni minime necessarie ed esegui una lettura o una scrittura circoscritta, a seconda di ciò che fa l'integrazione. Controlla il risultato del file e la gestione degli errori: non basta verificare che una richiesta abbia ricevuto risposta. Usa dati adatti ai test ed evita di sovrascrivere contenuti reali senza autorizzazione.

Ripeti la verifica sui sistemi che non condividono il ciclo di esecuzione dell'applicazione principale. Includi, se pertinenti, attività pianificate, worker e processi attivati da webhook. Apification offre integrazioni tramite API e webhook e i suoi servizi di automazione includono tentativi ripetuti, cronologia e statistiche; queste funzionalità possono aiutare a controllare l'attività di un'integrazione, ma non sostituiscono i test di autenticazione né confermano, da sole, che tutti i sistemi siano stati aggiornati. Registra i risultati osservabili e l'ambito preciso del test.

• Autenticazione: il nuovo segreto viene accettato dal sistema previsto.
• Autorizzazione: l'integrazione mantiene solo le autorizzazioni necessarie per la sua attività.
• File: la lettura, la scrittura o la trasformazione prevista termina e il risultato è verificabile.
• Processi asincroni: non rimangono attività non riuscite o in sospeso senza essere esaminate.

Ritira la credenziale precedente sulla base di verifiche concrete

Non ritirare la credenziale precedente solo perché il servizio principale risponde. Prima confronta l'inventario con le istanze attive e le attività eseguite durante un periodo di osservazione adeguato alla frequenza di ogni sistema che usa la credenziale. Se l'API fornisce log adeguati, cerca eventuali richieste che utilizzano ancora il vecchio valore e verifica che non ci siano worker dimenticati o distribuzioni in sospeso. Se non hai visibilità sufficiente, riconosci questo limite e non affermare che tutti i sistemi siano stati migrati.

Quando le verifiche e la procedura documentata indicano che è sicuro, revoca o disattiva la credenziale precedente seguendo le istruzioni del fornitore. Annota l'ora e il responsabile, ma non conservare il segreto. Se il fornitore offre opzioni specifiche, per esempio un'azione di rotazione o un limite di tempo, segui la documentazione aggiornata: il meccanismo di una piattaforma non è una regola generale. La rotazione non modifica automaticamente i file. Per recuperare contenuti, se pertinente, usa la cronologia delle versioni di Cloud come azione separata.

• Prima di revocare, controlla i sistemi attivi e i processi a bassa frequenza.
• Segui il meccanismo di ritiro documentato per l'API, senza improvvisare.
• Verifica che la credenziale precedente non sia più necessaria e registra la decisione.

Ripristino, problemi comuni e lista di controllo per la prossima volta

I problemi più comuni sono prevedibili: un segreto nella cache, una replica dimenticata, un'attività pianificata che non è stata eseguita durante il test o una distribuzione applicata solo ad alcune istanze. Può anche capitare che la credenziale precedente venga revocata prima di completare l'aggiornamento. Definisci in anticipo chi può interrompere la distribuzione, quali segnali richiedono una pausa e come comunicare l'incidente. Se il segreto è considerato esposto, non ripristinarlo come soluzione automatica: riattivarlo potrebbe riaprire il rischio.

Il piano di ripristino deve dipendere dallo stato effettivo delle credenziali e dalla procedura del fornitore. Se la nuova credenziale non funziona e quella precedente è ancora attiva e non è compromessa, il responsabile può interrompere la procedura e applicare il processo approvato per ripristinare uno stato operativo. Se la credenziale precedente è stata esposta o revocata, non dare per scontato che sia possibile ripristinarla: chiedi l'emissione di un'altra credenziale o segui le istruzioni del servizio. Al termine, documenta le cause, i passaggi completati e quelli in sospeso, senza salvare segreti o dati sensibili.

• Prima: documentazione consultata, sistemi che usano la credenziale inventariati, responsabili disponibili e ripristino concordato.
• Durante: configurazione protetta, distribuzione controllata, test sui file e monitoraggio dei processi asincroni.
• Dopo: credenziale precedente ritirata secondo la procedura, risultato confermato e note prive di segreti.
• In caso di dubbi: interrompi la procedura, conserva le evidenze non sensibili e consulta il fornitore prima di revocare o ripristinare.

Domande frequenti