Questo documento spiega come implementare l'autorizzazione di accesso OAuth 2.0 le API di Google tramite le applicazioni in esecuzione su dispositivi quali TV, console per videogiochi e stampanti. In particolare, questo flusso è stato ideato per i dispositivi che non hanno accesso a un browser o dispongono di funzionalità di input limitate.
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 TV potrebbe utilizzare OAuth 2.0 per ottenere l'autorizzazione seleziona un file archiviato su Google Drive.
Poiché le applicazioni che utilizzano questo flusso sono distribuite ai singoli dispositivi, presuppone che le app non possano mantenere segreti. Può accedere alle API di Google mentre l'utente sta presenti 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 input completo utilizzare il flusso OAuth 2.0 per i dispositivi mobili e applicazioni desktop. Dovresti usare questo flusso anche se l'app è una riga di comando senza interfaccia grafica).
Se vuoi accedere solo agli utenti con i loro Account Google e utilizzare Token ID JWT per ottenere informazioni di base del profilo dell'utente, consulta Accesso su TV e dispositivi di input limitati.
Prerequisiti
Abilita le API per il progetto
Qualsiasi applicazione che chiama le API di Google deve abilitare tali API nel API Console.
Per abilitare un'API per il tuo progetto:
- Open the API Library in Google API Console.
- If prompted, select a project, or create a new one.
- API Library 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.
- Seleziona l'API da abilitare e fai clic sul pulsante Abilita.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
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.
- Go to the Credentials page.
- Fai clic su Crea credenziali > ID client OAuth.
- Seleziona il tipo di applicazione TV e dispositivi di input con limitazioni.
- Assegna un nome al client OAuth 2.0 e fai clic su Crea.
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.
Consulta l'elenco Ambiti consentiti per le app o i dispositivi installati.
Ottenere i token di accesso OAuth 2.0
Anche se l'applicazione viene eseguita su un dispositivo con capacità di input limitate, gli utenti devono avere separato l'accesso a un dispositivo con funzionalità di input più avanzate per completare questo flusso di autorizzazione. Il flusso prevede i seguenti passaggi:
- L'applicazione invia una richiesta al server di autorizzazione di Google che identifica gli ambiti a cui la tua applicazione richiederà l'autorizzazione ad accedere.
- Il server risponde con diverse informazioni utilizzate nei passaggi successivi, ad esempio una codice dispositivo e un codice utente.
- Puoi visualizzare le informazioni che l'utente può inserire su un dispositivo separato per autorizzare dell'app.
- L'applicazione avvia il polling del server di autorizzazione di Google per determinare se l'utente ha autorizzato la tua app.
- L'utente passa a un dispositivo con funzionalità di input più avanzate, avvia un browser web accede all'URL visualizzato al passaggio 3 e inserisce un codice che viene visualizzato anche al passaggio 3. La L'utente potrà quindi concedere (o negare) l'accesso alla tua applicazione.
- La risposta successiva alla richiesta di polling contiene i token che l'app deve autorizzare richieste 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:
Questi passaggi vengono descritti in dettaglio nelle sezioni seguenti. Data la gamma di funzionalità e runtime
degli ambienti dei dispositivi, gli esempi mostrati in questo documento utilizzano le curl
a riga di comando. Questi esempi devono essere facili da trasferire in vari linguaggi e runtime.
Passaggio 1: richiedi i codici utente e del dispositivo
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 la tua applicazione
nonché gli ambiti di accesso a cui l'applicazione vuole accedere per conto dell'utente.
Devi recuperare questo URL dal
Documento di rilevamento che utilizza
Valore dei metadati device_authorization_endpoint. Includi la seguente richiesta HTTP
parametri:
| Parametri | |
|---|---|
client_id |
Obbligatorio
L'ID client dell'applicazione. Puoi trovare questo valore nella sezione API Console Credentials page. |
scope |
Obbligatorio
R delimitato da spazi l'elenco degli ambiti che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di consenso che Google mostra al utente. Consulta le Elenco degli ambiti consentiti per le app o i dispositivi installati. Gli ambiti consentono all'applicazione di richiedere l'accesso solo alle risorse di cui ha bisogno consentendo agli utenti di controllare il livello di accesso che concedono al tuo un'applicazione. Esiste quindi una relazione inversa tra il numero di ambiti richiesti e la probabilità di ottenere il consenso degli utenti. |
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 riuscita
Se la richiesta è valida, la risposta sarà un oggetto JSON contenente quanto segue proprietà:
| Proprietà | |
|---|---|
device_code |
Un valore che Google assegna in modo univoco per identificare il dispositivo che esegue l'app che richiede
autorizzazione. L'utente autorizzerà il dispositivo da un altro dispositivo con informazioni
funzionalità di input. Ad esempio, un utente potrebbe utilizzare un laptop o un cellulare per autorizzare
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 |
Il periodo di tempo, in secondi, durante il quale device_code e
user_code sono validi. Se in questo lasso di tempo l'utente non completa
flusso di autorizzazione e il dispositivo non effettua una query per recuperare informazioni sul
decisione dell'utente, potrebbe essere necessario riavviare la procedura dal passaggio 1. |
interval |
Il periodo di tempo, in secondi, che il dispositivo deve attendere tra una richiesta di polling e l'altra. Per
Ad esempio, se il valore è 5, il dispositivo deve inviare una richiesta di polling a
server di autorizzazione di Google ogni cinque secondi. Consulta
passaggio 3 per ulteriori dettagli. |
user_code |
Un valore sensibile alle maiuscole che identifica a Google gli ambiti in cui l'applicazione richiedendo l'accesso. L'interfaccia utente chiederà all'utente di inserire questo valore su una dispositivo separato con funzionalità di input più avanzate. Google utilizza quindi il valore per visualizzare l'insieme corretto di ambiti quando viene chiesto 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
user_code e concedere o negare l'accesso alla tua applicazione. Interfaccia utente
questo valore verrà visualizzato. |
Lo snippet seguente 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 per superamento quota
Se le richieste di codice del dispositivo hanno superato la quota associata al tuo ID client, riceveranno una risposta 403, contenente il seguente errore:
{
"error_code": "rate_limit_exceeded"
}
In tal caso, utilizza una strategia di backoff per ridurre la frequenza delle richieste.
Passaggio 3: visualizza il codice utente
Mostra verification_url e user_code ottenuti nel passaggio 2 alla
utente. Entrambi i valori possono contenere qualsiasi carattere stampabile del set di caratteri US-ASCII. I contenuti
che mostri all'utente deve invitarlo a passare alla
verification_url su un dispositivo separato e inserisci user_code.
Progetta la tua interfaccia utente (UI) tenendo presenti le seguenti regole:
user_codeuser_codedeve essere visualizzato in un campo in grado di gestire 15 "W" dimensioni caratteri. In altre parole, se puoi visualizzare il codiceWWWWWWWWWWWWWWWcorrettamente, la tua UI sia valida e ti consigliamo di usare quel valore di stringa durante il test del modouser_codevisualizzato nella tua UI.user_codeè sensibile alle maiuscole e non deve essere modificato in alcun modo, ad esempio come la modifica delle maiuscole o l'inserimento di altri caratteri di formattazione.
verification_url- Lo spazio in cui visualizzi
verification_urldeve essere sufficientemente ampio da gestire una stringa URL di 40 caratteri. - Non devi modificare
verification_urlin nessun modo, tranne facoltativamente rimuovere lo schema per la visualizzazione. Se intendi eliminare lo schema (ad es.https://) dall'URL per motivi di visualizzazione, assicurati che la tua app sia in grado di gestire entrambe le variantihttpehttps.
- Lo spazio in cui visualizzi
Passaggio 4: esegui un sondaggio sul server di autorizzazione di Google
L'utente userà un dispositivo separato per raggiungere 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 che ha inviato la richiesta deve eseguire un polling della
server di autorizzazione per determinare quando l'utente ha risposto alla richiesta.
Il dispositivo richiedente deve continuare a inviare richieste di polling finché non riceve una risposta
indicando che l'utente ha risposto alla richiesta di accesso o fino a quando device_code
e user_code ottenuti in
passaggio 2 è scaduto. Il valore interval restituito nel passaggio 2 specifica la quantità
il tempo di attesa, in secondi, tra una richiesta e l'altra.
L'URL dell'endpoint del sondaggio è https://oauth2.googleapis.com/token. La richiesta di polling
contiene i seguenti parametri:
| Parametri | |
|---|---|
client_id |
L'ID client dell'applicazione. Puoi trovare questo valore nella sezione API Console Credentials page. |
client_secret |
Il client secret per il valore client_id fornito. Puoi trovare questo valore nella sezione
API Console
Credentials page. |
device_code |
device_code restituito dal server di autorizzazione in
passaggio 2. |
grant_type |
Imposta questo valore su urn:ietf:params:oauth:grant-type:device_code. |
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
L'immagine seguente mostra una pagina simile a quella che gli utenti vedono quando visitano il
verification_url che hai visualizzato nel passaggio 3:
Dopo aver inserito l'user_code e, se non hai ancora eseguito l'accesso a Google,
l'utente vede una schermata per il 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 uno dei seguenti elementi: 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 dispositivo di
accedere alle API di Google per conto dell'utente. (scope
nella risposta determina quali API
dispositivo a cui può accedere).
In questo caso, la risposta dell'API contiene i seguenti campi:
| Campi | |
|---|---|
access_token |
Il token che l'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 fino a quando l'utente revoca l'accesso. Tieni presente che i token di aggiornamento vengono sempre restituiti per i dispositivi. |
scope |
Gli ambiti di accesso concessi da access_token espressi sotto forma di elenco di
stringhe delimitate da spazi, con distinzione tra maiuscole e minuscole. |
token_type |
Il tipo di token restituito. Al momento, il valore di questo campo è sempre impostato su
Bearer. |
Lo snippet seguente 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 richiede l'accesso a un'API per un periodo di tempo di tempo, può utilizzare il token di aggiornamento per ottenere un nuovo accesso di accesso. Se l'applicazione ha bisogno di questo tipo di accesso, dovrebbe memorizzare il token di aggiornamento per in un secondo momento.
Accesso negato
Se l'utente si rifiuta di concedere l'accesso al dispositivo, la risposta del server riceve un
403 Codice di stato della risposta HTTP (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
428 Codice di stato della risposta HTTP (Precondition Required). La risposta
contiene il seguente errore:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
Sondaggi troppo frequenti
Se il dispositivo invia richieste di polling troppo spesso, il server restituisce un 403
Codice di stato della risposta HTTP (Forbidden). La risposta contiene quanto segue
errore:
{
"error": "slow_down",
"error_description": "Forbidden"
}
Altri errori
Il server di autorizzazione restituisce degli errori anche se nella richiesta di polling mancano alcune informazioni obbligatorie
parametri o contiene un valore parametro errato. Queste richieste di solito hanno un 400
Stato della risposta HTTP (Bad Request) o 401 (Unauthorized)
le API nel tuo codice. 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 dell'amministratore di Google Workspace. Consulta il Centro assistenza per amministratori di Google Workspace Specificare quali soluzioni di terze parti e app interne accedono ai dati di Google Workspace per ulteriori informazioni su come amministratore può limitare l'accesso agli ambiti finché l'accesso non viene concesso esplicitamente al tuo account OAuth l'ID client. |
invalid_client |
401 |
Client OAuth non trovato. Ad esempio, questo errore si verifica se
Il valore del parametro Il tipo di client OAuth non è corretto. Assicurati che tipo di applicazione per l'ID client sia impostato su TV e dispositivi a input limitato. |
invalid_grant |
400 |
Il valore del 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 uno specifico Organizzazione Google Cloud. Conferma il tipo di utente configurazione della tua applicazione OAuth. |
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 HTTP
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:
| Campi | |
|---|---|
client_id |
L'ID client ottenuto da API Console. |
client_secret |
Il client secret ottenuto da API Console. |
grant_type |
Come
definiti nel
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. |
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.
Ambiti consentiti
Il flusso OAuth 2.0 per i dispositivi è supportato solo per i seguenti ambiti:
OpenID Connect Accedi con Google
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
API di YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly
Implementare la Protezione su più account
Un ulteriore passaggio da seguire per proteggere i tuoi utenti che stanno implementando più account Protezione con l'utilizzo del servizio di protezione su più account di Google. Questo servizio ti consente iscriviti alle notifiche di eventi di sicurezza che forniscono informazioni alla tua applicazione su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per intervenire in base al come decidi di rispondere agli eventi.
Ecco alcuni esempi di 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
Consulta le Proteggere gli account utente con la pagina Protezione su più account . per ulteriori informazioni su come implementare la Protezione su più account e per l'elenco completo degli eventi disponibili.