Accesso su TV e dispositivi di immissione limitati

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

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

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

  • Il dispositivo deve essere in grado di visualizzare 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.

Ottieni un ID client e un client secret

La tua 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, procedi come segue:

  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 informazioni dettagliate, fai clic sull'ID client.

Se crei un nuovo ID client, seleziona il tipo di applicazione TV e dispositivi di input limitati.

Ottenere un codice utente e un URL di verifica

Quando un utente richiede l'accesso utilizzando un Account Google, ricevi 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 obbligatori oltre agli ambiti profile e email.

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=CLIENT_ID&scope=email%20profile

Con curl:

curl -d "client_id=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 visualizza i valori user_code e verification_url per l'utente e, contemporaneamente, esegue il polling dell'endpoint di accesso all'interval specificato fino a quando l'utente non accede o è trascorso il tempo specificato da expires_in.

Mostrare 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 di inserire il codice utente.

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

  • user_code deve essere visualizzato in un campo abbastanza ampio da gestire 15 caratteri di dimensione W.
  • verification_url deve essere visualizzato in un campo abbastanza largo da 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 modificare in alcun modo la stringa (ad esempio cambiando la maiuscola iniziale o l'inserimento di altri caratteri di formattazione), perché la tua app potrebbe smettere di funzionare se il formato del codice cambia in futuro.

Se vuoi, puoi modificare la stringa verification_url rimuovendo lo schema dall'URL per scopi di visualizzazione. In questo caso, assicurati che la tua app possa gestire sia le varianti "http" e "https". Non modificare la stringa verification_url.

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

Collega un dispositivo inserendo un codice

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

Schermata di consenso di esempio per un client 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 Google e un token di aggiornamento per acquisire nuovi token.

Ottenere un token ID e un token di aggiornamento

Dopo che l'app ha visualizzato 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 dispositivo che hai ricevuto dall'endpoint del dispositivo. Esegui il polling dell'endpoint del token all'intervallo, in secondi, specificato dal valore interval.

Di seguito è riportato un esempio di richiesta:

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

client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

Con curl:

curl -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=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 non superiore al valore di interval. Se la tua app esegue un sondaggio troppo rapidamente, la risposta è la seguente:

{
  "error" : "slow_down"
}

Dopo che l'utente ha eseguito l'accesso e concesso l'accesso dell'app agli ambiti richiesti, 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..."
}

Quando riceve questa risposta, l'app può decodificare il token ID per ricevere informazioni di base sul profilo dell'utente che ha eseguito l'accesso o inviare il token ID al server di backend dell'app per l'autenticazione sicura 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 fare in modo che l'utente abbia eseguito l'accesso oltre i token, memorizza il token di aggiornamento e utilizzalo per richiedere nuovi token.

Recupera le informazioni del profilo utente dal token ID

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

var user_profile = jwt_decode(id_token);

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