Le API key sono ovunque.
Le utilizziamo per collegare un sito web a un servizio di pagamento, integrare un modello di intelligenza artificiale, inviare email, consultare dati meteorologici oppure comunicare con piattaforme esterne.
Spesso sono semplici stringhe di caratteri che inseriamo in un file di configurazione e poi dimentichiamo.
Il problema è che una API key può rappresentare una credenziale di accesso a servizi, dati e risorse, talvolta anche con conseguenze economiche importanti.
Se finisce nelle mani sbagliate, qualcuno potrebbe utilizzarla per effettuare richieste non autorizzate, consumare risorse a pagamento o accedere a funzionalità che dovrebbero rimanere riservate.
Vediamo come gestire correttamente le API key durante l'intero ciclo di vita di un'applicazione.
Che cos'è una API key?
Una API key è una credenziale utilizzata da un'applicazione per identificarsi o autenticarsi presso un servizio.
Immaginiamo un sito e-commerce che utilizza un servizio esterno per calcolare le spese di spedizione.
Quando il sito invia una richiesta all'API, include una chiave assegnata dal provider.
Il provider verifica la chiave e decide se consentire l'operazione.
Un esempio semplificato di richiesta HTTP potrebbe essere:
GET /v1/shipping/rates HTTP/1.1
Host: api.example.com
X-API-Key: <API_KEY>
In questo esempio, la chiave viene trasmessa attraverso un header HTTP.
È importante ricordare che non tutte le API key funzionano allo stesso modo.
Alcune identificano soltanto il progetto che effettua la richiesta. Altre autorizzano operazioni sensibili e devono essere trattate come veri e propri segreti.
API key e password sono la stessa cosa?
Non esattamente.
Una password viene generalmente associata all'identità di un utente.
Una API key, invece, può identificare un'applicazione, un progetto, un'integrazione o un servizio.
In entrambi i casi, però, la credenziale può concedere accesso a risorse protette.
Per questo motivo, una chiave segreta deve essere gestita con la stessa attenzione riservata alle password e agli altri token di accesso.
Perché le API key vengono esposte?
Le cause più comuni sono spesso legate alle abitudini di sviluppo.
Chiavi inserite direttamente nel codice
Uno sviluppatore potrebbe scrivere una credenziale all'interno di un file PHP:
<?php
$apiKey = 'INSERISCI_QUI_LA_CHIAVE';
Il codice può funzionare perfettamente, ma la gestione del segreto diventa problematica.
Se il file viene condiviso, pubblicato in un repository o incluso in un archivio, la chiave potrebbe essere esposta.
Credenziali pubblicate su GitHub
Uno degli errori più frequenti consiste nell'includere accidentalmente chiavi segrete in un commit.
Anche se la credenziale viene rimossa in un commit successivo, potrebbe rimanere nella cronologia Git o essere già stata copiata.
Ecco perché cancellare la riga dal file non è sufficiente.
Una chiave esposta deve essere considerata potenzialmente compromessa e sostituita.
Chiavi inserite nel frontend
Un'altra situazione delicata riguarda JavaScript eseguito nel browser.
Se una chiave segreta viene inclusa nel codice frontend, gli utenti possono generalmente recuperarla attraverso gli strumenti di sviluppo o analizzando le richieste di rete.
Per questo motivo, le chiavi che concedono privilegi riservati dovrebbero essere utilizzate dal backend.
Esistono anche chiavi progettate per essere pubbliche, come alcuni identificatori client. In quel caso, la sicurezza deve dipendere da restrizioni e controlli appropriati, non dalla segretezza della chiave.
Log e messaggi di errore
Una credenziale può finire anche nei log applicativi, nei sistemi di monitoraggio o nei messaggi di debug.
Per esempio, registrare l'intero contenuto di una richiesta HTTP potrebbe esporre header di autenticazione e token.
I sistemi di logging dovrebbero quindi oscurare automaticamente le informazioni sensibili.
Dove conservare le API key?
La risposta dipende dall'ambiente e dalla complessità dell'applicazione.
Variabili d'ambiente
Per molti progetti, le variabili d'ambiente rappresentano una soluzione pratica.
In PHP, per esempio, una chiave può essere letta attraverso:
<?php
$apiKey = getenv('SERVICE_API_KEY');
if ($apiKey === false || $apiKey === '') {
throw new RuntimeException(
'Credenziale API non configurata'
);
}
La credenziale viene fornita dall'ambiente di esecuzione anziché essere scritta direttamente nel codice sorgente.
Questo non rende automaticamente sicuro il sistema: occorre comunque proteggere configurazione del server, processi, backup e permessi di accesso.
File di configurazione fuori dalla directory pubblica
In alcuni ambienti PHP tradizionali, può essere utile conservare le credenziali in un file separato, non raggiungibile tramite HTTP.
Per esempio:
/home/app/
├── config/
│ └── secrets.php
└── public_html/
└── index.php
Il file contenente i segreti si trova fuori dalla directory pubblica del sito.
Deve essere accessibile soltanto agli utenti di sistema che ne hanno realmente bisogno.
Secret manager
Per infrastrutture più complesse, i secret manager consentono di centralizzare la gestione delle credenziali.
Possono offrire controlli di accesso, audit, versionamento e integrazioni con i servizi cloud.
La scelta dipende dalle esigenze operative: non tutte le applicazioni necessitano di un sistema particolarmente sofisticato.
Il principio del privilegio minimo
Uno degli errori più pericolosi è utilizzare una singola API key con permessi eccessivi.
Immaginiamo che un'applicazione debba soltanto leggere informazioni da un servizio.
Se la chiave dispone anche dei permessi per modificare configurazioni, cancellare dati o amministrare account, un'eventuale compromissione potrebbe avere conseguenze molto più gravi.
Il principio del privilegio minimo suggerisce di assegnare soltanto i permessi necessari per svolgere una determinata attività.
Quando il provider lo consente, conviene utilizzare chiavi distinte per ambienti e applicazioni differenti.
Per esempio:
- Una chiave per lo sviluppo.
- Una chiave per lo staging.
- Una chiave per la produzione.
- Chiavi separate per integrazioni con esigenze diverse.
In questo modo, revocare una credenziale non significa necessariamente interrompere tutte le altre integrazioni.
Che cosa significa ruotare una API key?
La rotazione consiste nel sostituire una credenziale esistente con una nuova.
Può essere necessaria quando una chiave è stata esposta, quando cambia il personale autorizzato oppure nell'ambito di una politica di sicurezza.
La procedura ideale dipende dalle funzionalità offerte dal provider.
Quando è possibile mantenere temporaneamente attive due chiavi, una rotazione può seguire questi passaggi:
- Generare una nuova API key.
- Configurarla nell'applicazione.
- Verificare che le richieste funzionino correttamente.
- Disattivare la vecchia chiave.
- Controllare i log per individuare eventuali errori.
Questo approccio riduce il rischio di interruzioni.
Se invece il provider consente una sola chiave attiva, bisogna pianificare la sostituzione con maggiore attenzione.
Cosa fare se una API key è stata pubblicata per errore?
La prima cosa da evitare è pensare che basti cancellarla dal repository.
Se una chiave è stata pubblicata, potrebbe essere già stata acquisita da sistemi automatici.
È opportuno:
- Revocare o ruotare tempestivamente la credenziale.
- Controllare le attività effettuate attraverso quella chiave.
- Verificare consumi, addebiti e richieste anomale.
- Individuare il punto da cui è avvenuta l'esposizione.
- Correggere il processo che ha causato il problema.
Se necessario, si può intervenire anche sulla cronologia del repository, ma questa operazione non sostituisce la revoca.
Come individuare le chiavi segrete nel codice
Esistono strumenti di secret scanning capaci di cercare credenziali e token all'interno dei repository.
Tra questi troviamo Gitleaks e altre soluzioni integrabili nei processi di sviluppo.
Per esempio, in un repository locale è possibile utilizzare un controllo con Gitleaks, se installato:
gitleaks git --redact
Le opzioni disponibili possono variare in base alla versione dello strumento.
Il controllo automatico è utile, ma non infallibile: alcune credenziali potrebbero non essere riconosciute, soprattutto se utilizzano formati personalizzati.
Come proteggere le API key durante le richieste
Oltre alla conservazione, è importante considerare il modo in cui vengono utilizzate.
Utilizzare HTTPS
Le richieste che trasmettono credenziali devono avvenire attraverso connessioni cifrate.
Evitare le chiavi negli URL
Inserire una credenziale nella query string, quando esistono alternative supportate, può aumentarne l'esposizione in log, cronologie e altri sistemi.
È preferibile utilizzare i meccanismi di autenticazione raccomandati dal provider, spesso basati su header HTTP.
Impostare restrizioni quando disponibili
Alcuni servizi consentono di limitare l'utilizzo delle chiavi a specifici indirizzi IP, domini, API o operazioni.
Queste restrizioni non sostituiscono la protezione del segreto, ma possono ridurre i danni di un uso improprio.
Monitorare utilizzo e anomalie
Un improvviso aumento delle richieste, accessi da ambienti inattesi o consumi anomali possono indicare un problema.
È utile configurare avvisi e limiti di spesa quando il servizio li mette a disposizione.
API key e applicazioni SaaS
Per chi sviluppa una piattaforma SaaS, la gestione delle credenziali richiede particolare attenzione.
Un'applicazione può utilizzare API key interne per comunicare con servizi esterni e, contemporaneamente, emettere chiavi per i propri clienti.
Nel secondo caso, è opportuno progettare un sistema che permetta agli utenti di creare, limitare e revocare le proprie chiavi.
Le chiavi dei clienti dovrebbero avere identificatori, permessi e tracciamento appropriati.
Quando possibile, conviene memorizzare una rappresentazione crittografica non reversibile delle chiavi utilizzate per l'autenticazione, anziché conservarle integralmente in chiaro.
Il server potrà così verificarle senza dover recuperare il segreto originale.
Conclusione
Le API key sono piccole, ma possono aprire la porta a servizi molto importanti.
Proteggerle significa considerare tutto il loro ciclo di vita: generazione, conservazione, utilizzo, monitoraggio, rotazione e revoca.
La regola più utile è semplice: una credenziale deve essere accessibile soltanto dove serve, disporre dei permessi strettamente necessari e poter essere revocata rapidamente.
Con MiHakero puoi monitorare gli elementi pubblicamente esposti della tua infrastruttura web e individuare configurazioni da verificare. La ricerca delle chiavi nel codice e la gestione dei segreti richiedono invece controlli dedicati da integrare nel processo di sviluppo.