OAuth 2.0 per app per dispositivi mobili e desktop

175 La panoramica riassume i flussi OAuth 2.0 supportati da Google, che possono aiutarti a garantire di aver selezionato il flusso corretto per la tua applicazione.

Questo documento spiega in che modo le applicazioni installate su dispositivi come telefoni, tablet e computer utilizzano gli endpoint OAuth 2.0 di Google per autorizzare l'accesso alle API di Google.

OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione mantenendo privati nomi utente, password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione dagli utenti all'archiviazione dei file nei propri Google Drive.

Le app installate sono distribuite su singoli dispositivi e si presume che queste app non possano mantenere i secret. Possono accedere alle API di Google mentre l'utente è presente nell'app o quando è in esecuzione in background.

Questo flusso di autorizzazione è simile a quello utilizzato per le applicazioni server web. La differenza principale è che le app installate devono aprire il browser di sistema e fornire un URI di reindirizzamento locale per gestire le risposte del server di autorizzazione di Google.

Alternative

Per le app per dispositivi mobili, potete utilizzare l'opzione Accedi con Google per Android o iOS. Le librerie client di Accedi con Google gestiscono l'autenticazione e l'autorizzazione degli utenti e possono essere più semplici da implementare rispetto al protocollo di livello inferiore descritto qui.

Per le app eseguite su dispositivi che non supportano il browser di sistema o con funzionalità di input limitate, ad esempio TV, console per videogiochi, fotocamere o stampanti, consulta OAuth 2.0 per TV e dispositivi o Accesso alle TV e ai dispositivi di input limitati.

Librerie ed esempi

Ti consigliamo le seguenti librerie ed esempi per aiutarti a implementare il flusso OAuth 2.0 descritto in questo documento:

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiami le API di Google deve abilitarle nel API Console.

Per abilitare un'API per il tuo progetto:

  1. Open the API Library in Google API Console.
  2. If prompted, select a project, or create a new one.
  3. L'elenco API Library elenca tutte le API disponibili, raggruppate per famiglia di prodotti e popolarità. Se l'API che vuoi attivare non è visibile nell'elenco, utilizza la funzione di ricerca per trovarla o fai clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
  4. Seleziona l'API che vuoi attivare, quindi fai clic sul pulsante Abilita.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Crea credenziali di autorizzazione

Qualsiasi applicazione che utilizzi OAuth 2.0 per accedere alle API di Google deve disporre di credenziali di autorizzazione che identifichino l'applicazione sul server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il progetto. Le tue applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per quel progetto.

  1. Go to the Credentials page.
  2. Fai clic su Crea credenziali > ID client OAuth.
  3. Le sezioni seguenti descrivono i tipi di client e i metodi di reindirizzamento supportati dal server di autorizzazione di Google. Scegli il tipo di client consigliato per la tua applicazione, assegna un nome al client OAuth e imposta gli altri campi nel modulo in base alle tue esigenze.

Schema URI personalizzato (Android, iOS, UWP)

Si consiglia uno schema URI personalizzato per le app Android, le app per iOS e le app UWP (Universal Windows Platform).

Android
  1. Seleziona il tipo di applicazione Android.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nel Credentials page del tuo progetto per identificare il client.
  3. Inserisci il nome del pacchetto della tua app Android. Questo valore viene definito nell'attributo package dell'elemento <manifest> nel file manifest dell'app.
  4. Inserisci l'impronta digitale del certificato di firma SHA-1 della distribuzione dell'app.
    • Se la tua app usa la firma dell'app di Google Play, copia l'impronta digitale SHA-1 dalla pagina di firma dell'app di Play Console.
    • Se gestisci autonomamente il tuo archivio chiavi e le chiavi di firma, utilizza l'utilità keytool inclusa in Java per stampare le informazioni dei certificati in un formato leggibile. Copia il valore di SHA1 nella sezione Certificate fingerprints dell'output di keytool. Per ulteriori informazioni, consulta l'articolo sull'autenticazione del client nella documentazione delle API di Google per Android.
  5. Fai clic su Crea.
