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 scenari OAuth 2.0 comuni, ad esempio per applicazioni server web, lato client, installate e con dispositivi con input limitato.

Per iniziare, recupera le credenziali client OAuth 2.0 da Google API Console. Quindi, 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 a cui vuoi accedere. Per una dimostrazione interattiva dell'utilizzo di OAuth 2.0 con Google (compresa la possibilità di utilizzare le tue credenziali client), sperimenta 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 maggiori dettagli sull'utilizzo di OAuth 2.0 per l'autenticazione, consulta OpenID Connect.

Passaggi di base

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

1. Ottieni le credenziali OAuth 2.0 da Google API Console.

Visita la Google API Console per ottenere le credenziali OAuth 2.0, ad esempio un ID client e un client secret, note sia a Google che alla tua applicazione. L'insieme di valori varia in base al tipo di applicazione che stai creando. Ad esempio, un'applicazione JavaScript non richiede un secret, a differenza di un'applicazione server web.

Devi creare un client OAuth appropriato per la piattaforma su cui verrà eseguita la tua app, ad esempio:

2. Richiedi un token di accesso al server di autorizzazione di Google.

Prima che l'applicazione possa accedere ai dati privati utilizzando un'API di Google, deve ottenere un token di accesso che concede l'accesso a quell'API. Un singolo token di accesso può concedere vari gradi di accesso a più API. Un parametro variabile chiamato scope controlla l'insieme di risorse e operazioni consentite da un token di accesso. Durante la richiesta di token di accesso, l'applicazione invia uno o più valori nel parametro scope.

Esistono diversi modi per effettuare questa richiesta, che variano in base al tipo di applicazione che stai creando. Ad esempio, un'applicazione JavaScript potrebbe richiedere un token di accesso utilizzando un reindirizzamento del browser a Google, mentre un'applicazione installata su un dispositivo senza 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 è disposto a concedere una o più autorizzazioni richieste dall'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 l'applicazione può utilizzare per ottenere un token di accesso) e un elenco degli ambiti di accesso concessi da tale token. Se l'utente non concede l'autorizzazione, il server restituisce un errore.

Una best practice consiste generalmente nel richiedere gli ambiti in modo incrementale, nel momento in cui è richiesto l'accesso, 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 del token di accesso con gli ambiti richiesti per accedere alle funzionalità e alle funzionalità della tua applicazione in base all'accesso a un'API di Google correlata. Disabilita tutte le funzionalità della tua app che non possono funzionare senza l'accesso all'API correlata.

L'ambito incluso nella richiesta potrebbe non corrispondere a quello incluso nella risposta, anche se l'utente ha concesso tutti gli ambiti richiesti. Per conoscere gli ambiti richiesti per l'accesso, consulta la documentazione di ogni API di Google. Un'API può mappare più valori di stringa di ambito a un singolo ambito di accesso, restituendo la stessa stringa di ambito per tutti i valori consentiti nella richiesta. Esempio: l'API Google People potrebbe restituire un ambito https://www.googleapis.com/auth/contacts quando un'app ha richiesto a un utente di autorizzare un ambito https://www.google.com/m8/feeds/; il metodo dell'API Google People people.updateContact richiede un ambito concesso pari a https://www.googleapis.com/auth/contacts.

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

Dopo che un'applicazione ha ottenuto un token di accesso, lo invia a un'API di Google in un' intestazione della richiesta di autorizzazione HTTP. È possibile inviare token come parametri della stringa di query dell'URI, ma questa operazione è sconsigliata, perché i parametri URI possono finire in file di log non completamente sicuri. È buona norma anche 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 della richiesta del 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 più volte il token di accesso all'API Google Calendar per operazioni simili.

5. Se necessario, aggiorna il token di accesso.

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

Scenari

Applicazioni server web

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

La sequenza di autorizzazione inizia quando l'applicazione reindirizza un browser a un URL di Google. L'URL include parametri di query che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione degli utenti, 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 scopi futuri e utilizzare il token di accesso per accedere a un'API di Google. Alla scadenza del token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.

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

Per maggiori dettagli, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni server web.

Applicazioni installate

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

Il processo genera un ID client e, in alcuni casi, un client secret, che incorpora nel codice sorgente dell'applicazione. (In questo contesto, il client secret non viene ovviamente trattato come un secret.)

La sequenza di autorizzazione inizia quando l'applicazione reindirizza un browser a un URL di Google. L'URL include parametri di query che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione degli utenti, 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 scopi futuri e utilizzare il token di accesso per accedere a un'API di Google. Alla scadenza del token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.

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

