Utilizzare OAuth 2.0 per accedere alle API di Google

Le API di Google utilizzano il protocollo OAuth 2.0 per l'autenticazione e l'autorizzazione. Google supporta gli scenari OAuth 2.0 più comuni, come quelli relativi a applicazioni server web, lato client, installate e con input limitato.

Per iniziare, recupera le credenziali del client OAuth 2.0 da Google API Console. Successivamente, l'applicazione client richiede un token di accesso al server di autorizzazione di Google, estrae un token dalla risposta e lo invia all'API di Google alla quale vuoi accedere. Per una dimostrazione interattiva dell'utilizzo di OAuth 2.0 con Google (inclusa l'opzione per utilizzare le proprie credenziali client), esegui l'esperimento con OAuth 2.0 Playground.

Questa pagina fornisce una panoramica degli scenari di autorizzazione OAuth 2.0 supportati da Google e fornisce link a contenuti più dettagliati. Per informazioni dettagliate sull'utilizzo di OAuth 2.0 per l'autenticazione, vedi OpenID Connect.

Passaggi di base

Tutte le applicazioni seguono un pattern di base quando accedono a un'API di Google con OAuth 2.0. In linea generale, devi seguire cinque passaggi:

1. Recupera le credenziali OAuth 2.0 dal Google API Console.

Visita Google API Console per ottenere le credenziali OAuth 2.0, come un ID client e un client secret, noti sia a Google che all'applicazione. L'insieme di valori varia in base al tipo di applicazione che stai creando. Ad esempio, un'applicazione JavaScript non richiede un secret, mentre un'applicazione server web sì.

2. Ottenere un token di accesso dal server di autorizzazione di Google.

Prima che la tua applicazione possa accedere ai dati privati mediante un'API, deve ricevere un token di accesso che le consenta di accedere all'API. Un singolo token di accesso può concedere vari livelli di accesso a più API. Un parametro variabile chiamato scope controlla l'insieme di risorse e operazioni consentite dal token di accesso. Durante la richiesta del token di accesso, l'applicazione invia uno o più valori nel parametro scope.

Esistono diversi modi per presentare questa richiesta e variano in base al tipo di applicazione che stai creando. Ad esempio, un'applicazione JavaScript potrebbe richiedere un token di accesso usando un reindirizzamento del browser a Google, mentre un'applicazione installata su un dispositivo privo di browser utilizza le richieste di servizi web.

Alcune richieste richiedono un passaggio di autenticazione in cui l'utente accede con il proprio Account Google. Dopo aver eseguito l'accesso, all'utente viene chiesto se vuole concedere una o più autorizzazioni richieste dalla tua applicazione. Questa procedura è chiamata consenso dell'utente.

Se l'utente concede almeno un'autorizzazione, il server di autorizzazione di Google invia all'applicazione un token di accesso (o un codice di autorizzazione che può essere utilizzato per ottenere un token di accesso) e un elenco di ambiti di accesso concessi da tale token. Se l'utente non concede l'autorizzazione, il server restituisce un errore.

In genere, una best practice richiede la richiesta di ambiti in modo incrementale, al momento dell'accesso richiesto, anziché in anticipo. Ad esempio, un'app che vuole supportare il salvataggio di un evento in un calendario non deve richiedere l'accesso a Google Calendar finché l'utente non preme il pulsante "Aggiungi a Calendar". Vedi Autorizzazione incrementale.

3. Esamina gli ambiti di accesso concessi dall'utente.

Confronta gli ambiti inclusi nella risposta al token di accesso con gli ambiti necessari per accedere alle caratteristiche e funzionalità della tua applicazione in base all'accesso a un'API Google correlata. Disabilita le funzionalità dell'app che non possono funzionare senza accesso all'API correlata.

