OAuth 2.0 per applicazioni TV e di dispositivi con input limitato

Questo documento spiega come implementare l'autorizzazione OAuth 2.0 per accedere alle API di Google tramite applicazioni in esecuzione su dispositivi come TV, console per videogiochi e stampanti. Nello specifico, questo flusso è progettato per i dispositivi che non hanno accesso a un browser o che hanno funzionalità di input limitate.

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 per TV potrebbe utilizzare OAuth 2.0 per ottenere l'autorizzazione per selezionare un file archiviato su Google Drive.

Poiché le applicazioni che utilizzano questo flusso vengono distribuite ai singoli dispositivi, si assume che le app non possano mantenere segreti. Possono accedere alle API di Google quando l'utente è presente nell'app o quando l'app è in esecuzione in background.

Alternative

Se stai scrivendo un'app per una piattaforma come Android, iOS, macOS, Linux o Windows (inclusa la piattaforma Universal Windows), che ha accesso al browser e funzionalità di input complete, utilizza il flusso OAuth 2.0 per applicazioni mobile e desktop. Devi utilizzare questo flusso anche se la tua app è uno strumento a riga di comando senza un'interfaccia grafica.

Se solo vuoi consentire agli utenti di accedere con i propri Account Google e utilizzare il token ID JWT per ottenere informazioni di base sul profilo dell'utente, consulta Accedere su TV e dispositivi di input con limitazioni.

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiama le API di Google deve attivarle in .

Per attivare un'API per il tuo progetto:

1. in .
3. La pagina elenca tutte le API disponibili, raggruppate per famiglia di prodotti e popolarità. Se l'API che vuoi attivare non è visibile nell'elenco, utilizza la ricerca per trovarla o fai clic su Visualizza tutto nella famiglia di prodotti a cui appartiene.
4. Seleziona l'API che vuoi attivare, poi fai clic sul pulsante Attiva.

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 per il server OAuth 2.0 di Google. I passaggi riportati di seguito spiegano come creare le credenziali per il progetto. Le applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai attivato per il progetto.

2. Fai clic su Crea credenziali > ID client OAuth.
3. Seleziona il tipo di applicazione TV e dispositivi a input limitato.
4. Assegna un nome al client OAuth 2.0 e fai clic su Crea.

Identificare gli ambiti di accesso

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, consentendo inoltre agli utenti di controllare la quantità di accesso concessa alla tua applicazione. 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 avrà bisogno di accedere.

Consulta l'elenco Ambiti consentiti per le app o i dispositivi installati.

Ottenere i token di accesso OAuth 2.0

Anche se la tua applicazione viene eseguita su un dispositivo con funzionalità di input limitate, gli utenti devono avere accesso distinto a un dispositivo con funzionalità di input più complete per completare questo flusso di autorizzazione. Il flusso prevede i seguenti passaggi:

1. L'applicazione invia una richiesta al server di autorizzazione di Google che identifica gli ambiti per i quali l'applicazione richiederà l'autorizzazione di accesso.
2. Il server risponde con diverse informazioni utilizzate nei passaggi successivi, ad esempio un codice dispositivo e un codice utente.
3. Mostra le informazioni che l'utente può inserire su un dispositivo separato per autorizzare la tua app.
4. L'applicazione inizia a eseguire il polling del server di autorizzazione di Google per determinare se l'utente ha autorizzato la tua app.
5. L'utente passa a un dispositivo con funzionalità di inserimento più avanzate, avvia un browser web, accede all'URL visualizzato nel passaggio 3 e inserisce un codice visualizzato anche nel passaggio 3. L'utente può quindi concedere (o negare) l'accesso alla tua applicazione.
6. La risposta successiva alla richiesta di polling contiene i token necessari per l'autorizzazione delle richieste da parte dell'app per conto dell'utente. Se l'utente ha rifiutato l'accesso alla tua applicazione, la risposta non contiene token.

L'immagine seguente illustra questa procedura:

