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 utilizzando applicazioni in esecuzione su dispositivi come TV, console per videogiochi e stampanti. In particolare, questo flusso è progettato per i dispositivi che non hanno accesso a un browser o che hanno funzionalità di immissione 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 TV potrebbe utilizzare OAuth 2.0 per ottenere l'autorizzazione a selezionare un file archiviato su Google Drive.

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

Alternative

Se vuoi solo far accedere gli utenti con i loro Account Google e utilizzare il token ID JWT per ottenere informazioni di base sul profilo utente, consulta Accedi su TV e dispositivi con input limitato.

Prerequisiti

Abilita le API per il tuo progetto

Qualsiasi applicazione che chiama le API di Google deve abilitarle nella console API.

Per abilitare un'API per il tuo progetto:

  1. Apri la libreria API nella console API di Google.
  2. Se richiesto, seleziona un progetto o creane uno nuovo.
  3. La libreria API 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 abilitare, quindi fai clic sul pulsante Abilita.
  5. Se richiesto, abilita la fatturazione.
  6. Se richiesto, leggi e accetta i Termini di servizio dell'API.

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 la identificano per il server OAuth 2.0 di Google. I passaggi seguenti spiegano come creare le credenziali per il tuo progetto. Le tue applicazioni possono quindi utilizzare le credenziali per accedere alle API che hai abilitato per quel progetto.

  1. Vai alla pagina Clienti.
  2. Fai clic su Crea client.
  3. Seleziona il tipo di applicazione TV e dispositivi di input limitato.
  4. Assegna un nome al client OAuth 2.0 e fai clic su Crea.

Identifica gli ambiti di accesso

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, consentendo al contempo agli utenti di controllare il livello di accesso che concedono 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 per cui la tua app avrà bisogno dell'autorizzazione di accesso.

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

Ottieni i token di accesso OAuth 2.0

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

  1. La tua applicazione invia una richiesta al server di autorizzazione di Google che identifica gli ambiti per i quali la tua 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. Mostri 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 l'app.
  5. L'utente passa a un dispositivo con funzionalità di input più avanzate, avvia un browser web, accede all'URL visualizzato nel passaggio 3 e inserisce un codice, anch'esso visualizzato 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 alla tua app per autorizzare le richieste per conto dell'utente. Se l'utente ha rifiutato l'accesso alla tua applicazione, la risposta non contiene token.

L'immagine illustra questo processo:

L'utente accede su un dispositivo separato dotato di browser

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 possono essere trasferiti in vari linguaggi e runtime.

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

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

Parametri
client_id Obbligatorio

L'ID client della tua applicazione. Puoi trovare questo valore nella pagina Client della console Cloud.
scope Obbligatorio

Un elenco di ambiti delimitati da spazi che identificano le risorse a cui l'applicazione potrebbe accedere per conto dell'utente. Questi valori informano la schermata per il consenso che Google mostra all'utente. Consulta l'elenco Ambiti consentiti per le app installate o i dispositivi.

Gli ambiti consentono alla tua applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno, consentendo al contempo agli utenti di controllare il livello di accesso che concedono alla tua applicazione. Pertanto, esiste una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso dell'utente.

Esempi

Il seguente snippet 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 esito positivo

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

Proprietà
device_code Un valore assegnato in modo univoco da Google per identificare il dispositivo che esegue l'app che richiede l'autorizzazione. L'utente autorizzerà il dispositivo da un altro dispositivo con funzionalità di input più complete. Ad esempio, un utente potrebbe utilizzare un laptop o uno smartphone per autorizzare un'app in esecuzione su una TV. In questo caso, device_code identifica la TV.

Questo codice consente al dispositivo che esegue l'app di determinare in modo sicuro se l'utente ha concesso o negato l'accesso.
expires_in La durata, in secondi, della validità di device_code e user_code. Se, in questo lasso di tempo, l'utente non completa il flusso di autorizzazione e il tuo dispositivo non esegue il polling per recuperare informazioni sulla decisione dell'utente, potresti dover riavviare questa procedura dal passaggio 1.
interval Il periodo di tempo, in secondi, che il dispositivo deve attendere tra le richieste di polling. Ad esempio, se il valore è 5, il dispositivo deve inviare una richiesta di polling al server di autorizzazione di Google ogni cinque secondi. Per maggiori dettagli, consulta il passaggio 3.
user_code Un valore sensibile alle maiuscole che identifica per Google gli ambiti a cui l'applicazione richiede l'accesso. L'interfaccia utente indicherà all'utente di inserire questo valore su un dispositivo separato con funzionalità di immissione più avanzate. Google utilizza quindi il valore per visualizzare l'insieme corretto di ambiti quando chiede all'utente di concedere l'accesso alla tua applicazione.
verification_url Un URL a cui l'utente deve accedere, su un dispositivo separato, per inserire il user_code e concedere o negare l'accesso alla tua applicazione. Questo valore verrà visualizzato anche nell'interfaccia utente.

Il seguente snippet mostra un esempio di risposta:

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

Risposta di superamento della quota

Se le richieste di codice del dispositivo hanno superato la quota associata al tuo ID client, 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 il verification_url e il 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 inserire il user_code.

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

  • user_code
    • Il user_code deve essere visualizzato in un campo in grado di 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 stringa per testare il modo in cui user_code viene visualizzato nella tua UI.
    • Il 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 mostri l'URL verification_url deve essere abbastanza ampio da contenere una stringa URL di 40 caratteri.
    • Non devi modificare l'verification_url in alcun modo, se non 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 sia in grado di gestire sia la variante http sia la variante https.

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

