OAuth 2.0 per app mobile e desktop

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

OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo al contempo nomi utente, password e altre informazioni private. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione consentire agli utenti di archiviare i file nei loro Google Drive.

Le app installate vengono distribuite su singoli dispositivi e si presume che tali app non possono mantenere 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 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 risposte dal server di autorizzazione di Google.

Alternative

Per le app mobile, potresti preferire utilizzare Accedi con Google per Android o iOS. Accedi con Google librerie client gestiscono l'autenticazione e l'autorizzazione dell'utente e possono essere più semplici rispetto al protocollo di livello inferiore descritto qui.

Per le app in esecuzione su dispositivi che non supportano i browser di sistema o con input limitato come TV, console per videogiochi, fotocamere o stampanti, vedi OAuth 2.0 per TV e Dispositivi o Accedi su TV e dispositivi di input limitato.

Librerie ed esempi

Consigliamo le librerie e gli esempi riportati di seguito per aiutarti a implementare il flusso OAuth 2.0 descritti in questo documento:

• Libreria AppAuth per Android
• Libreria AppAuth per iOS
• OAuth per le app: Windows Esempi

Prerequisiti

Abilita le API per il progetto

Qualsiasi applicazione che chiama le API di Google deve abilitare tali API nel .

Per abilitare un'API per il tuo progetto:

1. in .
3. elenca tutte le API disponibili, raggruppate per prodotto famiglia e popolarità. Se l'API che vuoi abilitare non è visibile nell'elenco, utilizza la ricerca per trovarlo o fare clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
4. Seleziona l'API da abilitare e fai clic sul pulsante Abilita.

Crea le credenziali di autorizzazione

Qualsiasi applicazione che utilizza OAuth 2.0 per accedere alle API di Google deve disporre di credenziali di autorizzazione che identificano l'applicazione nel server OAuth 2.0 di Google. I passaggi seguenti spiegano come e creare le credenziali per il tuo progetto. Le applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per il progetto.

2. Fai clic su Crea credenziali > ID client OAuth.
3. Le sezioni seguenti descrivono i tipi di client e i metodi di reindirizzamento utilizzati da Google di autorizzazione in base al server di autorizzazione. Scegli il tipo di client consigliato per applicazione, denominare il client OAuth e impostare gli altri campi del modulo come appropriato.

Identifica gli ambiti di accesso

Gli ambiti consentono all'applicazione di richiedere solo l'accesso alle risorse di cui ha bisogno, permettendo agli utenti di controllare la quantità di accesso che concedono alla tua applicazione. Pertanto, potrebbe essere una relazione inversa tra il numero di ambiti richiesti e la probabilità l'ottenimento del consenso degli utenti.

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 ad accedere.

Il documento sugli 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. La tua applicazione deve avere Consenso prima che possa eseguire una richiesta API di Google che richiede l'autorizzazione dell'utente.

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

Google supporta la chiave di prova per lo scambio del codice. (PKCE) per rendere più sicuro il flusso delle app installate. Viene creato uno strumento di verifica del codice univoco di autorizzazione e il suo valore trasformato, denominato "code_challenge", viene inviato al server di autorizzazione per ottenere il codice di autorizzazione.

Crea lo strumento di verifica del codice

Un code_verifier è una stringa casuale con elevata entropia che utilizza il token caratteri [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 deve avere un'entropia sufficiente per rendere impossibile indovinare il valore.

Crea la verifica del codice

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

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

Esempi di URL di autorizzazione

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

Gli URL sono identici, ad eccezione del valore del parametro redirect_uri. Gli URL contengono anche i parametri response_type e client_id obbligatori come parametro facoltativo state. Ogni URL contiene interruzioni di riga e spazi per 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 richiede il consenso all'utente

In questo passaggio, l'utente deciderà se concedere alla tua applicazione l'accesso richiesto. In questo momento di Google, Google mostra una finestra per il consenso che mostra il nome della tua applicazione e l'API di Google ai servizi a cui chiede l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente e un riepilogo degli ambiti di accesso da concedere. La l'utente può quindi concedere l'accesso a uno o più ambiti richiesti dalla tua applicazione oppure rifiutare la richiesta.

La tua richiesta non deve fare nulla in questa fase perché attende la risposta da Server OAuth 2.0 di Google che indica se è stato concesso un accesso. Questa risposta è spiegata in al passaggio successivo.

Passaggio 4: gestisci la risposta del server OAuth 2.0

Il modo in cui l'applicazione riceve la risposta di autorizzazione dipende 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 di accesso e un token di aggiornamento, come descritto nel passaggio successivo.

Passaggio 5: sostituisci il codice di autorizzazione per aggiornare e accedere token

Per scambiare un codice di autorizzazione con un token di accesso, chiama il metodo 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 accesso di breve durata e un token di aggiornamento.

La risposta contiene i seguenti campi:

Lo snippet seguente mostra un esempio di risposta:

{
  "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

Una volta che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un API per conto di un utente account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. Per farlo, includi il token di accesso in una richiesta all'API mediante l'inclusione di una query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile utilizzare l'intestazione HTTP, in quanto le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi, casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, chiamata all'API Drive Files).

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

Esempi GET HTTP

Una chiamata al drive.files (l'API Drive Files) utilizzando il protocollo Authorization: Bearer potrebbe avere il seguente aspetto. 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

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

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

curl esempi

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

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

Oppure, 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. Tu può aggiornare un token di accesso senza richiedere l'autorizzazione all'utente (anche quando l'utente non presente) se hai richiesto l'accesso offline agli ambiti associati al token.

Per aggiornare un token di accesso, l'applicazione invia un POST HTTPS al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che ha 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 token restituisce un oggetto JSON che contiene un nuovo token di accesso. Lo snippet seguente mostra un esempio risposta:

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

Tieni presente che esistono limiti al numero di token di aggiornamento che verranno emessi. un limite per cliente/utente e un'altra per utente in tutti i client. Salva 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, potrebbe capitare che si verifichino questi limiti, nel qual caso i token di aggiornamento meno recenti. smetterà di funzionare.

Revoca di un token

In alcuni casi un utente potrebbe decidere di revocare l'accesso concesso a un'applicazione. Un utente può revocare l'accesso visitando Impostazioni account. Consulta le Rimuovi sezione "Accesso a siti o app" della sezione Siti e app con accesso al tuo account documento di supporto per ulteriori informazioni.

È anche possibile che un'applicazione revoca in modo programmatico l'accesso concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un 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 concessi all'applicazione vengono rimossi.

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 il token è un token di accesso e presenta un corrispondente, verrà revocato anche il token di aggiornamento.

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

Per approfondire

Best Current Practice di IETF: OAuth 2.0 per App native definisce molte delle best practice qui documentate.