iOS
  1. Seleziona il tipo di applicazione iOS.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nel Credentials page del tuo progetto per identificare il client.
  3. Inserisci l'identificatore bundle per la tua app. L'ID bundle è il valore della chiave CFBundleIdentifier nel file di risorse dell'elenco di proprietà dell'app (info.plist). Il valore viene visualizzato più comunemente nel riquadro Generale o nel riquadro Firma e funzionalità dell'editor di progetto Xcode. L'ID bundle viene visualizzato anche nella sezione Informazioni generali della pagina Informazioni app dell'app sul sito App Store di Apple.
  4. (facoltativo)

    Inserisci l'ID App Store della tua app se l'app è pubblicata nell'App Store di Apple. L'ID store è una stringa numerica inclusa in ogni URL dell'Apple App Store.

    1. Apri l'app Apple App Store sul tuo dispositivo iOS o iPadOS.
    2. Cerca la tua app.
    3. Seleziona il pulsante Condividi (quadrato e simbolo a freccia su).
    4. Seleziona Copia link.
    5. Incolla il link in un editor di testo. L'ID App Store è la parte finale dell'URL.

      Esempio: https://apps.apple.com/app/google/id284815942

  5. (facoltativo)

    Inserisci il tuo ID team. Per ulteriori informazioni, consulta Individuare l'ID team nella documentazione dell'account sviluppatore Apple.

  6. Fai clic su Crea.
UWP
  1. Seleziona il tipo di applicazione Universal Windows Platform.
  2. Inserisci un nome per il client OAuth. Questo nome viene visualizzato nel Credentials page del tuo progetto per identificare il client.
  3. Inserisci l'ID Microsoft Store di 12 caratteri della tua app. Puoi trovare questo valore nel Centro partner di Microsoft nella pagina Identità app nella sezione Gestione app.
  4. Fai clic su Crea.

Per le app UWP, lo schema URI personalizzato non può superare i 39 caratteri.

Indirizzo IP di loopback (macOS, Linux, Windows desktop)

Per ricevere il codice di autorizzazione tramite questo URL, la tua applicazione deve essere in ascolto sul server web locale. Ciò è possibile su molte piattaforme, ma non su tutte. Tuttavia, se la tua piattaforma lo supporta, questo è il meccanismo consigliato per ottenere il codice di autorizzazione.

Quando la tua app riceve la risposta di autorizzazione, per la migliore usabilità dovrebbe rispondere mostrando una pagina HTML che indica all'utente di chiudere il browser e tornare all'app.

Utilizzo consigliato App per macOS, Linux e Windows per desktop (ma non per Universal Windows Platform)
Valori dei moduli Imposta il tipo di applicazione su App desktop.

Copia/incolla manuale

Identifica gli ambiti di accesso

Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse necessarie, permettendo al tempo stesso agli utenti di controllare la quantità di accesso da loro concessa. Pertanto, potrebbe esserci una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

Prima di iniziare a implementare l'autorizzazione OAuth 2.0, ti consigliamo di identificare gli ambiti a cui la tua app dovrà avere l'autorizzazione di accesso.

Il documento Ambiti API OAuth 2.0 contiene un elenco completo di ambiti che potresti utilizzare per accedere alle API di Google.

Ottenere i token di accesso OAuth 2.0

I seguenti passaggi mostrano in che modo la tua applicazione interagisce con il server OAuth 2.0 di Google per ottenere il consenso di un utente a eseguire una richiesta API per conto dell'utente. La tua applicazione deve avere questo consenso prima di poter eseguire una richiesta API di Google che richiede l'autorizzazione dell'utente.

Passaggio 1: genera una verifica del codice e verifica

