Accesso su TV e dispositivi di input limitato

Puoi consentire agli utenti di accedere alla tua app con i loro Account Google su dispositivi con capacità di ingresso limitate, come le TV connesse a internet.

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

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

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

Ottenere un ID client e un client secret

La tua app ha bisogno di un ID client e di un client secret OAuth 2.0 per effettuare richieste agli endpoint di accesso di Google.

Per trovare l'ID client e il client secret del tuo progetto, segui questi passaggi:

  1. Seleziona una credenziale OAuth 2.0 esistente o apri la pagina Credenziali.
  2. Se non l'hai ancora fatto, crea il protocollo OAuth 2.0 per il tuo progetto credenziali 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 cliente, seleziona il tipo di applicazione TV e dispositivi a input limitato.

Ottenere un codice utente e un URL di verifica

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

Di seguito è riportato un esempio di richiesta 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

Utilizzo di 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 all'ora interval specificata finché l'utente non accede o non è trascorso il 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, visualizzali 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. Progettazione la tua UI in modo da poter gestire i seguenti limiti:

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

Entrambe le stringhe possono contenere qualsiasi carattere stampabile dell'insieme di caratteri US-ASCII.

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

Puoi modificare la stringa verification_url rimuovendo lo schema da l'URL per la visualizzazione, se lo desideri. In questo caso, assicurati che la tua app possa gestire entrambe le varianti "http" e "https". Non modificare il valore Stringa verification_url.

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

Connettere un dispositivo inserendo un codice

Dopo che l'utente ha inserito il codice utente, il sito di accesso Google mostra una schermata di approvazione simile alla seguente:

Schermata di consenso di esempio per un client di dispositivo

Se l'utente fa clic su Consenti, la tua 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 l'app visualizza il codice utente e l'URL di verifica, inizia a eseguire il polling del endpoint token (https://oauth2.googleapis.com/token) con il codice del dispositivo che ricevuto dall'endpoint del dispositivo. Esegui un sondaggio sull'endpoint del token in corrispondenza dell'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

Utilizzo di 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"
}

L'app deve ripetere queste richieste a una frequenza che non superi il valore di interval. Se la tua app esegue il polling troppo rapidamente, la risposta è la seguente:

{
  "error" : "slow_down"
}

Dopo che l'utente avrà eseguito l'accesso e concesso alla tua app l'accesso agli ambiti che hai richiesto, la risposta alla prossima richiesta 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..."
}

Alla ricezione di questa risposta, la tua app può decodificare il token ID per ottenere le informazioni del profilo dell'utente che ha effettuato l'accesso oppure invia il token ID al tuo server di backend dell'app per eseguire l'autenticazione sicura sul server. Inoltre, la tua 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 oltre i token di aggiornamento, memorizza il token di aggiornamento e utilizzalo per richiedere di token.

Ottenere le informazioni del profilo utente dal token ID

Puoi ottenere le informazioni del profilo dell'utente che ha eseguito l'accesso decodificando l'ID con qualsiasi libreria di decodifica JWT. Ad esempio, l'uso della classe Auth0 Libreria JavaScript 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"];

Ulteriori informazioni