L'ambito incluso nella tua richiesta potrebbe non corrispondere all'ambito incluso nella risposta, anche se l'utente ha concesso tutti gli ambiti richiesti. Consulta la documentazione di ciascuna API di Google per trovare gli ambiti necessari per l'accesso. Un'API può mappare più valori di una stringa di ambito a un singolo ambito di accesso, restituisce la stessa stringa di ambito per tutti i valori consentiti nella richiesta. Esempio: l'API Google People può restituire un ambito https://www.googleapis.com/auth/contacts quando un'app ha richiesto a un utente l'autorizzazione di un ambito https://www.google.com/m8/feeds/; il metodo API Google People people.updateContact richiede un ambito consentito di https://www.googleapis.com/auth/contacts.

4. Invia il token di accesso a un'API.

Dopo aver ottenuto un token di accesso, un'applicazione invia il token a un'API Google in un'intestazione della richiesta di autorizzazione HTTP. È possibile inviare i token come parametri della stringa di query URI, ma non lo consigliamo, perché i parametri URI possono finire in file di log non completamente sicuri. È buona prassi, inoltre, evitare di creare nomi di parametri URI non necessari.

I token di accesso sono validi solo per l'insieme di operazioni e risorse descritte in scope nella richiesta di token. Ad esempio, se viene emesso un token di accesso per l'API Google Calendar, non concede l'accesso all'API Google Contacts. Tuttavia, puoi inviare questo token di accesso all'API Google Calendar più volte per operazioni simili.

5. Aggiorna il token di accesso, se necessario.

I token di accesso hanno una durata limitata. Se la tua applicazione ha bisogno dell'accesso a un'API Google oltre la durata di un singolo token di accesso, può ottenere un token di aggiornamento. Un token di aggiornamento consente alla tua applicazione di ottenere nuovi token di accesso.

Scenari

Applicazioni server web

L'endpoint OAuth di Google 2.0 supporta le applicazioni server web che utilizzano linguaggi e framework come PHP, Java, Python, Ruby e ASP.NET.

La sequenza di autorizzazioni inizia quando l'applicazione reindirizza un browser a un URL di Google; l'URL include parametri di ricerca che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione, la selezione delle sessioni e il consenso degli utenti. Il risultato è un codice di autorizzazione, che l'applicazione può scambiare con un token di accesso e un token di aggiornamento.

L'applicazione deve archiviare il token di aggiornamento per uso futuro e utilizzarlo per accedere a un'API di Google. Alla scadenza, il token di accesso utilizza il token di aggiornamento.

L'applicazione invia una richiesta di token al server di autorizzazione di Google, riceve un codice di autorizzazione, lo scambia con un token e lo utilizza per chiamare un endpoint dell'API di Google.

Per i dettagli, consulta Utilizzare OAuth 2.0 per applicazioni server web.

Applicazioni installate

L'endpoint di Google OAuth 2.0 supporta le applicazioni installate su dispositivi come computer, dispositivi mobili e tablet. Quando crei un ID client tramite Google API Console, specifica che si tratta di un'applicazione installata, quindi seleziona il tipo di applicazione Android, Chrome, iOS, Universal Windows Platform (UWP) o desktop.

Il processo genera un ID client e, in alcuni casi, un client secret, che incorpori nel codice sorgente della tua applicazione. (in questo contesto, il secret del client ovviamente non è considerato un secret).

La sequenza di autorizzazioni inizia quando l'applicazione reindirizza un browser a un URL di Google; l'URL include parametri di ricerca che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione, la selezione delle sessioni e il consenso degli utenti. Il risultato è un codice di autorizzazione, che l'applicazione può scambiare con un token di accesso e un token di aggiornamento.

L'applicazione deve archiviare il token di aggiornamento per uso futuro e utilizzarlo per accedere a un'API di Google. Alla scadenza, il token di accesso utilizza il token di aggiornamento.

L'applicazione invia una richiesta di token al server di autorizzazione di Google, riceve un codice di autorizzazione, lo scambia con un token e lo utilizza per chiamare un endpoint dell'API di Google.

Per maggiori dettagli, vedi Utilizzare OAuth 2.0 per le applicazioni installate.

