Google si impegna a promuovere l'equità razziale per le comunità nere. Vedi come.

Utilizzo di OAuth 2.0 per accedere alle API di Google

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

Per cominciare, è necessario ottenere le credenziali del client OAuth 2.0 dal Google API Console . Quindi la tua applicazione client richiede un token di accesso dal server di autorizzazione di Google, estrae un token dalla risposta e invia il token all'API di Google a cui desideri accedere. Per una dimostrazione interattiva di utilizzare OAuth 2.0 con Google (tra cui la possibilità di utilizzare le proprie credenziali client), sperimentare con l'OAuth 2.0 Playground .

Questa pagina offre una panoramica degli scenari di autorizzazione OAuth 2.0 supportati da Google e fornisce collegamenti a contenuti più dettagliati. Per ulteriori informazioni sull'uso OAuth 2.0 per l'autenticazione, vedere OpenID Connect .

Passaggi di base

Tutte le applicazioni seguono uno schema di base quando accedono a un'API di Google utilizzando OAuth 2.0. Ad alto livello, segui cinque passaggi:

1. Ottenere OAuth 2.0 credenziali dal Google API Console.

Visita il Google API Console per ottenere le credenziali OAuth 2.0 come ad esempio un segreto ID client e client che sono noti a Google e l'applicazione. Il set di valori varia in base al tipo di applicazione che stai creando. Ad esempio, un'applicazione JavaScript non richiede un segreto, ma un'applicazione server Web sì.

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 tale API. Un singolo token di accesso può concedere vari gradi di accesso a più API. Un parametro variabile denominata scope controlla l'insieme di risorse e operazioni che un token di accesso permessi. Durante la richiesta di accesso token, l'applicazione invia uno o più valori nel scope dei parametri.

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 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 effettuato l'accesso, all'utente viene chiesto se è disposto a concedere una o più autorizzazioni richieste dall'applicazione. Questo processo è chiamato l'autorizzazione 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 è consigliabile 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 al calendario"; vedi l'autorizzazione incrementale .

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

Confronta gli ambiti inclusi nella risposta del token di accesso agli ambiti richiesti per accedere a funzioni e funzionalità della tua applicazione in base all'accesso a un'API di Google correlata. Disattiva tutte le funzionalità della tua app che non possono funzionare senza l'accesso alla relativa API.

L'ambito incluso nella richiesta potrebbe non corrispondere all'ambito incluso nella risposta, anche se l'utente ha concesso tutti gli ambiti richiesti. Fare riferimento alla documentazione per ciascuna 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 di Google La gente può restituire un ambito di https://www.googleapis.com/auth/contacts quando un app ha richiesto un utente autorizzare un ambito di https://www.google.com/m8/feeds/ ; il metodo API di Google Persone people.updateContact richiede un ambito concesso di https://www.googleapis.com/auth/contacts .

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

Dopo un'applicazione ottiene un token di accesso, invia il token di un'API di Google in una richiesta HTTP di autorizzazione . È possibile inviare token come parametri della stringa di query URI, ma non lo consigliamo, perché i parametri URI possono finire in file di registro non completamente sicuri. Inoltre, è buona pratica REST evitare di creare nomi di parametri URI non necessari. Tieni presente che il supporto per le stringhe di query verrà ritirato il 1° giugno 2021.

Token di accesso sono validi solo per l'insieme delle operazioni e delle risorse descritte nel scope della richiesta token. Ad esempio, se viene emesso un token di accesso per l'API di Google Calendar, non concede l'accesso all'API dei contatti di Google. Tuttavia, puoi inviare quel token di accesso all'API di Google Calendar più volte per operazioni simili.

5. Aggiornare il token di accesso, se necessario.

I token di accesso hanno una durata limitata. Se la tua applicazione necessita dell'accesso 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 del server Web

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

La sequenza di autorizzazione inizia quando la tua 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 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.

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

Per dettagli, vedere Utilizzo di OAuth 2.0 per le applicazioni Web Server .

Applicazioni installate

L'endpoint Google OAuth 2.0 supporta le applicazioni installate su dispositivi come computer, dispositivi mobili e tablet. Quando si crea un ID cliente attraverso il Google API Console , specificare che si tratta di un'applicazione installata, quindi selezionare Android, Chrome app, iOS, universale di Windows Platform (UWP), o desktop app come il tipo di applicazione.

Il processo risulta in un ID client e, in alcuni casi, in un segreto client, che incorpori nel codice sorgente della tua applicazione. (In questo contesto, il segreto del client non è ovviamente trattato come un segreto.)

La sequenza di autorizzazione inizia quando la tua 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 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.

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

Per dettagli, vedere Utilizzo di OAuth 2.0 per le applicazioni installate .

Applicazioni lato client (JavaScript)

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

La sequenza di autorizzazione inizia quando la tua 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 API di Google. Quando il token scade, l'applicazione ripete il processo.

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

