Passa al contenuto principale

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 e dove consultare i log delle richieste effettuate.

Creare un nuovo client OAuth2​

Per creare un nuovo client:

  1. apri la pagina Il mio profilo;
  2. clicca su Chiavi API;
  3. nella sezione Client API OAuth2, clicca su + per aggiungere un nuovo client.

Sezione Client API OAuth2 con pulsante di creazione

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.

Creazione del client con nome e selezione degli scope

Dopo il salvataggio, il sistema genera il nuovo client e mostra:

  • il Client ID;
  • il Client Secret.
Attenzione al 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.

Visualizzare e gestire i client attivi​

Nella pagina Client API OAuth2 trovi l'elenco di tutti i client attivi.

Per ciascun client puoi aprire il dettaglio cliccando nel punto indicato nell'interfaccia.

Elenco dei client OAuth2 e accesso al dettaglio

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.

Dettaglio del client con pulsante per copiare gli scope

Rigenerare il Client Secret​

Se hai bisogno di sostituire il secret del client, puoi rigenerarlo dall'apposita azione disponibile nel dettaglio.

Azione per rigenerare il Client Secret

Quando rigeneri il secret, è importante tenere presente questo comportamento:

  • gli access_token già emessi e non ancora scaduti restano validi fino alla loro scadenza naturale;
  • tutte le nuove richieste di emissione token o di refresh token dovranno invece usare il nuovo Client Secret.
Attenzione

Anche il nuovo Client Secret sarà visibile una sola volta, esattamente come accade in fase di creazione del client.

Nuovo Client Secret mostrato una sola volta

Eliminare un client OAuth2​

Se un client non serve più, puoi eliminarlo dalla relativa azione disponibile nel dettaglio o nell'elenco.

Azione per eliminare un client OAuth2

Eliminazione del client

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, puoi definire uno o più IP autorizzati.

Se non è configurato alcun IP, il client può richiedere token e usare le API da qualsiasi indirizzo IP.

Se invece è presente almeno un IP autorizzato, l'accesso viene consentito solo dagli IP indicati.

Questa impostazione è utile, ad esempio, quando il client viene usato soltanto da:

  • un server applicativo specifico;
  • un middleware interno;
  • un'infrastruttura con IP statici noti.

Configurazione degli IP autorizzati

Consultare i log del client​

Nella sezione Log puoi consultare la cronologia delle operazioni effettuate dal client.

Sono tracciate sia:

  • le richieste di emissione token;
  • le richieste di refresh token;
  • le chiamate API eseguite con il client.

Per ogni voce di log puoi vedere le informazioni principali, come:

  • il tipo di richiesta;
  • l'URL interrogato;
  • l'esito dell'operazione.

Il log è pensato per aiutarti a verificare rapidamente se una richiesta è andata a buon fine e quale endpoint è stato chiamato.

Nota

Nel log non è disponibile il dettaglio completo dei dati restituiti in risposta dall'API.

Sezione log con elenco delle chiamate e dei tentativi di emissione token

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.

In sintesi​

La gestione dei client OAuth2 ruota attorno a quattro attività principali:

  1. creare il client con nome e scope corretti;
  2. conservare con attenzione il Client Secret;
  3. controllare e aggiornare nel tempo configurazione, IP autorizzati e secret;
  4. 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.