Applicazioni lato client (JavaScript)

L'endpoint di Google OAuth 2.0 supporta le applicazioni JavaScript eseguite in un browser.

La sequenza di autorizzazioni inizia quando l'applicazione reindirizza un browser a un URL di Google; l'URL include parametri di ricerca che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione, la selezione delle sessioni e il consenso degli utenti.

Il risultato è un token di accesso, che il client deve convalidare prima di includerlo in una richiesta API di Google. Alla scadenza del token, l'applicazione ripete il processo.

L'applicazione JS invia una richiesta di token al server di autorizzazione di Google,
                  riceve un token, lo convalida e lo utilizza per chiamare un endpoint
                  dell'API di Google.

Per maggiori dettagli, vedi Utilizzare OAuth 2.0 per applicazioni lato client.

Applicazioni su dispositivi di input limitati

L'endpoint di Google OAuth 2.0 supporta le applicazioni eseguite su dispositivi di input limitati come console per videogiochi, videocamere e stampanti.

La sequenza di autorizzazioni inizia con l'applicazione che invia una richiesta di servizio web a un URL Google per un codice di autorizzazione. La risposta contiene diversi parametri, tra cui un URL e un codice che l'applicazione mostra all'utente.

L'utente riceve l'URL e il codice dal dispositivo, quindi passa a un dispositivo o a un computer separato con funzionalità di input più avanzate. L'utente avvia un browser, va all'URL specificato, accede e inserisce il codice.

Nel frattempo, l'applicazione esegue il polling di un URL Google a un intervallo specifico. Dopo che l'utente approva l'accesso, la risposta dal server Google contiene un token di accesso e un token di aggiornamento. L'applicazione deve archiviare il token di aggiornamento per uso futuro e utilizzarlo per accedere a un'API di Google. Dopo la scadenza del token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.

L'utente accede a un dispositivo separato dotato di un browser

Per maggiori dettagli, vedi Utilizzare OAuth 2.0 per i dispositivi.

Account di servizio

Le API di Google, come l'API Prediction e Google Cloud Storage, possono agire per conto della tua applicazione senza accedere alle informazioni utente. In questi casi, l'applicazione deve dimostrare la propria identità all'API, ma non è necessario il consenso dell'utente. Analogamente, in scenari aziendali, la tua applicazione può richiedere l'accesso delegato ad alcune risorse.

Per questi tipi di interazioni server-server è necessario un account di servizio, ovvero un account che appartiene alla tua applicazione anziché a un singolo utente finale. L'applicazione chiama le API di Google per conto dell'account di servizio e non è richiesto il consenso dell'utente. In scenari non relativi ad account di servizio, l'applicazione chiama le API di Google per conto degli utenti finali e a volte è richiesto il consenso degli utenti.

Le credenziali di un account di servizio, che puoi ottenere da Google API Console, includono un indirizzo email univoco, un ID client e almeno una coppia di chiavi pubblica/privata. Devi utilizzare l'ID client e una chiave privata per creare un JWT firmato e creare una richiesta di token di accesso nel formato appropriato. L'applicazione invia la richiesta del token al server di autorizzazione Google OAuth 2.0, che restituisce un token di accesso. L'applicazione utilizza il token per accedere a un'API di Google. Alla scadenza del token, l'applicazione ripete il processo.

L'applicazione server utilizza un JWT per richiedere un token al server di autorizzazione di Google, quindi utilizza il token per chiamare un endpoint dell'API di Google. Non sono coinvolti utenti finali.

Per maggiori dettagli, consulta la documentazione dell'account di servizio.

Dimensione token

La dimensione dei token può variare fino ai seguenti limiti:

  • Codici di autorizzazione: 256 byte
  • Token di accesso: 2048 byte
  • Token di aggiornamento: 512 byte

I token di accesso restituiti dall'API Security Token Service di Google Cloud sono simili ai token di accesso OAuth 2.0 dell'API Google, ma hanno limiti di dimensione dei token diversi. Per maggiori dettagli, consulta la documentazione dell'API.

