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, lato client, installate e per dispositivi a input limitato applicazioni.
Per iniziare, ottieni le credenziali client OAuth 2.0 dalla console API di Google. Poi, l'applicazione client richiede un token di accesso dal 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 (inclusa l'opzione di utilizzare le tue credenziali client), prova OAuth 2.0 Playground.
Questa pagina fornisce una panoramica degli scenari di autorizzazione OAuth 2.0 supportati da Google, e 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 un pattern di base quando accedono a un'API di Google utilizzando OAuth 2.0. A livello generale, segui cinque passaggi:
1. Ottieni le credenziali OAuth 2.0 dalla console API di Google.
Visita la console API di Google per ottenere le credenziali OAuth 2.0, come 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 server web sì.
Devi creare un client OAuth appropriato per la piattaforma su cui verrà eseguita l'app, ad esempio:
-
Per le app Android, utilizza il
Android . -
Per le app iOS e macOS, utilizza
il tipo di client iOS . -
code
Per le app web lato server o JavaScript, utilizza
il tipo di client
Applicazione web . Non utilizzare questo tipo di client per altre applicazioni, ad esempio app native o mobile. - chrome_extension Per le estensioni Chrome, utilizza il tipo di client Estensione Chrome.
-
tv
Per i dispositivi a input limitato, come TV o dispositivi incorporati, utilizza il tipo di client
TV e dispositivi a input limitato . - host Per le interazioni server-to-server, utilizza i service account. Non è richiesto alcun ID client OAuth.
2. Ottieni un token di accesso dal server di autorizzazione di Google.
Prima che la tua applicazione possa accedere ai dati privati utilizzando un'API di Google, deve ottenere un
token di accesso che conceda l'accesso a quell'API. Un singolo token di accesso può concedere diversi livelli
di accesso a più API. Un parametro variabile denominato scope controlla l'insieme
di risorse e operazioni consentite da un token di accesso. Durante la richiesta del 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. Per saperne di più su come effettuare la richiesta, consulta Scenarios e le guide di implementazione dettagliate per ogni tipo di app.
Alcune richieste richiedono un passaggio di autenticazione in cui l'utente accede con il proprio Account Google account. Dopo aver eseguito l'accesso, all'utente viene chiesto se è disposto a concedere una o più autorizzazioni richieste dalla tua applicazione. Questo processo è chiamato 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 l'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, è una best practice richiedere gli ambiti in modo incrementale, al momento in cui è necessario 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 funzionalità della tua applicazione che dipendono dall'accesso a un'API di Google correlata. Disattiva le funzionalità dell'app che non possono funzionare senza l'accesso all'API correlata correlata.
L'ambito incluso nella richiesta potrebbe non corrispondere all'ambito incluso nella risposta, anche
se l'utente ha concesso tutti gli ambiti richiesti. Consulta la documentazione di ogni API di Google per
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 può 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
people.updateContact
dell'API Google People richiede un ambito concesso di https://www.googleapis.com/auth/contacts.
4. Invia il token di accesso a un'API.
Dopo che un'applicazione ottiene un token di accesso, lo invia a un'API di Google in un' intestazione della richiesta HTTP Authorization. È possibile inviare i token come parametri della stringa di query URI, ma non lo consigliamo, perché i parametri URI possono finire nei file di log che non sono completamente sicuri. Inoltre, è una buona pratica REST evitare di creare nomi di parametri URI non necessari.
I token di accesso sono validi solo per l'insieme di operazioni e risorse descritte nel
scope della richiesta di token. Ad esempio, se viene emesso un token di accesso per l'API Google Calendar, non concede l'accesso all'API Contatti Google. Tuttavia, puoi inviare più volte lo stesso token di accesso all'API Google Calendar 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 di 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.
Scenarios
Questi scenari descrivono come utilizzare OAuth 2.0 per richiedere codici di autorizzazione e ottenere token di accesso e di aggiornamento per diversi tipi di applicazioni.
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 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 token.
L'applicazione deve memorizzare il token di aggiornamento per un utilizzo futuro e utilizzare il token di accesso per accedere a un'API di Google. Una volta scaduto il token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.
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 client tramite la console API di Google, specifica che si tratta di un'applicazione installata, quindi seleziona App Android, Estensione Chrome, App iOS, o App desktop come tipo di applicazione.
Il processo genera un ID client e, in alcuni casi, un client secret, che incorpori in il 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 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. L'applicazione deve convalidare il token di accesso prima di includerlo in una richiesta dell'API di Google request. Quando il token scade, l'applicazione ripete il processo.
Facoltativamente, un server di backend può scambiare il codice di autorizzazione con un token di aggiornamento, memorizzandolo in una posizione sicura. Una volta scaduto il token di accesso, il server di backend utilizza il token di aggiornamento per ottenerne uno nuovo per l'applicazione.
Per maggiori dettagli, consulta Autorizzare l'accesso ai dati utente di Google per Android, e OAuth 2.0 per app iOS e desktop.
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 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 dell'API di Google. Quando il token scade, l'applicazione ripete il processo.
Per maggiori dettagli, consulta l'articolo sull'utilizzo di Using OAuth 2.0 per applicazioni lato client.
Applicazioni su dispositivi a input limitato
L'endpoint OAuth 2.0 di Google supporta le applicazioni eseguite su dispositivi a input limitato come console di gioco, videocamere e stampanti.
La sequenza di autorizzazione inizia con l'applicazione che effettua una richiesta di servizio web a un Google URL 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 input più avanzate. L'utente avvia un browser, va all'URL specificato, esegue l'accesso 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 di Google contiene un token di accesso e un token di aggiornamento. L'applicazione deve memorizzare il token di aggiornamento per un utilizzo futuro e utilizzare il token di accesso per accedere a un'API di Google. Una volta scaduto il token di accesso, l'applicazione utilizza il token di aggiornamento per ottenerne uno nuovo.
Per maggiori dettagli, consulta l'articolo sull'utilizzo di OAuth 2.0 per i dispositivi.
Service account
Le API di Google, come l'API Prediction e Google Cloud Storage, possono agire per conto della tua applicazione senza accedere alle informazioni dell'utente. In queste situazioni, la tua applicazione deve dimostrare la propria identità all'API, ma non è necessario il consenso dell'utente. Allo stesso modo, negli scenari aziendali, la tua applicazione può richiedere l'accesso delegato ad alcune risorse.
Per questi tipi di interazioni server-to-server è necessario un service account, ovvero un account che appartiene alla tua applicazione anziché a un singolo utente finale. La tua applicazione chiama le API di Google per conto del service account e non è richiesto il consenso dell'utente. Negli scenari non di service account, la tua applicazione chiama le API di Google per conto degli utenti finali e a volte è richiesto il consenso dell'utente.
Le credenziali di un service account, che ottieni dalla console API di Google, includono un indirizzo email generato univoco, un ID client e almeno una coppia di chiavi pubbliche/private. Utilizza l'ID client e una chiave privata per creare un JWT firmato e costruire una richiesta di token di accesso nel formato appropriato. La tua 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 di Google. Quando il token scade, l'applicazione ripete il processo.
Per maggiori dettagli, consulta la documentazione sui service account.
Dimensioni del token
Le dimensioni dei token possono variare, fino ai seguenti limiti:
I token di accesso restituiti dall' API Security Token Service di Google Cloud hanno una struttura simile ai token di accesso OAuth 2.0 dell'API di Google, ma hanno limiti di dimensioni dei token 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 di conseguenza le dimensioni variabili dei token.
Scadenza del token di aggiornamento
Devi scrivere il codice in modo da 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:
A un progetto Google Cloud Platform 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 con scadenza dopo
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 a service account.
Esiste anche un limite maggiore al numero totale di token di aggiornamento che un account utente o un service account 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 consiste nel 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 di amministratore e utilizzarli per autorizzare alcuni client.
Gestire le policy di controllo della sessione per le organizzazioni Google Cloud
Gli amministratori delle organizzazioni GCP potrebbero richiedere una riautenticazione frequente degli utenti durante l'accesso alle risorse GCP, utilizzando la funzionalità di controllo della sessione di Google Cloud. Questa policy influisce sull'accesso a console Google Cloud, a
Google Cloud SDK (noto anche come gcloud
CLI) e a qualsiasi applicazione OAuth di terze parti che richieda l'ambito Cloud Platform. Se un utente ha una policy di Controllo sessione, alla scadenza della durata della sessione, le chiamate API genereranno 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 una policy di Controllo 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 correttamente riavviando una sessione di autenticazione.
Allo stesso modo, non devi utilizzare o incoraggiare l'utilizzo delle credenziali utente per il deployment server-to-server. Se le credenziali utente vengono sottoposte a deployment su un server per job o operazioni a lunga esecuzione e un cliente applica le policy di Controllo sessione a questi utenti, l'applicazione server non andrà a buon fine perché non sarà possibile riautenticare l'utente alla scadenza della durata della sessione.
Per saperne di più su come aiutare i clienti a eseguire il deployment di questa funzionalità, consulta questo articolo di assistenza per gli 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.
- Libreria di autenticazione Google per Java
- Libreria client API di Google per Python
- Libreria client API di Google per Dart
- Libreria client API di Google per Go
- Libreria client API di Google per .NET
- Libreria client API di Google per Ruby
- Libreria client API di Google per PHP
- Libreria client API di Google per JavaScript
- GTMAppAuth - Libreria client OAuth per Mac e iOS