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

Per iniziare, ottieni le credenziali client OAuth 2.0 da Google API Console. L'applicazione client richiede quindi un token di accesso dal server di autorizzazione di Google, estrae un token dalla risposta e lo invia all'API Google a cui vuoi accedere. Per una dimostrazione interattiva dell'utilizzo di OAuth 2.0 con Google (inclusa la possibilità di utilizzare le tue credenziali client), fai esperimenti con OAuth 2.0 Playground.

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

Passaggi di base

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

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

Visita la pagina Google API Console per ottenere le credenziali OAuth 2.0, ad esempio un ID client e un client secret, noti sia a Google sia 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, ma un'applicazione di server web sì.

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

2. Ottieni un token di accesso dal 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 consenta l'accesso a quell'API. Un singolo token di accesso può concedere diversi 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 dell'accesso all'token, la tua applicazione invia uno o più valori nel parametro scope.

Esistono diversi modi per effettuare questa richiesta e 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 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 alla tua applicazione un token di accesso (o un codice di autorizzazione che la tua applicazione può utilizzare per ottenere un token di accesso) e un elenco di ambiti di accesso concessi da quel token. Se l'utente non concede l'autorizzazione, il server restituisce un errore.

In genere, è buona prassi richiedere gli ambiti in modo incrementale, al momento in cui è richiesto l'accesso, piuttosto che 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". Consulta Autorizzazione incrementale.

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

Confronta gli ambiti inclusi nella risposta del token di accesso con quelli necessari per accedere alle funzionalità della tua applicazione, che dipendono dall'accesso a un'API di Google correlata. Disattiva le funzionalità della tua app che non possono funzionare senza 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. Consulta la documentazione di ogni API di Google per conoscere gli ambiti richiesti per l'accesso. 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 di https://www.googleapis.com/auth/contacts quando un'app ha richiesto all'utente di autorizzare un ambito di https://www.google.com/m8/feeds/; il metodo dell'API Google People people.updateContact richiede un ambito concesso 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 lo invia a un'API Google in un' intestazione della richiesta di autorizzazione HTTP. È possibile inviare token come parametri di stringa di query URI, ma non lo consigliamo, perché i parametri URI possono finire in file di log non completamente sicuri. Inoltre, è buona prassi REST evitare di creare nomi di parametri URI non necessari.

I token di accesso sono validi solo per l'insieme di operazioni e risorse descritto nel scope della richiesta di token. Ad esempio, se viene emesso un token di accesso per l'API Google Calendar, non viene concesso l'accesso all'API Google Contacts. Tuttavia, puoi inviare il 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 di accedere 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 2.0 di Google supporta le 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 dell'utente, la selezione della sessione e il consenso dell'utente. Il risultato è un codice di autorizzazione che l'applicazione può scambiare con un token di accesso e un token di aggiornamento.

L'applicazione deve memorizzare il token di aggiornamento per un uso futuro e utilizzare il token di accesso per accedere a un'API Google. Una volta scaduto il 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 Google, riceve un codice di autorizzazione, scambia il codice con un token e utilizza il token per chiamare un endpoint dell'API 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 come computer, dispositivi mobili e tablet. Quando crei un ID cliente tramite Google API Console, specifica che si tratta di un'applicazione installata, quindi seleziona Android, app per Chrome, iOS, Universal Windows Platform (UWP) o app desktop come tipo di applicazione.

La procedura genera un ID client e, in alcuni casi, un client secret, che devi incorporare nel codice sorgente della tua applicazione. In questo contesto, il client secret non viene ovviamente trattato come un segreto.

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 dell'utente, la selezione della sessione e il consenso dell'utente. Il risultato è un codice di autorizzazione che l'applicazione può scambiare con un token di accesso e un token di aggiornamento.

L'applicazione deve memorizzare il token di aggiornamento per un uso futuro e utilizzare il token di accesso per accedere a un'API Google. Una volta scaduto il 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 Google, riceve un codice di autorizzazione, scambia il codice con un token e utilizza il token per chiamare un endpoint dell'API 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 in esecuzione 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 dell'utente, la selezione della sessione e il consenso dell'utente.