Google si riserva il diritto di modificare le dimensioni del token entro questi limiti. La tua applicazione deve supportare le dimensioni del token variabili di conseguenza.

Scadenza aggiornamento token

Devi scrivere il tuo codice per prevedere la possibilità che un token di aggiornamento concesso non funzioni più. Un token di aggiornamento potrebbe smettere di funzionare per uno dei seguenti motivi:

  • L'utente ha revocato l'accesso della tua app.
  • Il token di aggiornamento non è stato utilizzato per sei mesi.
  • L'utente ha modificato le password e il token di aggiornamento contiene ambiti Gmail.
  • L'account utente ha superato il numero massimo di token di aggiornamento garantiti (dal vivo).
  • L'utente appartiene a un'organizzazione Google Cloud Platform con criteri di controllo della sessione attivi.

A un progetto Google Cloud Platform con una schermata di consenso OAuth configurata per un tipo di utente esterno e con uno stato di pubblicazione "Di prova", viene emesso un token di aggiornamento che scade tra 7 giorni.

Attualmente è previsto un limite di 50 token di aggiornamento per ogni Account Google per ogni ID client OAuth 2.0. Quando viene raggiunto tale limite, la creazione di un nuovo token di aggiornamento annulla automaticamente la validità del token di aggiornamento meno recente senza preavviso. Questo limite non si applica agli account di servizio.

Esiste anche un limite maggiore al numero totale di token di aggiornamento che un account utente o un account di servizio possono avere per tutti i client. La maggior parte degli utenti normali non supera questo limite, ma un account sviluppatore utilizzato per testare un'implementazione potrebbe farlo.

Se devi autorizzare più programmi, macchine o dispositivi, una soluzione alternativa è limitare il numero di client autorizzati per ogni Account Google a 15 o 20. Se sei un amministratore di Google Workspace, puoi creare altri utenti con privilegi di amministratore e utilizzarli per autorizzare alcuni client.

Gestione dei criteri di controllo delle sessioni per le organizzazioni Google Cloud Platform (GCP)

Gli amministratori delle organizzazioni GCP potrebbero richiedere la riautenticazione frequente degli utenti mentre accedono alle risorse GCP, utilizzando la funzionalità di controllo della sessione Google Cloud. Questo criterio influisce sull'accesso a Google Cloud Console, all'SDK Google Cloud SDK (noto anche come l'interfaccia a riga di comando gcloud) e a qualsiasi applicazione OAuth di terze parti che richiede l'ambito Cloud Platform. Se un utente ha un criterio di controllo della sessione, alla scadenza della durata della sessione le chiamate API avranno un errore simile a quello che accadrebbe se il token di aggiornamento venisse revocato: la chiamata non riuscirà con un tipo di errore invalid_token; il tipo di errore secondario può essere utilizzato per distinguere tra un token di revoca e un errore dovuto a un criterio di controllo della sessione. Poiché la durata delle sessioni può essere molto limitata (da 1 ora a 24 ore), questo scenario deve essere gestito normalmente riavviando una sessione di autenticazione.

Analogamente, non devi utilizzare o incoraggiare l'uso delle credenziali utente per il deployment server-to-server. Se viene eseguito il deployment delle credenziali utente su un server per operazioni o operazioni a lunga esecuzione e un cliente applica criteri di controllo delle sessioni a tali utenti, l'applicazione del server avrà esito negativo poiché non sarà possibile autenticare nuovamente l'utente alla scadenza della sessione.

Per ulteriori informazioni su come aiutare i clienti a eseguire il deployment di questa funzionalità, consultate questo articolo del Centro assistenza incentrato sull'amministratore.

Librerie client

Le seguenti librerie client si integrano con i framework più diffusi, il che semplifica l'implementazione di OAuth 2.0. Nel corso del tempo verranno aggiunte altre funzionalità.