Creare e gestire un client OAuth2
Per usare le API Shellrent in modo sicuro, il primo passo è creare un client OAuth2. Il client ti permette di ottenere gli access_token necessari per autenticare le chiamate API e di definire con precisione quali permessi concedere alla tua integrazione.
Questa guida spiega come creare un client, come gestirlo nel tempo, come limitare gli IP da cui usare le API e dove consultare i log delle richieste effettuate.
Per ottenere i token il tuo account deve avere l'autenticazione a due fattori attiva. Puoi creare il client anche senza, ma finché non la attivi le richieste di token vengono rifiutate con stato 400 ed errore unauthorized_client.
Creare un nuovo client OAuth2
Per creare un nuovo client:
- apri la pagina Il mio profilo;
- clicca su Chiavi API e apri la scheda Client API oAuth2;
- nella sezione Client API oAuth2, clicca su + (Crea nuovo Client).
A questo punto ti verrà chiesto di compilare i dati principali del client:
- Nome del client: è un nome descrittivo, utile solo per riconoscerlo più facilmente in elenco;
- Scope: sono i permessi che autorizzano il client a usare determinati gruppi di endpoint API.
Scegli uno o più scope dal menu a tendina, in base a ciò che la tua integrazione deve fare. La guida Scope e autorizzazioni descrive gli scope disponibili.
Dopo il salvataggio, il sistema genera il nuovo client e mostra:
- il Client ID;
- il Client Secret.
Il Client Secret viene mostrato una sola volta, subito dopo la creazione del client. Salvalo immediatamente in un luogo sicuro, perché in seguito non sarà più possibile visualizzarlo di nuovo.
Con Client ID e Client Secret puoi richiedere il primo token, come descritto in Utilizzo delle API Shellrent, oppure configurare uno degli SDK ufficiali per PHP o Python.
Visualizzare e gestire i client attivi
Nella sezione Client API oAuth2 trovi l'elenco di tutti i client attivi, che puoi filtrare per nome, Client ID o scope.
Per ciascun client puoi aprire il dettaglio cliccando nel punto indicato nell'interfaccia.
Nel dettaglio del client puoi consultare:
- l'ID completo del client;
- l'elenco degli scope autorizzati.
Se ti serve riportare gli scope direttamente nel codice della richiesta token, puoi usare il pulsante Copia: otterrai l'elenco già pronto, con gli scope separati da spazi.
Gli scope di un client non si modificano dopo la creazione. Se la tua integrazione ha bisogno di permessi diversi, crea un nuovo client con gli scope corretti, aggiorna l'integrazione con le nuove credenziali ed elimina il client precedente.
Rigenerare il Client Secret
Se hai bisogno di sostituire il secret del client, puoi rigenerarlo dall'apposita azione disponibile nell'elenco.
Quando rigeneri il secret, è importante tenere presente questo comportamento:
- il secret precedente smette subito di funzionare;
- anche gli access_token già emessi con quel client vengono revocati immediatamente, anche se non sono ancora scaduti;
- tutte le nuove richieste di token dovranno usare il nuovo Client Secret.
Prima di rigenerare il secret, prepara quindi l'aggiornamento delle applicazioni che usano il client: fino a quando non usano il nuovo secret, le loro chiamate vengono rifiutate.
Anche il nuovo Client Secret sarà visibile una sola volta, esattamente come accade in fase di creazione del client.
Eliminare un client OAuth2
Se un client non serve più, puoi eliminarlo dalla relativa azione disponibile nell'elenco.
L'eliminazione di un client invalida immediatamente qualsiasi utilizzo delle API tramite quel client, compresi gli access_token non ancora scaduti.
Per questo motivo, prima di eliminare un client, verifica che non sia ancora in uso in applicazioni, script o servizi attivi.
Limitare l'accesso tramite IP autorizzati
Per aumentare il livello di sicurezza, nella stessa scheda trovi la sezione IP autorizzati, dove puoi definire uno o più indirizzi IP da cui è consentito usare le API.
Gli IP autorizzati valgono per il tuo account, non per il singolo client: si applicano quindi a tutti i client OAuth2 che hai creato.
La sezione mostra gli IP che valgono per queste API: quelli abilitati alle “api” e quelli con “Tutto”, che vale per ogni tipo di accesso. Gli IP abilitati alle “api2” nella pagina Sicurezza del profilo valgono solo per le API2 (deprecate), su manager.shellrent.com/api2.
Se non è configurato alcun IP, le API possono essere usate da qualsiasi indirizzo IP, e la sezione lo segnala con un avviso.
Se invece è presente almeno un IP autorizzato, le chiamate API vengono accettate solo dagli IP indicati: da qualsiasi altro indirizzo la risposta è 403 Forbidden.
Questa impostazione è utile, ad esempio, quando le API vengono usate soltanto da:
- un server applicativo specifico;
- un middleware interno;
- un'infrastruttura con IP statici noti.
Consultare i log
Nella scheda Log della pagina Chiavi API puoi consultare la cronologia dell'utilizzo delle API da parte del tuo account, con due sezioni distinte.
La sezione Log chiamate API elenca le chiamate API eseguite con i tuoi client. Per ogni chiamata puoi vedere:
- il client che l'ha eseguita;
- il metodo HTTP e il path chiamato;
- lo stato della risposta, cioè il codice HTTP;
- l'IP di provenienza e la data.
La sezione Log oAuth elenca invece gli eventi legati ai token, come le emissioni, i rifiuti e le revoche, con il client, l'esito, l'IP e la data. Qui puoi verificare, ad esempio, perché una richiesta di token è stata rifiutata.
Puoi filtrare i log per stato, path, metodo, client, IP e intervallo di date: è il modo più rapido per verificare se una richiesta è andata a buon fine e quale endpoint è stato chiamato.
Nel log non è disponibile il dettaglio completo dei dati inviati o restituiti dall'API.
Buone pratiche consigliate
Per una gestione corretta dei client OAuth2:
- usa un nome descrittivo per ogni client, così da capire subito a quale integrazione appartiene;
- assegna solo gli scope strettamente necessari;
- conserva il Client Secret in un sistema sicuro e non in chiaro nel codice;
- limita gli accessi tramite IP autorizzati quando possibile;
- consulta regolarmente i log per verificare richieste anomale o errori di autenticazione;
- se sospetti una compromissione del secret, rigeneralo immediatamente: i token emessi fino a quel momento vengono revocati.
In sintesi
La gestione dei client OAuth2 ruota attorno a quattro attività principali:
- creare il client con nome e scope corretti;
- conservare con attenzione il Client Secret;
- controllare e aggiornare nel tempo IP autorizzati e secret, creando un nuovo client quando servono scope diversi;
- usare i log per monitorare l'utilizzo delle API.
Una volta creato il client, puoi passare alla richiesta di un token OAuth2 e all'esecuzione delle prime chiamate API.