OAuth 2.0 per app mobile e desktop

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

OAuth 2.0 consente agli utenti di condividere dati specifici con un'applicazione, mantenendo privati i nomi utente, le password e altre informazioni. Ad esempio, un'applicazione può utilizzare OAuth 2.0 per ottenere l'autorizzazione al recupero dei dati di YouTube di un canale.

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

Alternative

Per le app mobile, è preferibile utilizzare Accedi con Google per Android o iOS. Le librerie client di Accedi con Google gestiscono l'autenticazione e l'autorizzazione utente e potrebbero essere più semplici da implementare rispetto al protocollo di livello inferiore descritto qui.

Per le app in esecuzione su dispositivi che non supportano un browser di sistema o con funzionalità di input limitate, come TV, console per videogiochi, videocamere o stampanti, consulta OAuth 2.0 per TV e dispositivi o Accesso su TV e dispositivi a input limitato.

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 le app: esempi di Windows

Prerequisiti

Abilita le API per il 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. Utilizza la pagina Raccolta per individuare e attivare l'API di dati di YouTube. Trova e abilita anche le altre API utilizzate dalla tua applicazione.

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 tuo progetto. Le applicazioni possono quindi utilizzare le credenziali per accedere alle API abilitate 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 come appropriato.

Identifica gli ambiti di accesso

Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, permettendo al contempo agli utenti di controllare il livello di accesso che concedono all'applicazione. Pertanto, potrebbe esistere una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il 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à disporre dell'autorizzazione per accedere.

La YouTube Data API v3 utilizza i seguenti ambiti:

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. 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 uno strumento di verifica e verifica del codice

Google supporta il protocollo Proof Key for Code Exchange (PKCE) per rendere più sicuro il flusso delle app installate. Per ogni richiesta di autorizzazione viene creato uno strumento di verifica univoco del codice 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

Un code_verifier è una stringa casuale con elevata 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 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 degli utenti, 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 e rifiuta le connessioni HTTP (non SSL).

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

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, nonché il parametro facoltativo state. Ogni URL contiene interruzioni di riga e spazi per una migliore leggibilità.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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 questa fase, Google mostra una finestra di consenso che mostra il nome della tua applicazione e dei servizi API di Google per i quali richiede l'autorizzazione ad accedere con le credenziali di autorizzazione dell'utente e un riepilogo degli ambiti di accesso da concedere. L'utente può quindi acconsentire alla concessione dell'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 un 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 all'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 per 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/youtube.force-ssl",
  "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 sono stati concessi gli ambiti di accesso richiesti dall'API. Per farlo, includi il token di accesso in una richiesta all'API includendo un parametro di 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 puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, quando chiami l'API YouTube Live Streaming).

Tieni presente che l'API YouTube Live Streaming non supporta il flusso dell'account di servizio. Poiché non è possibile collegare un account di servizio a un account YouTube, i tentativi di autorizzazione delle richieste con questo flusso generano un errore NoLinkedYouTubeAccount.

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

Esempi GET HTTP

Una chiamata all'endpoint liveBroadcasts.list (l'API YouTube Live Streaming) che utilizza l'intestazione HTTP Authorization: Bearer potrebbe essere simile alla seguente. Tieni presente che devi specificare un tuo token di accesso:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true 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/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Oppure, in alternativa, l'opzione del parametro della stringa di query:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Aggiornamento di un token di accesso

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

Per aggiornare un token di accesso, l'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 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 dei limiti al numero di token di aggiornamento che verranno emessi: un limite per ogni combinazione client/utente e un altro per utente per tutti i client. Dovresti 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 imbattersi in questi limiti, nel qual caso i token di aggiornamento meno recenti smetteranno 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 le Impostazioni account. Per ulteriori informazioni, consulta la sezione relativa alla rimozione dell'accesso di siti o app del documento di assistenza per siti e app di terze parti con accesso al tuo account.

È 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 o rimuove un'applicazione oppure 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 precedentemente concesse all'applicazione vengano rimosse.

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

Il protocollo OAuth 2.0 per app native delle best practice correnti dell'IETF definisce molte delle best practice qui documentate.