Per dettagli, vedere Utilizzo di OAuth 2.0 per le applicazioni client-side .

Applicazioni su dispositivi con input limitato

L'endpoint Google OAuth 2.0 supporta 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 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 dispositivo o computer separato con funzionalità di input più avanzate. L'utente avvia un browser, accede all'URL specificato, effettua il login e inserisce il codice.

Nel frattempo, l'applicazione esegue il polling di un URL di Google a un intervallo specificato. Dopo che l'utente ha approvato l'accesso, la risposta dal server di Google contiene un token di accesso e un token di aggiornamento. L'applicazione deve archiviare 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.

L'utente accede su un dispositivo separato dotato di browser

Per dettagli, vedere Utilizzo di OAuth 2.0 per dispositivi .

Account di servizio

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

Per questi tipi di interazioni server-to-server di avete bisogno di un account di servizio, che è un account che appartiene alla vostra applicazione invece che 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. (Negli scenari senza account di servizio, l'applicazione chiama le API di Google per conto degli utenti finali e talvolta è richiesto il consenso dell'utente.)

Le credenziali di un account di servizio, che si ottengono dalla Google API Console, includono un indirizzo di posta elettronica generato che è unico, un ID cliente, e / coppia di chiavi privata almeno una pubblica. Utilizzi l'ID client e una chiave privata per creare un JWT firmato e costruire 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. Quando il token scade, l'applicazione ripete il processo.

La tua applicazione server utilizza un JWT per richiedere un token dal server di autorizzazione di Google, quindi utilizza il token per chiamare un endpoint dell'API di Google. Nessun utente finale è coinvolto.

Per i dettagli, consultare la documentazione di servizio-conto .

Dimensione del gettone

I token possono variare di dimensioni, fino ai seguenti limiti:

  • Codici di autorizzazione: 256 byte
  • Token di accesso: 2048 byte
  • Aggiorna token: 512 byte

Token di accesso restituito dal di Google Cloud API servizio token di sicurezza sono strutturati in modo simile a Google API OAuth token di accesso 2.0, ma hanno diversi limiti di dimensione token. Per i dettagli, consultare la documentazione delle API .

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

Aggiorna scadenza token

È necessario scrivere il codice per prevedere la possibilità che un token di aggiornamento concesso possa non funzionare più. Un token di aggiornamento potrebbe smettere di funzionare per uno di questi 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 un numero massimo di token di aggiornamento (live) concessi.
  • L'utente appartiene a un'organizzazione di Google Cloud Platform che ha in vigore criteri di controllo della sessione.

Un progetto Google Cloud Platform con una schermata di consenso OAuth configurata per un tipo di utente esterno e uno stato di pubblicazione "Test" riceve un token di aggiornamento che scade tra 7 giorni.

Attualmente esiste un limite di 50 token di aggiornamento per account Google per ID client OAuth 2.0. Se viene raggiunto il limite, la creazione di un nuovo token di aggiornamento invalida automaticamente il token di aggiornamento più vecchio 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 è necessario autorizzare più programmi, macchine, o dispositivi, una soluzione è quella di limitare il numero di client di autorizzare ogni account Google per 15 o 20. Se sei un amministratore di Google di lavoro , è possibile creare altri utenti con privilegi amministrativi e usarli per autorizzare alcuni dei clienti.

Gestione dei criteri di controllo della sessione per le organizzazioni di Google Cloud Platform (GCP)

Gli amministratori di organizzazioni GCP potrebbero richiedere frequenti nuova autenticazione degli utenti mentre questi si collegano a risorse GCP, utilizzando la funzione di controllo di sessione di Google Cloud . Ciò influisce criteri di accesso a Google Cloud Console, il Google Cloud SDK (noto anche come il CLI gcloud), e tutte le applicazioni OAuth di terze parti che richiede l'ambito Cloud Platform. Se un utente ha una politica di controllo di sessione in luogo poi alla scadenza della durata della sessione, le chiamate API saranno errore fuori simile a quello che succederebbe se il token di aggiornamento è stato revocato - la chiamata non verrà effettuata 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 una politica di controllo della sessione. Poiché la durata delle sessioni può essere molto limitata (tra 1 ora e 24 ore), questo scenario deve essere gestito correttamente riavviando una sessione di autenticazione.

Allo stesso modo, non è necessario utilizzare o incoraggiare l'uso di credenziali utente per la distribuzione da server a server. Se le credenziali dell'utente vengono distribuite su un server per lavori o operazioni di lunga durata e un cliente applica criteri di controllo della sessione su tali utenti, l'applicazione server avrà esito negativo poiché non sarà possibile riautenticare l'utente alla scadenza della durata della sessione.

Per ulteriori informazioni su come aiutare i clienti a implementare questa funzione, fare riferimento a questo articolo della guida admin-focalizzato.

Librerie clienti

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