Accesso su TV e dispositivi di input limitato

Puoi consentire agli utenti di accedere alla tua app con i propri Account Google su dispositivi con funzionalità di input limitate, come le TV connesse a Internet.

L'app mostra all'utente un codice breve e un URL di accesso. Quindi, l'utente apre l'URL di accesso in un browser web, inserisce il codice e concede all'app l'autorizzazione ad accedere alle informazioni di accesso dell'utente. Infine, l'app riceve la conferma e l'utente ha eseguito l'accesso.

Per utilizzare questo flusso di accesso, l'app deve essere eseguita su un dispositivo che soddisfa i seguenti criteri:

  • Il dispositivo deve essere in grado di mostrare un URL di 40 caratteri e un codice utente di 15 caratteri, insieme alle istruzioni per l'utente.
  • Il dispositivo deve essere connesso a Internet.

Recupero di un ID client e di un client secret

L'app richiede un ID client OAuth 2.0 e un client secret per effettuare richieste agli endpoint di accesso di Google.

Per trovare l'ID client e il client secret del progetto:

  1. Seleziona una credenziale OAuth 2.0 esistente o apri la pagina Credenziali.
  2. Se non l'hai ancora fatto, crea le credenziali OAuth 2.0 del tuo progetto facendo clic su Crea credenziali > ID client OAuth e fornendo le informazioni necessarie per creare le credenziali.
  3. Cerca l'ID client nella sezione ID client OAuth 2.0. Per maggiori dettagli, fai clic sull'ID client.

Se stai creando un nuovo ID client, seleziona il tipo di applicazione TV e dispositivi di input limitato.

Ottenere un codice utente e un URL di verifica

Quando un utente richiede di accedere utilizzando un Account Google, puoi ricevere un codice utente e un URL di verifica inviando una richiesta POST HTTP all'endpoint del dispositivo OAuth 2.0, https://oauth2.googleapis.com/device/code. Includi il tuo ID client e un elenco degli ambiti necessari con la richiesta. Se vuoi accedere solo agli utenti con i loro Account Google, richiedi solo gli ambiti profile e email; oppure, se vuoi richiedere l'autorizzazione per chiamare un'API supportata per conto degli utenti, richiedi gli ambiti richiesti oltre agli ambiti profile e email.

Di seguito è riportata una richiesta di esempio di un codice utente:

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

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

In uso: curl:

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

La risposta viene restituita come oggetto JSON:

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

L'app mostra all'utente i valori user_code e verification_url e contemporaneamente esegue il polling dell'endpoint di accesso in base al valore interval specificato finché l'utente non esegue l'accesso o non è trascorso il periodo di tempo specificato da expires_in.

Visualizza il codice utente e l'URL di verifica

Dopo aver ricevuto un codice utente e un URL di verifica dall'endpoint del dispositivo, mostrali e chiedi all'utente di aprire l'URL e inserire il codice utente.

I valori di verification_url e user_code sono soggetti a modifica. Progetta la tua UI in modo da poter gestire i seguenti limiti:

  • user_code deve essere visualizzato in un campo abbastanza largo da poter gestire 15 caratteri di dimensioni W.
  • verification_url deve essere visualizzato in un campo abbastanza ampio da poter gestire una stringa URL di 40 caratteri.

Entrambe le stringhe possono contenere qualsiasi carattere stampabile del set di caratteri US-ASCII.

Quando visualizzi la stringa user_code, non modificarla in alcun modo (ad esempio cambiando maiuscole e minuscole o inserendo altri caratteri di formattazione), perché la tua app potrebbe non funzionare se il formato del codice cambia in futuro.

Puoi modificare la stringa verification_url rimuovendo lo schema dall'URL per motivi di visualizzazione, se preferisci. In questo caso, assicurati che la tua app possa gestire entrambe le varianti "http" e "https". Non modificare in altro modo la stringa verification_url.

Quando l'utente accede all'URL di verifica, vede una pagina simile alla seguente:

Connetti un dispositivo inserendo un codice

Dopo che l'utente inserisce il codice utente, il sito Accedi con Google presenta una schermata per il consenso simile alla seguente:

Esempio di schermata di consenso per un client del dispositivo

Se l'utente fa clic su Consenti, l'app può ottenere un token ID per identificare l'utente, un token di accesso per chiamare le API di Google e un token di aggiornamento per acquisire nuovi token.

Ottenere un token ID e un token di aggiornamento

Dopo che nell'app vengono visualizzati il codice utente e l'URL di verifica, inizia a eseguire il polling dell'endpoint del token (https://oauth2.googleapis.com/token) con il codice del dispositivo che hai ricevuto dall'endpoint del dispositivo. Esegui un sondaggio sull'endpoint del token all'intervallo, in secondi, specificato dal valore interval.

Di seguito è riportata una richiesta di esempio:

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

client_id=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

In uso: curl:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

Se l'utente non ha ancora approvato la richiesta, la risposta è la seguente:

{
  "error" : "authorization_pending"
}

La tua app dovrebbe ripetere queste richieste a una frequenza non superiore al valore di interval. Se la tua app esegue il polling troppo rapidamente, la risposta è la seguente:

{
  "error" : "slow_down"
}

Dopo che l'utente esegue l'accesso e concesso alla tua app l'accesso agli ambiti richiesti, la risposta alla richiesta successiva dell'app include un token ID, un token di accesso e un token di aggiornamento:

{
  "access_token": "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

Una volta ricevuta questa risposta, l'app può decodificare il token ID per ottenere informazioni di base del profilo dell'utente che ha eseguito l'accesso oppure inviare il token ID al server di backend dell'app per eseguire l'autenticazione in modo sicuro con il server. Inoltre, l'app può utilizzare il token di accesso per chiamare le API di Google autorizzate dall'utente.

I token ID e di accesso hanno una durata limitata. Per mantenere l'accesso dell'utente per una durata maggiore della durata dei token, archivia il token di aggiornamento e utilizzalo per richiedere nuovi token.

Recuperare le informazioni del profilo utente dal token ID

Puoi ottenere informazioni sul profilo dell'utente che ha eseguito l'accesso decodificando il token ID con qualsiasi libreria di decodifica JWT. Ad esempio, se viene utilizzata la libreria JavaScript Auth0 jwt-decode:

var user_profile = jwt_decode(<var>id_token</var>);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

Maggiori informazioni