Poiché l'utente utilizzerà un dispositivo separato per accedere all'verification_url e concedere (o negare) l'accesso, il dispositivo richiedente non riceve automaticamente una notifica quando l'utente risponde alla richiesta di accesso. Per questo motivo, il dispositivo richiedente 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 di attesa, in secondi, tra le richieste.

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

Parametri
client_id L'ID client della tua applicazione. Puoi trovare questo valore nella pagina Client della console Cloud.
client_secret Il client secret per il client_id fornito. Puoi trovare questo valore nella pagina Client della console Cloud.
device_code Il device_code restituito dal server di autorizzazione nel passaggio 2.
grant_type Imposta questo valore su urn:ietf:params:oauth:grant-type:device_code.

Esempi

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

L'immagine seguente mostra una pagina simile a quella che gli utenti vedono quando accedono alla verification_url che hai visualizzato nel passaggio 3:

Connetti un dispositivo inserendo un codice

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 per il consenso:

Esempio di schermata per il consenso per un client del dispositivo

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 per il 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:

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.
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 o finché il token di aggiornamento non scade. Tieni presente che i token di aggiornamento vengono sempre restituiti per i dispositivi.
scope Gli ambiti di accesso concessi da access_token espressi come un elenco di stringhe sensibili alle maiuscole delimitate da spazi.
token_type Il tipo di token restituito. Questo valore è sempre Bearer.

Il seguente snippet mostra un esempio di risposta:

{
  "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 richiede questo tipo di accesso, deve memorizzare il token di aggiornamento per un utilizzo successivo.

Accesso negato

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

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

In attesa di autorizzazione

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

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

Polling troppo frequente

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

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

Altri errori

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

Errore Codice di stato HTTP Descrizione
admin_policy_enforced 400 L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa delle policy dell'amministratore di Google Workspace. Per ulteriori informazioni su come un amministratore può limitare l'accesso agli ambiti finché non viene concesso esplicitamente l'accesso al tuo ID client OAuth, consulta l'articolo del Centro assistenza per gli amministratori di Google Workspace Specifica quali app di terze parti e interne possono accedere ai dati di Google Workspace.
invalid_client 401

Il client OAuth non è stato trovato. Ad esempio, questo errore si verifica se il valore del parametro client_id non è valido.

Il tipo di client OAuth non è corretto. Assicurati che il tipo di applicazione per l'ID client sia impostato su TV e dispositivi a input limitato.
invalid_grant 400 Il valore parametro code non è valido, è già stato rivendicato o non può essere analizzato.
unsupported_grant_type 400 Il valore del parametro grant_type non è valido.
org_internal 403 L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una specifica organizzazione Google Cloud. Conferma la configurazione del tipo di utente per la tua applicazione OAuth.

Chiamata 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 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 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 visualizzare i relativi 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 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 (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 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 una richiesta HTTPS POST al server di autorizzazione di Google (https://oauth2.googleapis.com/token) che include i seguenti parametri nel corpo della richiesta:

Nome Valore
client_id L'ID client ottenuto dalla console API.
client_secret Facoltativo

Il client secret ottenuto dalla console API.

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 del 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&
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. Il seguente snippet mostra una risposta di esempio:

{
  "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 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 la tua applicazione richiede troppi token di aggiornamento, potrebbe raggiungere questi limiti e, in questo caso, i token di aggiornamento meno recenti smetteranno di funzionare.

Revoca dei 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 ulteriori informazioni, consulta la sezione Rimuovere l'accesso di un sito o di un'app del documento di assistenza Siti e app di terze parti con accesso al tuo account.

È anche possibile che un'applicazione revochi l'accesso concesso in modo programmatico. La revoca programmatica è importante nei casi 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 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. In caso di 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:

OpenID Connect, Accedi con Google

  • email
  • openid
  • profile

API Drive

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

API di YouTube

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

Accesso in base al tempo

L'accesso basato sul tempo consente a un utente di concedere alla tua app l'accesso ai suoi dati per un periodo di tempo limitato per completare un'azione. L'accesso basato sul tempo è disponibile in alcuni prodotti Google durante il flusso di consenso e offre agli utenti la possibilità di concedere l'accesso per un periodo di tempo limitato. Un esempio è l' API Data Portability, che consente un trasferimento dei dati una tantum.

Quando un utente concede alla tua applicazione l'accesso basato sul tempo, il token di aggiornamento scade dopo la durata specificata. Tieni presente che i token di aggiornamento potrebbero essere invalidati prima in circostanze specifiche; per maggiori dettagli, consulta questi casi. In questi casi, il campo refresh_token_expires_in restituito nella risposta dello scambio del codice di autorizzazione rappresenta il tempo rimanente prima della scadenza del token di aggiornamento.

Implementa la Protezione su più account

Un ulteriore passaggio da eseguire per proteggere gli account degli utenti è l'implementazione della Protezione su più account utilizzando il servizio Protezione su più account di Google. Questo servizio ti consente di iscriverti alle notifiche di eventi di sicurezza che forniscono alla tua applicazione informazioni su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per passare all'azione a seconda di come decidi di rispondere agli eventi.

Ecco alcuni esempi dei tipi di eventi inviati alla tua app dal servizio di Protezione su più account di Google:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Per ulteriori informazioni su come implementare la protezione su più account e per l'elenco completo degli eventi disponibili, consulta la pagina Proteggi gli account utente con la protezione su più account .