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 muestra un código corto y una URL de acceso al usuario. Luego, el usuario abre la URL de acceso en un navegador web, ingresa el código y le otorga permiso a la app para acceder a su información de acceso. Por último, la app recibe la confirmación y el usuario accede.

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 instrucciones para el usuario.
  • El dispositivo debe estar conectado a Internet.

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

Tu app necesita un ID de cliente 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 crearlas.
  3. Busca el ID de cliente en la sección IDs de cliente de OAuth 2.0. Para obtener más información, 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, obtienes un código de usuario y una URL de verificación. Para ello, envía una solicitud POST HTTP al extremo del dispositivo OAuth 2.0, https://oauth2.googleapis.com/device/code. Incluye tu ID de cliente y una lista de los alcances 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 quieres solicitar permiso para llamar a una API compatible en nombre de los usuarios, solicita los permisos necesarios además de los permisos 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=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

Usa curl de la siguiente manera:

curl -d "client_id=YOUR_GOOGLE_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 muestra los valores user_code y verification_url al usuario 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.

Muestra 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 pueda controlar los siguientes límites:

  • user_code se debe mostrar en un campo lo suficientemente ancho como para controlar 15 caracteres del tamaño de W.
  • verification_url se debe mostrar en un campo lo suficientemente amplio como para controlar una cadena de URL de 40 caracteres.

Ambas cadenas pueden contener cualquier carácter imprimible del grupo de caracteres US-ASCII.

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

Si lo deseas, puedes modificar la cadena verification_url quitando el esquema de la URL para fines de visualización. Si es así, asegúrate de que tu app pueda controlar las variantes "http" y "https". De lo contrario, no modifiques la cadena verification_url.

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

Cómo ingresar un código para conectar un dispositivo

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

Ejemplo de pantalla de consentimiento para un cliente de dispositivo

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

Obtén un token de ID y un token de actualización

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

La siguiente es una solicitud de ejemplo:

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

Usa curl de la siguiente manera:

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

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 velocidad que no exceda el valor de interval. Si tu app realiza sondeos demasiado rápido, la respuesta es la siguiente:

{
  "error" : "slow_down"
}

Una vez que el usuario accede y le otorga a tu app acceso a los permisos que solicitaste, la respuesta a la siguiente solicitud de tu app 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..."
}

Cuando recibes esta respuesta, tu app puede decodificar el token de ID para obtener información básica del perfil sobre el usuario que accedió o enviar el token de ID al servidor de backend de tu app para autenticarse de forma segura con el servidor. Además, tu app puede usar el token de acceso para llamar a las APIs de Google que el usuario autorizó.

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

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

Para obtener información de perfil sobre el usuario que accedió, debes 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(<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"];

Más información