Acceso en TVs y dispositivos de entrada limitados

Puedes permitir que los usuarios accedan a tu app con sus Cuentas de Google en dispositivos con capacidades de entrada limitadas, como TVs conectadas a Internet.

La app le muestra al usuario un código corto y una URL de acceso. Luego, el usuario abre la URL de acceso en un navegador web, ingresa el código y otorga permiso a la app para acceder a la información de acceso del usuario. Por último, la app recibe una confirmación y el usuario accede a su cuenta.

Para usar este flujo de acceso, la app debe ejecutarse en un dispositivo que cumpla con los siguientes criterios:

  • El dispositivo debe poder mostrar una URL de 40 caracteres y un código de usuario de 15 caracteres, junto con las instrucciones para el usuario.
  • El dispositivo debe estar conectado a Internet.

Obtén un ID de cliente y un secreto de cliente

Tu app necesita un ID y un secreto de cliente de OAuth 2.0 para realizar solicitudes a los extremos de acceso de Google.

Para encontrar el ID de cliente y el secreto de cliente de tu proyecto, haz lo siguiente:

  1. Selecciona una credencial de OAuth 2.0 existente o abre la página Credenciales.
  2. Si aún no lo hiciste, crea las credenciales de OAuth 2.0 de tu proyecto. Para ello, haz clic en Crear credenciales & ID de cliente de OAuth y proporciona la información necesaria para crear las credenciales.
  3. Busca ID de cliente en la sección ID de cliente de OAuth 2.0. Para obtener más detalles, haz clic en el ID de cliente.

Si estás creando un ID de cliente nuevo, selecciona el tipo de aplicación TVs y dispositivos de entrada limitada.

Obtén un código de usuario y una URL de verificación

Una vez que un usuario solicita acceder con una Cuenta de Google, puedes obtener un código de usuario y una URL de verificación mediante el envío de una solicitud HTTP POST al extremo del dispositivo de OAuth 2.0, https://oauth2.googleapis.com/device/code. Incluye tu ID de cliente y una lista de los permisos que necesitas con la solicitud. Si solo quieres que los usuarios accedan con sus Cuentas de Google, solicita solo los permisos profile y email. Si deseas solicitar permiso para llamar a una API compatible en nombre de los usuarios, solicita los alcances necesarios, además de los alcances profile y email.

A continuación, se muestra un ejemplo de solicitud de un código de usuario:

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

client_id=CLIENT_ID&scope=email%20profile

Usa curl de la siguiente manera:

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

La respuesta se muestra como un objeto JSON:

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

Tu app le muestra al usuario los valores de user_code y verification_url y, al mismo tiempo, sondea el extremo de acceso en el interval especificado hasta que el usuario accede o pasa el tiempo especificado por expires_in.

Mostrar el código de usuario y la URL de verificación

Después de recibir un código de usuario y una URL de verificación del extremo del dispositivo, muéstralos y pídele al usuario que abra la URL y que ingrese el código de usuario.

Los valores de verification_url y user_code están sujetos a cambios. Diseña tu IU de manera que admita los siguientes límites:

  • user_code debe mostrarse en un campo lo suficientemente ancho para manejar 15 caracteres de tamaño W.
  • verification_url debe mostrarse en un campo lo suficientemente ancho para controlar una string de URL de 40 caracteres.

Ambas strings pueden contener cualquier carácter imprimible del conjunto de caracteres US-ASCII.

Cuando muestras la string user_code, no la modifiques de ninguna manera (como cambiar mayúsculas y minúsculas, o insertar otros caracteres de formato), ya que tu app podría fallar si el formato del código cambia en el futuro.

Puedes modificar la string verification_url si quitas el esquema de la URL para fines de visualización, si así lo deseas. Si lo haces, asegúrate de que la app pueda manejar tanto las variantes como los http y https; De lo contrario, no modifiques la string verification_url.

Cuando el usuario navegue a la URL de verificación, verá una página similar a la siguiente:

Conecta un dispositivo ingresando un código

Después de que el usuario ingrese el código de usuario, el sitio de Acceso con Google presentará una pantalla de consentimiento similar a la siguiente:

Ejemplo de pantalla de consentimiento para un cliente del dispositivo

Si el usuario hace clic en Permitir, tu app puede obtener un token de ID a fin de identificarlo, un token de acceso para llamar a las API de Google y un token de actualización para adquirir tokens nuevos.

Cómo obtener un token de ID y un token de actualización

Después de que la app muestre el código del usuario y la URL de verificación, comienza a sondear el extremo del token (https://oauth2.googleapis.com/token) con el código del dispositivo que recibiste del extremo del dispositivo. Consulta el extremo del token en intervalos, en segundos, especificado por el valor interval.

A continuación, se muestra un ejemplo de solicitud:

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

Usa curl de la siguiente manera:

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

Si el usuario aún no aprobó la solicitud, la respuesta es la siguiente:

{
  "error" : "authorization_pending"
}

Tu app debe repetir estas solicitudes a una tasa que no supere el valor de interval. Si tu app realiza un sondeo demasiado rápido, la respuesta es la siguiente:

{
  "error" : "slow_down"
}

Una vez que el usuario accede y otorga a tu app los permisos que solicitaste, la respuesta a la siguiente solicitud incluirá un token de ID, un token de acceso y un token de actualización:

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

Una vez que se recibe esta respuesta, la app puede decodificar el token de ID para obtener información básica de perfil sobre el usuario que accedió o enviar el token de ID al servidor de backend de la app a fin de autenticar de forma segura con el servidor. Además, la app puede usar el token de acceso para llamar a las API de Google que autorizó el usuario.

Los tokens de ID y de acceso tienen una vida útil limitada. A fin de mantener el acceso del usuario más allá de los tokens, almacena el token de actualización y úsalo para solicitar tokens nuevos.

Cómo obtener información de perfil del usuario a partir del token de ID

Para obtener información de perfil del usuario que accedió, puedes decodificar el token de ID con cualquier biblioteca de decodificación de JWT. Por ejemplo, con la biblioteca de JavaScript jwt-decode de Auth0:

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"];

Más información