Le sezioni seguenti spiegano questi passaggi in dettaglio. Data la gamma di funzionalità e ambienti di runtime che i dispositivi possono avere, gli esempi mostrati in questo documento utilizzano l'utilità a riga di comando curl. Questi esempi dovrebbero essere facili da trasferire a vari linguaggi e runtime.

Passaggio 1: richiedi i codici del dispositivo e dell'utente

In questo passaggio, il dispositivo invia una richiesta POST HTTP al server di autorizzazione di Google, all'indirizzo https://oauth2.googleapis.com/device/code, che identifica l'applicazione e gli ambiti di accesso a cui l'applicazione vuole accedere per conto dell'utente. Devi recuperare questo URL dal documento Discovery utilizzando il valore dei metadati device_authorization_endpoint. Includi i seguenti parametri della richiesta HTTP:

Esempi

Lo snippet seguente mostra una richiesta di esempio:

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

client_id=client_id&scope=email%20profile

Questo esempio mostra un comando curl per inviare la stessa richiesta:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

Passaggio 2: gestisci la risposta del server di autorizzazione

Il server di autorizzazione restituirà una delle seguenti risposte:

Risposta di successo

Se la richiesta è valida, la risposta sarà un oggetto JSON contenente le seguenti proprietà:

Il seguente snippet mostra una risposta di esempio:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Risposta a quota superata

Se le richieste di codici dispositivo hanno superato la quota associata al tuo ID cliente, riceverai una risposta 403 contenente il seguente errore:

{
  "error_code": "rate_limit_exceeded"
}

In questo caso, utilizza una strategia di backoff per ridurre la frequenza delle richieste.

Passaggio 3: visualizza il codice utente

Mostra all'utente verification_url e user_code ottenuti nel passaggio 2. Entrambi i valori possono contenere qualsiasi carattere stampabile del set di caratteri US-ASCII. I contenuti che mostri all'utente devono indicargli di accedere a verification_url su un dispositivo separato e di inserire il user_code.

Progetta l'interfaccia utente (UI) tenendo presenti le seguenti regole:

• user_code
  • user_code deve essere visualizzato in un campo che può gestire 15 caratteri di dimensione "W". In altre parole, se riesci a visualizzare correttamente il codice WWWWWWWWWWWWWWW la tua UI è valida e ti consigliamo di utilizzare questo valore di stringa per testare il modo in cui viene visualizzato user_code nella tua UI.
  • user_code è sensibile alle maiuscole e non deve essere modificato in alcun modo, ad esempio cambiando le maiuscole o inserendo altri caratteri di formattazione.