Per maggiori dettagli, consulta l'articolo sull' utilizzo di OAuth 2.0 per le applicazioni installate.

Applicazioni lato client (JavaScript)

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

La sequenza di autorizzazione inizia quando l'applicazione reindirizza un browser a un URL di Google. L'URL include parametri di query che indicano il tipo di accesso richiesto. Google gestisce l'autenticazione degli utenti, 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 API di Google.

Per maggiori dettagli, consulta l'articolo sull'utilizzo di OAuth 2.0 per le applicazioni lato client.

Applicazioni su dispositivi di input limitati

L'endpoint OAuth 2.0 di Google supporta applicazioni eseguite su dispositivi con input limitato, come console per videogiochi, fotocamere e stampanti.

La sequenza di autorizzazione inizia con l'applicazione che invia una richiesta di servizio web a un URL di 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 computer separato con funzionalità di input più avanzate. L'utente avvia un browser, passa all'URL specificato, esegue l'accesso e inserisce il codice.

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

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

Per maggiori dettagli, consulta l'articolo sull'utilizzo di OAuth 2.0 per i dispositivi.

Account di servizio

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

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

Le credenziali di un account di servizio, che ottieni da Google API Console, includono un indirizzo email univoco generato, un ID client e almeno una coppia di chiavi pubbliche/private. Puoi 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 quindi la richiesta del token al server di autorizzazione OAuth 2.0 di Google, 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 token JWT per richiedere un token al server di autorizzazione di Google, quindi utilizza il token per chiamare un endpoint API di Google. Non viene coinvolto l'utente finale.

Per maggiori dettagli, consulta la documentazione relativa agli account di servizio.

Dimensioni token

Le dimensioni dei token possono variare, rispettando i 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 strutturati in modo simile ai token di accesso OAuth 2.0 dell'API di 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 e la tua applicazione deve supportare dimensioni token variabili di conseguenza.

Aggiorna scadenza token

Devi scrivere il codice per prevedere la possibilità che un token di aggiornamento concesso possa non funzionare più. Un token di aggiornamento potrebbe non funzionare per uno di questi motivi:

A un progetto Google Cloud Platform con una schermata di consenso OAuth configurata per un tipo di utente esterno e con stato di pubblicazione "Test" viene emesso un token di aggiornamento che scade dopo 7 giorni, a meno che gli unici ambiti OAuth richiesti siano un sottoinsieme di nome, indirizzo email e profilo utente (tramite gli ambiti userinfo.email, userinfo.profile, openid o i relativi equivalente OpenID Connect).

Attualmente esiste un limite di 100 token di aggiornamento per Account Google per ogni ID client OAuth 2.0. Se viene raggiunto il limite, la creazione di un nuovo token di aggiornamento rende automaticamente non valido il 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 può avere su tutti i client. La maggior parte degli utenti normali non supererà questo limite, ma potrebbe farlo l'account di uno sviluppatore utilizzato per testare un'implementazione.

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

Gestione dei criteri di controllo della sessione per le organizzazioni che utilizzano la piattaforma Google Cloud

Gli amministratori delle organizzazioni Google Cloud potrebbero richiedere una frequente riautenticazione degli utenti durante l'accesso alle risorse Google Cloud mediante la funzionalità di controllo della sessione di Google Cloud. Questi criteri influiscono sull'accesso alla console Google Cloud, a Google Cloud SDK (noto anche come gcloud CLI) e a qualsiasi applicazione OAuth di terze parti che richiede l'ambito Cloud Platform. Se un utente ha applicato un criterio di controllo delle sessioni, alla scadenza della durata della sessione le chiamate API avranno un errore simile a quello che accadrebbe se il token di aggiornamento fosse stato revocato. La chiamata non andrà a buon fine con un tipo di errore invalid_grant. Il campo error_subtype può essere utilizzato per distinguere tra un token revocato e un errore dovuto a un criterio di controllo della sessione (ad esempio, "error_subtype": "invalid_rapt"). Poiché la durata delle sessioni può essere molto limitata (tra 1 e 2 ore), questo scenario di autenticazione deve essere gestito completamente

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

Per maggiori informazioni su come aiutare i tuoi clienti a eseguire il deployment di questa funzionalità, consulta questo articolo del Centro assistenza dedicato agli amministratori.

Librerie client

Le seguenti librerie client si integrano con i framework più diffusi, semplificando l'implementazione di OAuth 2.0. Nel tempo verranno aggiunte altre funzionalità alle librerie.