Google supporta il protocollo Proof Key for Code Exchange (PKCE) per rendere più sicuro il flusso delle app installate. Viene creato uno strumento di verifica del codice univoco per ogni richiesta di autorizzazione e il relativo valore trasformato, denominato "code_challenge", viene inviato al server di autorizzazione per ottenere il codice di autorizzazione.

Creare lo strumento di verifica del codice

code_verifier è una stringa casuale crittografica ad alta entropia che utilizza i caratteri non riservati [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", con una lunghezza minima di 43 caratteri e una lunghezza massima di 1 caratteri.

Lo strumento di verifica del codice deve avere un'entropia sufficiente per rendere inattuabile il valore.

Creare un test di codice

Sono supportati due metodi per la creazione della verifica del codice.

Metodi di generazione di verifica tramite codice
S256 (consigliato) La verifica del codice è l'hash SHA256 con codifica Base64 nell'URL (senza padding) dello strumento di verifica del codice.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
semplice La verifica del codice è uguale a quella dello strumento di verifica del codice generato sopra.
code_challenge = code_verifier

Passaggio 2: invia una richiesta al server OAuth 2.0 di Google

Per ottenere l'autorizzazione dell'utente, invia una richiesta al server di autorizzazione di Google all'indirizzo https://accounts.google.com/o/oauth2/v2/auth. Questo endpoint gestisce la ricerca di sessioni attive, autentica l'utente e ottiene il consenso dell'utente. L'endpoint è accessibile solo su SSL e rifiuta le connessioni HTTP (non SSL).

Il server di autorizzazione supporta i seguenti parametri di stringa di query per le applicazioni installate:

Parametri
client_id Obbligatorio

L'ID client della tua applicazione. Puoi trovare questo valore in API Console Credentials page.

redirect_uri Obbligatorio

Determina la modalità di risposta del server di autorizzazione di Google alla tua app. Esistono diverse opzioni di reindirizzamento disponibili per le app installate e dovrai impostare le tue credenziali di autorizzazione con un determinato metodo di reindirizzamento.

Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, configurato nel API Consoledi Credentials page. Se questo valore non corrisponde a un URI autorizzato, riceverai un errore redirect_uri_mismatch.

La tabella seguente mostra il valore del parametro redirect_uri appropriato per ogni metodo:

Valori redirect_uri
Schema URI personalizzato com.example.app:redirect_uri_path

o

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app è la notazione DNS inversa di un dominio sotto il tuo controllo. Per essere valido, lo schema personalizzato deve contenere un punto.
  • com.googleusercontent.apps.123 è la notazione DNS inversa dell'ID client.
  • redirect_uri_path è un componente del percorso facoltativo, come /oauth2redirect. Tieni presente che il percorso deve iniziare con una singola barra, diversa dal normale URL HTTP.
Indirizzo IP loopback http://127.0.0.1:port oppure http://[::1]:port

Esegui una query sulla piattaforma per trovare l'indirizzo IP di loopback pertinente e avvia un listener HTTP su una porta disponibile casuale. Sostituisci port con il numero di porta effettivo della tua app.

Tieni presente che il supporto dell'opzione di reindirizzamento degli indirizzi IP di loopback sulle app per dispositivi mobili è DEPRECATO.

response_type Obbligatorio

Determina se l'endpoint di Google OAuth 2.0 restituisce un codice di autorizzazione.

Imposta il valore parametro su code per le applicazioni installate.

scope Obbligatorio

Un elenco di ambiti delimitati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori informano la schermata di consenso che Google mostra all'utente.

Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse necessarie e permette agli utenti di controllare la quantità di accesso da concedere all'applicazione. Pertanto, esiste una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

code_challenge Consigliato

Specifica un valore code_verifier codificato che verrà utilizzato come verifica lato server durante lo scambio del codice di autorizzazione. Per ulteriori informazioni, consulta la sezione sulla verifica del codice sopra riportata.

code_challenge_method Consigliato

Specifica il metodo utilizzato per codificare un code_verifier che verrà utilizzato durante lo scambio di codice di autorizzazione. Questo parametro deve essere utilizzato con il parametro code_challenge descritto sopra. Il valore predefinito di code_challenge_method è plain se non è presente nella richiesta che include un elemento code_challenge. Gli unici valori supportati per questo parametro sono S256 o plain.

state Consigliato

Specifica qualsiasi valore stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione. Il server restituisce il valore esatto che invii come coppia di name=value nell'identificatore di frammento dell'URL (#) di redirect_uri dopo che l'utente ha acconsentito o negato la richiesta di accesso della tua applicazione.

Puoi utilizzare questo parametro per diversi scopi, ad esempio indirizzare l'utente alla risorsa corretta nell'applicazione, inviare nonce e mitigare la falsificazione di richieste tra siti. Poiché redirect_uri può essere indovinato, l'utilizzo di un valore state può aumentare la garanzia che una connessione in entrata sia il risultato di una richiesta di autenticazione. Se generi una stringa casuale o codifica l'hash di un cookie o di un altro valore che acquisisce lo stato del client, puoi convalidare la risposta per assicurarti inoltre che la richiesta e la risposta abbiano origine nello stesso browser, fornendo protezione contro attacchi come la falsificazione di richieste tra siti. Consulta la documentazione OpenID Connect per un esempio di come creare e confermare un token state.

login_hint Facoltativo

Se la tua applicazione sa quale utente sta tentando di eseguire l'autenticazione, può utilizzare questo parametro per fornire un suggerimento al server di autenticazione Google. Il server utilizza il suggerimento per semplificare il flusso di accesso precompilando il campo dell'email nel modulo di accesso o selezionando la sessione multi-accesso appropriata.

Imposta il valore del parametro su un indirizzo email o un identificatore sub, equivalente all'ID Google dell'utente.

Esempi di URL di autorizzazione

Le schede riportate di seguito mostrano degli URL di autorizzazione di esempio per le diverse opzioni dell'URI di reindirizzamento.

Gli URL sono identici, tranne per il valore del parametro redirect_uri. Gli URL contengono anche i parametri obbligatori response_type e client_id, nonché il parametro facoltativo state. Ogni URL contiene interruzioni di riga e spazi per una maggiore leggibilità.

Schema URI personalizzato

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

Indirizzo IP loopback

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Passaggio 3: Google chiede all'utente il consenso

In questo passaggio, l'utente decide se concedere alla tua applicazione l'accesso richiesto. In questa fase, Google mostra una finestra di consenso che mostra il nome della tua applicazione e i servizi API di Google a cui richiede l'accesso con le credenziali di autorizzazione dell'utente e un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire a concedere l'accesso a uno o più ambiti richiesti dalla tua applicazione o rifiutare la richiesta.

In questa fase non è necessario fare nulla perché attende la risposta dal server OAuth 2.0 di Google per indicare se è stato concesso qualsiasi accesso. Questa risposta è spiegata nel passaggio successivo.

Errori

Le richieste inviate all'endpoint di autorizzazione OAuth 2.0 di Google potrebbero mostrare messaggi di errore rivolti agli utenti anziché nei flussi di autenticazione e autorizzazione previsti. Di seguito sono riportati i codici di errore comuni e le relative soluzioni.

admin_policy_enforced

L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dei criteri del suo amministratore di Google Workspace. Consulta l'articolo del Centro assistenza per gli amministratori di Google Workspace Controllare quali app di terze parti e AMP possono accedere ai dati di Google Workspace per saperne di più su come un amministratore può limitare l'accesso a tutti gli ambiti o ad ambiti sensibili e con restrizioni finché non viene concesso esplicitamente l'accesso al tuo ID client OAuth.

disallowed_useragent

L'endpoint di autorizzazione viene visualizzato all'interno di uno user-agent incorporato che non è consentito dai criteri OAuth 2.0 di Google.

Android

Gli sviluppatori Android potrebbero vedere questo messaggio di errore quando aprono le richieste di autorizzazione in android.webkit.WebView. Gli sviluppatori dovrebbero invece utilizzare librerie Android come Accedi con Google per Android o AppAuth per Android tramite OpenID Foundation.

Gli sviluppatori web potrebbero riscontrare questo errore quando un'app Android apre un link web generale in uno user-agent incorporato e un utente accede all'endpoint di autorizzazione OAuth 2.0 di Google dal tuo sito. Gli sviluppatori dovrebbero consentire l'apertura dei link generali nel gestore di link predefinito del sistema operativo, che include sia i gestori di link per app Android sia l'app predefinita del browser. Anche la libreria Schede personalizzate di Android è un'opzione supportata.

iOS

Gli sviluppatori di iOS e macOS potrebbero riscontrare questo errore quando aprono le richieste di autorizzazione in WKWebView. Gli sviluppatori dovrebbero invece utilizzare librerie iOS come Google Accedi per iOS o OpenID Foundation's AppAuth per iOS.

Gli sviluppatori web potrebbero riscontrare questo errore quando un'app per iOS o macOS apre un link web generale in uno user agent incorporato e un utente accede all'endpoint di autorizzazione OAuth 2.0 di Google dal tuo sito. Gli sviluppatori dovrebbero consentire l'apertura dei link generali nel gestore di link predefinito del sistema operativo, che include sia i gestori di link universali sia l'app predefinita del browser. Anche la libreria SFSafariViewController è un'opzione supportata.

org_internal

L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una specifica organizzazione Google Cloud. Per ulteriori informazioni su questa opzione di configurazione, consulta la sezione Tipo di utente nell'articolo del Centro assistenza dedicato alla configurazione della schermata di consenso OAuth.

redirect_uri_mismatch

Il valore redirect_uri inviato nella richiesta di autorizzazione non corrisponde a un URI di reindirizzamento autorizzato per l'ID client OAuth. Rivedi gli URI di reindirizzamento autorizzati nella Google API Console Credentials page.

Il passaggio redirect_uri potrebbe non essere valido per il tipo di client.

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui la tua applicazione riceve la risposta di autorizzazione dipende dallo schema dell'URI di reindirizzamento che utilizza. Indipendentemente dallo schema, la risposta conterrà un codice di autorizzazione (code) o un errore (error). Ad esempio, error=access_denied indica che l'utente ha rifiutato la richiesta.

Se l'utente concede l'accesso alla tua applicazione, puoi scambiare il codice di autorizzazione con un token di accesso e un token di aggiornamento, come descritto nel passaggio successivo.

Passaggio 5: codice di autorizzazione di Exchange per i token di aggiornamento e accesso

Per scambiare un codice di autorizzazione con un token di accesso, chiama l'endpoint https://oauth2.googleapis.com/token e imposta i seguenti parametri:

Campi
client_id L'ID client ottenuto da API Console Credentials page.
client_secret Il client secret ottenuto da API Console Credentials page.
code Il codice di autorizzazione restituito dalla richiesta iniziale.
code_verifier Lo strumento di verifica del codice che hai creato nel passaggio 1.
grant_type Come definito nella specifica OAuth 2.0, questo valore di campo deve essere impostato su authorization_code.
redirect_uri Uno degli URI di reindirizzamento elencati per il tuo progetto in API ConsoleCredentials page per client_id.

Il seguente snippet mostra una richiesta di esempio:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google risponde a questa richiesta restituisce un oggetto JSON contenente un token di accesso di breve durata e un token di aggiornamento.

La risposta contiene i seguenti campi:

Campi
access_token Il token che la tua applicazione invia per autorizzare una richiesta API di Google.
expires_in La durata rimanente del token di accesso in secondi.
id_token Nota: questa proprietà viene restituita solo se la tua richiesta includeva un ambito di identità, come openid, profile o email. Il valore è un JSON Web Token (JWT) che contiene informazioni sull'identità firmate digitalmente sull'utente.
refresh_token Un token che puoi utilizzare per ottenere un nuovo token di accesso. I token di aggiornamento sono validi finché l'utente non revoca l'accesso. Tieni presente che i token di aggiornamento vengono sempre restituiti per le applicazioni installate.
scope Gli ambiti di accesso concessi da access_token espressi come elenco di stringhe sensibili alle maiuscole.
token_type Il tipo di token restituito. Al momento, il valore di questo campo è sempre impostato su Bearer.

Il seguente snippet mostra una risposta di esempio:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Chiamata delle API di Google

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API Google per conto di un determinato account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. A tale scopo, includi il token di accesso in una richiesta all'API includendo un parametro di ricerca access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile l'intestazione HTTP, perché le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, quando chiami l'API Drive Files).

Puoi provare tutte le API di Google e visualizzarne gli ambiti in OAuth 2.0 Playground.

Esempi GET HTTP

Una chiamata all'endpoint drive.files (l'API Drive File) che utilizza l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare il tuo token di accesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Ecco una chiamata alla stessa API per l'utente autenticato utilizzando il parametro della stringa di query access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Esempi di curl

Puoi testare questi comandi con l'applicazione a riga di comando curl. Ecco un esempio che utilizza l'opzione di intestazione HTTP (opzione preferita):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

In alternativa, puoi scegliere l'opzione del parametro della stringa di query:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Aggiornamento di un token di accesso

I token di accesso scadono periodicamente e diventano credenziali non valide per una richiesta API correlata. Puoi aggiornare un token di accesso senza chiedere l'autorizzazione all'utente (anche quando non è presente) se hai richiesto l'accesso offline agli ambiti associati al token.

Per aggiornare un token di accesso, l'applicazione invia una richiesta HTTPS POST al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che include i seguenti parametri:

Campi
client_id L'ID client ottenuto da API Console.
client_secret Il client secret ottenuto da API Console. client_secret non è applicabile alle richieste dei client registrati come applicazioni Android, iOS o Chrome.
grant_type Come definito nella specifica OAuth 2.0, il valore di questo campo deve essere impostato su refresh_token.
refresh_token Il token di aggiornamento restituito dallo scambio di codice di autorizzazione.

Il seguente snippet mostra una richiesta di esempio:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Se l'utente non ha revocato l'accesso concesso all'applicazione, il server token restituisce un oggetto JSON contenente un nuovo token di accesso. Il seguente snippet mostra una risposta di esempio:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Tieni presente che esiste un limite al numero di token di aggiornamento che verranno emessi: un limite per combinazione client/utente e un altro per utente in tutti i client. Dovresti salvare i token di aggiornamento nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se la tua applicazione richiede troppi token di aggiornamento, questi potrebbero superare questi limiti. In questo caso, i token di aggiornamento meno recenti smetteranno di funzionare.

Revoca di un token

In alcuni casi, un utente potrebbe voler revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando le impostazioni dell'account. Per ulteriori informazioni, consulta la sezione Rimuovere il sito o l'accesso alle app del sito di terze parti e delle app con accesso al tuo account.

È inoltre possibile che un'applicazione revochi in modo programmatico l'accesso concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse API richieste dall'app sono cambiate in modo significativo. In altre parole, una parte del processo di rimozione può includere una richiesta API per garantire la rimozione delle autorizzazioni precedentemente concesse all'applicazione.

Per revocare un token in modo programmatico, l'applicazione invia una richiesta a https://oauth2.googleapis.com/revoke e include il token come parametro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Il token può essere un token di accesso o un token di aggiornamento. Se è un token di accesso e ha un token di aggiornamento corrispondente, verrà revocato anche il token di aggiornamento.

Se la revoca viene elaborata correttamente, il codice di stato HTTP della risposta è 200. Per le condizioni di errore, viene restituito un codice di stato HTTP 400 insieme a un codice di errore.

Per approfondire

La best practice di IETF OAuth 2.0 per app native definisce molte delle best practice qui descritte.