• verification_url
  • Lo spazio in cui viene visualizzato verification_url deve essere abbastanza ampio da gestire una stringa URL di 40 caratteri.
  • Non devi modificare verification_url in alcun modo, tranne che per rimuovere facoltativamente lo schema per la visualizzazione. Se prevedi di rimuovere lo schema (ad es. https://) dall'URL per motivi di visualizzazione, assicurati che la tua app possa gestire entrambe le varianti http e https.

Passaggio 4: esegui la polling del server di autorizzazione di Google

Poiché l'utente utilizzerà un dispositivo separato per accedere a verification_url e concedere (o negare) l'accesso, il dispositivo che effettua la richiesta non riceve una notifica automatica quando l'utente risponde alla richiesta di accesso. Per questo motivo, il dispositivo che effettua la richiesta deve eseguire il polling del server di autorizzazione di Google per determinare quando l'utente ha risposto alla richiesta.

Il dispositivo richiedente deve continuare a inviare richieste di polling finché non riceve una risposta che indica che l'utente ha risposto alla richiesta di accesso o finché device_code e user_code ottenuti nel passaggio 2 non sono scaduti. Il valore interval restituito nel passaggio 2 specifica il tempo, in secondi, da attendere tra una richiesta e l'altra.

L'URL dell'endpoint da sottoporre a sondaggio è https://oauth2.googleapis.com/token. La richiesta di polling contiene i seguenti parametri:

Esempi

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=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Questo esempio mostra un comando curl per inviare la stessa richiesta:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Passaggio 5: l'utente risponde alla richiesta di accesso

La seguente immagine mostra una pagina simile a quella che gli utenti vedono quando accedono al verification_url visualizzato nel passaggio 3:

Dopo aver inserito il user_code e, se non ha ancora eseguito l'accesso, aver eseguito l'accesso a Google, l'utente visualizza una schermata di consenso come quella mostrata di seguito:

Passaggio 6: gestisci le risposte alle richieste di polling

Il server di autorizzazione di Google risponde a ogni richiesta di polling con una delle seguenti risposte:

Accesso concesso

Se l'utente ha concesso l'accesso al dispositivo (facendo clic su Allow nella schermata del consenso), la risposta contiene un token di accesso e un token di aggiornamento. I token consentono al tuo dispositivo di accedere alle API di Google per conto dell'utente. La proprietà scope nella risposta determina le API a cui il dispositivo può accedere.

In questo caso, la risposta dell'API contiene i seguenti campi:

Il seguente snippet mostra una risposta di esempio:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

I token di accesso hanno una durata limitata. Se la tua applicazione deve accedere a un'API per un lungo periodo di tempo, può utilizzare il token di aggiornamento per ottenere un nuovo token di accesso. Se la tua applicazione ha bisogno di questo tipo di accesso, deve memorizzare il token di aggiornamento per un uso successivo.

Accesso negato

Se l'utente rifiuta di concedere l'accesso al dispositivo, la risposta del server ha un codice di stato di risposta HTTP 403 (Forbidden). La risposta contiene il seguente errore:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Autorizzazione in attesa

Se l'utente non ha ancora completato il flusso di autorizzazione, il server restituisce un codice di stato di risposta HTTP 428 (Precondition Required). La risposta contiene il seguente errore:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Esecuzione di sondaggi troppo di frequente

Se il dispositivo invia richieste di polling troppo di frequente, il server restituisce un 403 codice di stato della risposta HTTP (Forbidden). La risposta contiene il seguente errore:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Altri errori

Il server di autorizzazione restituisce anche errori se nella richiesta di polling mancano parametri obbligatori o se il valore di un parametro è errato. Queste richieste hanno in genere un codice di stato della risposta HTTP 400 (Bad Request) o 401 (Unauthorized). Questi errori includono:

Chiamate alle 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 gli ambiti di accesso richiesti dall'API sono stati concessi. 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 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 richieste GET HTTP

Una chiamata all'endpoint drive.files (l'API Drive Files) 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 che utilizza il parametro della stringa di query access_token:

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 (opzione preferita):

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

In alternativa, l'opzione del parametro 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, 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 di token restituisce un oggetto JSON contenente un nuovo token di accesso. Il seguente snippet mostra un'esempio di risposta:

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

Tieni presente che esistono limiti al numero di token di aggiornamento che verranno emessi: un limite per combinazione di cliente/utente e un altro per utente su tutti i clienti. Devi salvare i token di aggiornamento in uno spazio di archiviazione a lungo termine e continuare a utilizzarli finché rimangono validi. Se la tua applicazione richiede troppi token di aggiornamento, potrebbe incontrare questi limiti, nel qual caso i token di aggiornamento meno recenti non funzioneranno più.

Revocare 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 account. Per saperne di più, consulta la sezione Rimuovere l'accesso di un sito o un'app del documento del Centro assistenza App e siti di terze parti con accesso al tuo account.

È anche possibile che un'applicazione revochi in modo programmatico l'accesso che le è stato concesso. La revoca programmatica è importante nei casi in cui un utente annulla l'iscrizione, rimuove un'applicazione o le risorse dell'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 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 il token è un token di accesso e ha un token di aggiornamento corrispondente, anche il token di aggiornamento verrà revocato.

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.

Ambiti consentiti

Il flusso OAuth 2.0 per i dispositivi è supportato solo per i seguenti ambiti: