OAuth 2.0 per app mobile e desktop

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 i propri nomi utente, le password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione degli utenti ad archiviare file nei propri Google Drive.

Le app installate vengono distribuite ai singoli dispositivi e si presume che non possano conservare i secret. Possono accedere alle API di Google mentre l'utente è presente nell'app o quando l'app è 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 mobile, potresti utilizzare Accedi con Google per Android o iOS. Le librerie client di Accedi con Google gestiscono l'autenticazione e l'autorizzazione degli utenti e potrebbero essere più semplici da implementare rispetto al protocollo di livello inferiore descritto qui.

Per le app eseguite su dispositivi che non supportano un 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 su TV e dispositivi di immissione limitati.

Librerie ed esempi

Consigliamo le librerie e gli esempi seguenti per aiutarti a implementare il flusso OAuth 2.0 descritto in questo documento:

• Libreria AppAuth per Android
• Libreria AppAuth per iOS
• OAuth per app: Windows Samples

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiama le API di Google deve abilitare queste API in 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' 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 oppure fai clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
4. Seleziona l'API che vuoi attivare e 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 utilizza OAuth 2.0 per accedere alle API di Google deve avere credenziali di autorizzazione che identificano l'applicazione sul server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il progetto. Le applicazioni potranno quindi utilizzare le credenziali per accedere alle API che hai abilitato per il 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 del modulo in base alle necessità.

Identificare gli ambiti di accesso

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare la quantità di accesso che concederanno all'applicazione. Pertanto, potrebbe esistere 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 applicazione dovrà accedere.

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

Ottenere i token di accesso OAuth 2.0

I passaggi seguenti 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 suo conto. L'applicazione deve avere questo consenso prima di poter eseguire una richiesta API di Google che richiede l'autorizzazione dell'utente.

Passaggio 1: genera uno strumento di verifica del codice e una verifica del codice

Google supporta il protocollo PKCE (Proof Key for Code Exchange) per rendere più sicuro il flusso dell'app installata. Per ogni richiesta di autorizzazione viene creato uno strumento di verifica del codice univoco e il suo valore trasformato, chiamato "code_challenge", viene inviato al server di autorizzazione per ottenere il codice di autorizzazione.

Crea lo strumento di verifica del codice

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

Lo strumento di verifica del codice dovrebbe avere un'entropia sufficiente a rendere impossibile indovinare il valore.

Crea la verifica del codice

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

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

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 delle sessioni attive, autentica l'utente e ottiene il suo consenso. L'endpoint è accessibile solo tramite SSL e rifiuta le connessioni HTTP (non SSL).

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

URL di autorizzazione di esempio

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

Gli URL sono identici, ad eccezione del 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 favorire la leggibilità.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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 all'applicazione l'accesso richiesto. In questa fase, Google mostra una finestra per il consenso che mostra il nome dell'applicazione e i servizi API di Google a cui richiede l'autorizzazione per accedere con le credenziali di autorizzazione dell'utente, oltre a un riepilogo degli ambiti dell'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.

L'applicazione non deve fare nulla in questa fase perché attende la risposta dal server OAuth 2.0 di Google che indica se è stato concesso qualsiasi accesso. Questa risposta è spiegata nel passaggio seguente.

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui l'applicazione riceve la risposta di autorizzazione dipende dallo schema dell'URI di reindirizzamento utilizzato. 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: scambia il codice di autorizzazione con i token di aggiornamento e di 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:

Lo snippet seguente 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 restituendo un oggetto JSON che contiene un token di accesso di breve durata e un token di aggiornamento.

La risposta contiene i seguenti campi:

Lo snippet seguente 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 alle API di Google

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API di Google per conto di un determinato account utente se gli ambiti di accesso richiesti dall'API sono stati concessi. A questo scopo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer di intestazione HTTP Authorization. Quando possibile, è preferibile utilizzare 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 di HTTP GET

Una chiamata all'endpoint drive.files (l'API Drive Files) utilizzando l'intestazione HTTP Authorization: Bearer potrebbe essere simile alla seguente. Tieni presente che devi specificare un tuo token di accesso:

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

Di seguito è riportata 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 in cui viene utilizzata l'opzione dell'intestazione HTTP (opzione preferita):

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

In alternativa, 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 all'utente l'autorizzazione (anche quando l'utente non è presente) se hai richiesto l'accesso offline agli ambiti associati al token.

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

Lo snippet seguente 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 dei token restituisce un oggetto JSON contenente un nuovo token di accesso. Lo snippet seguente 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 sono previsti limiti al numero di token di aggiornamento che verranno emessi: un limite per combinazione client/utente e un altro per utente in tutti i client. Devi salvare i token di aggiornamento nello spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se l'applicazione richiede troppi token di aggiornamento, potrebbe raggiungere questi limiti, nel qual 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 saperne di più, consulta la sezione relativa alla rimozione dell'accesso di siti o app del documento di assistenza Siti e app di terze parti con accesso al tuo account.

Un'applicazione può anche revocare in modo programmatico l'accesso che le è stato concesso. La revoca programmatica è importante nelle istanze in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse API richieste da un'app sono cambiate in modo significativo. In altre parole, parte del processo di rimozione può includere una richiesta API per garantire che le autorizzazioni concesse in precedenza all'applicazione vengano rimosse.

Per revocare in modo programmatico un token, 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 il token è 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 attuale di IETF OAuth 2.0 per le app native stabilisce molte delle best practice documentate qui.