Acceso en TVs y dispositivos de entrada limitados

Puedes permitir que los usuarios accedan a la app con sus Cuentas de Google en dispositivos con capacidades de entrada limitadas, como las 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 le otorga a la app permiso para acceder a la información de acceso del usuario. 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 de 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 crear las credenciales.
  3. Busca el 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 and Limited Input devices.

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

Cuando 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 alcances que necesitas con la solicitud. Si solo quieres que los usuarios accedan con sus Cuentas de Google, solicita únicamente los alcances profile y email. Si deseas solicitar permiso para llamar a una API compatible en nombre de los usuarios, solicita los permisos necesarios además de los alcances profile y email.

A continuación, se muestra un ejemplo de solicitud para 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
}

La app le muestra al usuario los valores user_code y verification_url y, al mismo tiempo, sondea el extremo de acceso en el interval especificado hasta que el usuario acceda o haya pasado la hora especificada 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, luego, indícale al usuario que abra la URL y, luego, 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 tal que pueda controlar los siguientes límites:

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

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

Cuando muestres 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 lo deseas. Si lo haces, asegúrate de que tu app pueda admitir variantes "http" y "https". No modifiques la string verification_url.

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

Ingresa un código para conectar un dispositivo

Una vez 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, la 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 la app muestre el código de usuario y la URL de verificación, comienza a sondear el extremo del token (https://oauth2.googleapis.com/token) con el código de dispositivo que recibiste de él. Sondea el extremo del token en el intervalo, en segundos, especificado por el valor interval.

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

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 sondea 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 próxima solicitud de tu app incluye 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 recibe esta respuesta, tu app puede decodificar el token de ID para obtener información de perfil básica 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, la app puede usar el token de acceso para llamar a las APIs de Google que autorizó el usuario.

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

Obtén información de perfil del usuario a partir del token de ID

Puedes obtener la información de perfil sobre el usuario que accedió mediante la decodificación del token de ID con cualquier biblioteca de decodificación JWT. Por ejemplo, con la biblioteca 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