Il risultato è un token di accesso, che il client deve convalidare prima di includerlo in una richiesta all'API Google. Quando il token scade, l'applicazione ripete la procedura.

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

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

Applicazioni su dispositivi con input limitato

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

La sequenza di autorizzazione inizia con l'invio da parte dell'applicazione di 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 ottiene l'URL e il codice dal dispositivo, quindi passa a un altro dispositivo o computer con funzionalità di inserimento più avanzate. L'utente avvia un browser, accede all'URL specificato, accede e inserisce il codice.

Nel frattempo, l'applicazione esegue il polling di un URL di Google a un intervallo specificato. 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 memorizzare il token di aggiornamento per un uso futuro e utilizzare il token di accesso per accedere a un'API Google. Una volta scaduto il token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.

L'utente accede su un dispositivo separato con un browser

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

Account di servizio

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

Per questi tipi di interazioni server-to-server, hai bisogno di un account di servizio, ossia un account che appartiene alla tua 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 è necessario. Negli scenari non relativi agli account di servizio, l'applicazione chiama le API di Google per conto degli utenti finali e a volte è necessario il consenso dell'utente.

Le credenziali di un account di servizio, che ottieni da Google API Console, includono un indirizzo email generato univoco, un ID client e almeno una coppia di chiavi pubblica/privata. Utilizza l'ID cliente 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 di 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 Google. Quando il token scade, l'applicazione ripete la procedura.

L'applicazione server utilizza un JWT per richiedere un token al server di autorizzazione Google, quindi utilizza il token per chiamare un endpoint dell'API Google. Non è coinvolto nessun utente finale.

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

Dimensioni del token

Le dimensioni dei token possono 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 strutturati in modo simile ai token di accesso OAuth 2.0 dell'API Google, ma hanno limiti di dimensione diversi. Per maggiori dettagli, consulta la documentazione dell'API.

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

Scadenza del token di aggiornamento

Devi scrivere il codice in modo da anticipare la possibilità che un token di aggiornamento concesso possa non funzionare più. Un token di aggiornamento potrebbe smettere di funzionare per uno dei seguenti motivi:

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

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

Esiste anche un limite maggiore per il numero totale di token di aggiornamento che un account utente o un account di servizio può avere in tutti i client. La maggior parte degli utenti normali non supererà questo limite, ma l'account di un sviluppatore utilizzato per testare un'implementazione potrebbe farlo.

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

Gestire i criteri di controllo della sessione per le organizzazioni Google Cloud (GCP)

Gli amministratori delle organizzazioni Google Cloud potrebbero richiedere una frequente autenticazione degli utenti mentre accedono alle risorse Google Cloud utilizzando la funzionalità di controllo della sessione di Google Cloud. Questo criterio influisce sull'accesso alla console Google Cloud, al Google Cloud SDK (noto anche come gcloud CLI) e a qualsiasi applicazione OAuth di terze parti che richiede l'ambito della piattaforma Cloud. Se un utente ha implementato un criterio di controllo della sessione, alla scadenza della durata della sessione, le chiamate all'API restituiranno un errore simile a quello che si verificherebbe 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é le durate delle sessioni possono essere molto limitate (da 1 a 24 ore), questo scenario deve essere gestito in modo corretto riavviando una sessione di autenticazione.

Allo stesso modo, non devi utilizzare né incoraggiare l'utilizzo di credenziali utente per il deployment da server a server. Se le credenziali utente vengono implementate su un server per operazioni o job di lunga durata e un cliente applica criteri di controllo della sessione a questi utenti, l'applicazione del server non andrà a buon fine perché non sarà possibile autenticare nuovamente l'utente al termine della durata della sessione.

Per ulteriori informazioni su come aiutare i tuoi clienti a implementare questa funzionalità, consulta questo articolo del Centro assistenza rivolto agli amministratori.

Librerie client

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