OAuth 2.0 para aplicaciones de TV y dispositivos de entrada limitada

Nota importante: Este flujo de OAuth 2.0 admite un conjunto limitado de permisos.

En este documento, se explica cómo implementar la autorización de OAuth 2.0 para acceder a las APIs de Google a través de aplicaciones que se ejecutan en dispositivos como TVs, consolas de juegos y, también, impresoras. Más específicamente, este flujo está diseñado para dispositivos que no tienen acceso a un navegador o que tienen capacidades de entrada limitadas.

OAuth 2.0 permite que los usuarios compartan datos específicos con una aplicación y, al mismo tiempo, mantengan la privacidad de sus nombres de usuario, contraseñas y otra información. Por ejemplo, una aplicación para TV podría usar OAuth 2.0 para obtener permiso para seleccionar un archivo almacenado en Google Drive.

Dado que las aplicaciones que usan este flujo se distribuyen a dispositivos individuales, se da por sentado que las apps no pueden guardar secretos. Pueden acceder a las APIs de Google mientras el usuario está presente en la app o cuando esta se ejecuta en segundo plano.

Alternativas

Si escribes una app para una plataforma como Android, iOS, macOS, Linux o Windows (incluida la plataforma universal de Windows) que tiene acceso al navegador y capacidades de entrada completas, usa el flujo de OAuth 2.0 para aplicaciones para computadoras y dispositivos móviles. (Debes usar ese flujo incluso si tu app es una herramienta de línea de comandos sin una interfaz gráfica).

Si solo deseas que los usuarios accedan con sus Cuentas de Google y usar el token de ID JWT para obtener información básica del perfil de usuario, consulta Acceso en TVs y dispositivos de entrada limitados.

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitarlas en API Console.

Para habilitar una API en tu proyecto, sigue estos pasos:

1. Open the API Library en Google API Console.
2. If prompted, select a project, or create a new one.
3. En la API Library , se enumeran todas las APIs disponibles, agrupadas por familia de productos y popularidad. Si la API que quieres habilitar no está en la lista, usa la búsqueda para encontrarla o haz clic en Ver todo en la familia de productos a la que pertenece.
4. Selecciona la API que deseas habilitar y, luego, haz clic en el botón Habilitar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Crea credenciales de autorización

Cualquier aplicación que use OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifiquen la aplicación para el servidor OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Luego, tus aplicaciones podrán usar las credenciales para acceder a las APIs que habilitaste para ese proyecto.

1. Go to the Credentials page.
2. Haz clic en Crear credenciales > ID de cliente de OAuth.
3. Selecciona el tipo de aplicación TVs y dispositivos de entrada limitada.
4. Asigna un nombre a tu cliente de OAuth 2.0 y haz clic en Crear.

Identifica los permisos de acceso

Los alcances permiten que la aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, puede haber una relación inversa entre la cantidad de permisos solicitados y la probabilidad de obtener el consentimiento del usuario.

Antes de que comiences a implementar la autorización de OAuth 2.0, te recomendamos identificar los alcances para los que la aplicación necesitará permiso de acceso.

Nota: La autorización incremental no es compatible con las apps o los dispositivos instalados.

Consulta la lista de Permisos permitidos para las apps o los dispositivos instalados.

Si tu aplicación pública usa permisos que permiten el acceso a ciertos datos del usuario, debe completar un proceso de verificación. Si ves app no verificada en la pantalla cuando pruebas tu aplicación, debes enviar una solicitud de verificación para quitarla. Obtén más información sobre las apps no verificadas y las respuestas a las preguntas frecuentes sobre la verificación de apps en el Centro de ayuda.

Obtén tokens de acceso de OAuth 2.0

Aunque tu aplicación se ejecute en un dispositivo con capacidades de entrada limitadas, los usuarios deben tener acceso independiente a un dispositivo con capacidades de entrada más enriquecidas para completar este flujo de autorización. El flujo tiene los siguientes pasos:

1. Tu aplicación envía una solicitud al servidor de autorización de Google que identifica los permisos a los que tu aplicación solicitará acceso.
2. El servidor responde con varios datos que se usan en pasos posteriores, como un código de dispositivo y un código de usuario.
3. Muestras información que el usuario puede ingresar en otro dispositivo para autorizar tu app.
4. Tu aplicación comienza a sondear el servidor de autorización de Google para determinar si el usuario autorizó tu app.
5. El usuario cambia a un dispositivo con capacidades de entrada más ricas, inicia un navegador web, navega a la URL que se muestra en el paso 3 y, luego, ingresa un código que también se muestra en el paso 3. Luego, el usuario puede otorgar (o denegar) el acceso a tu aplicación.
6. La siguiente respuesta a tu solicitud de sondeo contiene los tokens que tu app necesita para autorizar solicitudes en nombre del usuario. (Si el usuario rechazó el acceso a tu aplicación, la respuesta no contiene tokens).

En la siguiente imagen, se ilustra este proceso:

En las siguientes secciones, se explican estos pasos en detalle. Dado el rango de capacidades y entornos de tiempo de ejecución que pueden tener los dispositivos, los ejemplos que se muestran en este documento usan la utilidad de línea de comandos curl. Estos ejemplos deberían ser fáciles de portar a varios lenguajes y entornos de ejecución.

Paso 1: Solicita códigos de dispositivo y usuario

En este paso, tu dispositivo envía una solicitud POST HTTP al servidor de autorización de Google, en https://oauth2.googleapis.com/device/code, que identifica tu aplicación, así como los permisos de acceso a los que esta quiere acceder en nombre del usuario. Debes recuperar esta URL del documento de descubrimiento con el valor de metadatos device_authorization_endpoint. Incluye los siguientes parámetros de solicitud HTTP:

Parámetros
client_id	Obligatorio El ID de cliente de tu aplicación. Puedes encontrar este valor en el archivo API Console Credentials page.
scope	Obligatorio Es una lista de permisos delimitados por espacios que identifican los recursos a los que puede acceder tu aplicación en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario. Consulta la lista de Permisos permitidos para las apps o los dispositivos instalados. Los alcances permiten que la aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, existe una relación inversa entre la cantidad de permisos solicitados y la probabilidad de obtener el consentimiento del usuario.

Ejemplos

En el siguiente fragmento, se muestra una solicitud de muestra:

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

client_id=client_id&scope=email%20profile

En este ejemplo, se muestra un comando curl para enviar la misma solicitud:

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

Paso 2: Controla la respuesta del servidor de autorización

El servidor de autorización mostrará una de las siguientes respuestas:

Respuesta correcta

Si la solicitud es válida, la respuesta será un objeto JSON que contiene las siguientes propiedades:

Propiedades
device_code	Es un valor que Google asigna de forma exclusiva para identificar el dispositivo que ejecuta la app que solicita la autorización. El usuario autorizará ese dispositivo desde otro dispositivo con capacidades de entrada más enriquecidas. Por ejemplo, un usuario puede usar una laptop o un teléfono celular para autorizar una app que se ejecuta en una TV. En este caso, device_code identifica la TV. Este código permite que el dispositivo que ejecuta la app determine de forma segura si el usuario otorgó o negó el acceso.
expires_in	Es la cantidad de tiempo, en segundos, durante la cual device_code y user_code son válidos. Si, durante ese tiempo, el usuario no completa el flujo de autorización y tu dispositivo tampoco sondea para recuperar información sobre la decisión del usuario, es posible que debas reiniciar este proceso desde el paso 1.
interval	Es la cantidad de tiempo, en segundos, que el dispositivo debe esperar entre las solicitudes de sondeo. Por ejemplo, si el valor es 5, el dispositivo debe enviar una solicitud de sondeo al servidor de autorización de Google cada cinco segundos. Consulta el paso 3 para obtener más información.
user_code	Es un valor que distingue mayúsculas de minúsculas y que identifica a Google los permisos a los que la aplicación solicita acceso. Tu interfaz de usuario le indicará al usuario que ingrese este valor en un dispositivo independiente con capacidades de entrada más enriquecidas. Luego, Google usa el valor para mostrar el conjunto correcto de permisos cuando le solicita al usuario que otorgue acceso a tu aplicación.
verification_url	Es una URL a la que el usuario debe navegar, en un dispositivo independiente, para ingresar el user_code y otorgar o denegar el acceso a tu aplicación. Tu interfaz de usuario también mostrará este valor.

En el siguiente fragmento, se muestra una respuesta de ejemplo:

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

Respuesta de cuota excedida

Si tus solicitudes de código de dispositivo superaron la cuota asociada con tu ID de cliente, recibirás una respuesta 403 que contendrá el siguiente error:

{
  "error_code": "rate_limit_exceeded"
}

En ese caso, usa una estrategia de retirada para reducir la frecuencia de las solicitudes.

Paso 3: Muestra el código del usuario

Muestra los verification_url y user_code obtenidos en el paso 2 al usuario. Ambos valores pueden contener cualquier carácter imprimible del conjunto de caracteres US-ASCII. El contenido que le muestres al usuario debe indicarle que navegue a verification_url en otro dispositivo y que ingrese user_code.

Diseña tu interfaz de usuario (IU) teniendo en cuenta las siguientes reglas:

• user_code
  • El user_code debe mostrarse en un campo que pueda controlar 15 caracteres de tamaño "W". En otras palabras, si puedes mostrar el código WWWWWWWWWWWWWWW correctamente, tu IU es válida y te recomendamos que uses ese valor de cadena cuando pruebes la forma en que se muestra user_code en tu IU.
  • user_code distingue mayúsculas de minúsculas y no se debe modificar de ninguna manera, como cambiar la mayúscula o insertar otros caracteres de formato.
• verification_url
  • El espacio en el que se muestra el verification_url debe ser lo suficientemente ancho como para controlar una cadena de URL de 40 caracteres.
  • No debes modificar verification_url de ninguna manera, excepto para quitar el esquema de visualización de forma opcional. Si planeas quitar el esquema (p.ej., https://) de la URL por motivos de visualización, asegúrate de que tu app pueda controlar las variantes http y https.

Advertencia: Ambos valores están sujetos a cambios, y no debes codificar ninguno de ellos en tu código. Del mismo modo, no debes modificar los valores de ninguna manera, excepto quitar el esquema de verification_url de forma opcional.

Paso 4: Consulta el servidor de autorización de Google

Como el usuario usará un dispositivo independiente para navegar a verification_url y otorgar (o denegar) el acceso, el dispositivo solicitante no recibirá una notificación automática cuando el usuario responda a la solicitud de acceso. Por esa razón, el dispositivo solicitante debe sondear el servidor de autorización de Google para determinar cuándo el usuario respondió la solicitud.

El dispositivo solicitante debe seguir enviando solicitudes de sondeo hasta que reciba una respuesta que indique que el usuario respondió a la solicitud de acceso o hasta que venza el device_code y el user_code obtenidos en el paso 2. El interval que se muestra en el paso 2 especifica la cantidad de tiempo, en segundos, que se debe esperar entre las solicitudes.

La URL del extremo que se sondeará es https://oauth2.googleapis.com/token. La solicitud de sondeo contiene los siguientes parámetros:

Parámetros
client_id	El ID de cliente de tu aplicación. Puedes encontrar este valor en el API Console Credentials page.
client_secret	El secreto del cliente para el client_id proporcionado. Puedes encontrar este valor en el API Console Credentials page.
device_code	El device_code que muestra el servidor de autorización en el paso 2
grant_type	Configura este valor en urn:ietf:params:oauth:grant-type:device_code.

Ejemplos

En el siguiente fragmento, se muestra una solicitud de muestra:

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

En este ejemplo, se muestra un comando curl para enviar la misma solicitud:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Paso 5: El usuario responde a la solicitud de acceso

Nota: Tu aplicación no necesita hacer nada en esta etapa, además de sondear el servidor de autorización como se describe en el paso anterior.

En la siguiente imagen, se muestra una página similar a la que ven los usuarios cuando navegan al verification_url que mostraste en el paso 3:

Después de ingresar el user_code y, si aún no lo hizo, acceder a Google, el usuario verá una pantalla de consentimiento como la que se muestra a continuación:

Paso 6: Controla las respuestas a las solicitudes de sondeo

El servidor de autorización de Google responde a cada solicitud de sondeo con una de las siguientes respuestas:

Acceso otorgado

Si el usuario otorgó acceso al dispositivo (haciendo clic en Allow en la pantalla de consentimiento), la respuesta contiene un token de acceso y un token de actualización. Los tokens permiten que tu dispositivo acceda a las APIs de Google en nombre del usuario. (La propiedad scope de la respuesta determina a qué APIs puede acceder el dispositivo).

En este caso, la respuesta de la API contiene los siguientes campos:

Campos
access_token	Es el token que envía tu aplicación para autorizar una solicitud a la API de Google.
expires_in	Es la vida útil restante del token de acceso en segundos.
refresh_token	Es un token que puedes usar para obtener un nuevo token de acceso. Los tokens de actualización son válidos hasta que el usuario revoca el acceso. Ten en cuenta que los tokens de actualización siempre se devuelven para los dispositivos.
scope	Los permisos de acceso que otorga access_token expresados como una lista de cadenas delimitadas por espacios y que distinguen mayúsculas de minúsculas.
token_type	Es el tipo de token que se muestra. En este momento, el valor de este campo siempre se establece en Bearer.

En el siguiente fragmento, se muestra una respuesta de ejemplo:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Los tokens de acceso tienen una vida útil limitada. Si tu aplicación necesita acceso a una API durante un período prolongado, puede usar el token de actualización para obtener un token de acceso nuevo. Si tu aplicación necesita este tipo de acceso, debe almacenar el token de actualización para usarlo más adelante.

Acceso denegado

Si el usuario se niega a otorgar acceso al dispositivo, la respuesta del servidor tiene un código de estado de respuesta HTTP 403 (Forbidden). La respuesta contiene el siguiente error:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Autorización pendiente

Si el usuario aún no completó el flujo de autorización, el servidor muestra un código de estado de respuesta HTTP 428 (Precondition Required). La respuesta contiene el siguiente error:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Sondeos demasiado frecuentes

Si el dispositivo envía solicitudes de sondeo con demasiada frecuencia, el servidor muestra un código de estado de respuesta HTTP 403 (Forbidden). La respuesta contiene el siguiente error:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Otros errores

El servidor de autorización también muestra errores si a la solicitud de sondeo le faltan parámetros obligatorios o tiene un valor de parámetro incorrecto. Por lo general, estas solicitudes tienen un código de estado de respuesta HTTP 400 (Bad Request) o 401 (Unauthorized). Entre ellos, se incluyen los siguientes:

Error	Código de estado HTTP	Descripción
admin_policy_enforced	400	La Cuenta de Google no puede autorizar uno o más permisos solicitados debido a las políticas de su administrador de Google Workspace. Consulta el artículo de ayuda para administradores de Google Workspace Controla qué apps internas y de terceros acceden a los datos de Google Workspace para obtener más información sobre cómo un administrador puede restringir el acceso a los permisos hasta que se otorgue acceso de forma explícita a tu ID de cliente de OAuth.
invalid_client	401	No se encontró el cliente de OAuth. Por ejemplo, este error se produce si el valor del parámetro client_id no es válido. El tipo de cliente de OAuth es incorrecto. Asegúrate de que el tipo de aplicación para el ID de cliente esté configurado como TVs y dispositivos de entrada limitada.
invalid_grant	400	El valor del parámetro code no es válido, ya se reclamó o no se puede analizar.
unsupported_grant_type	400	El valor del parámetro grant_type no es válido.
org_internal	403	El ID de cliente de OAuth en la solicitud forma parte de un proyecto que limita el acceso a las Cuentas de Google en una organización de Google Cloud específica. Confirma la configuración del tipo de usuario para tu aplicación de OAuth.

Cómo llamar a las APIs de Google

Una vez que tu aplicación obtenga un token de acceso, podrás usarlo para realizar llamadas a una API de Google en nombre de una cuenta de usuario determinada si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API con un parámetro de consulta access_token o un valor Bearer de encabezado HTTP Authorization. Cuando sea posible, se prefiere el encabezado HTTP, ya que las cadenas de consulta suelen ser visibles en los registros del servidor. En la mayoría de los casos, puedes usar una biblioteca cliente para configurar tus llamadas a las APIs de Google (por ejemplo, cuando llamas a la API de Drive Files).

Puedes probar todas las APIs de Google y ver sus permisos en OAuth 2.0 Playground.

Ejemplos de HTTP GET

Una llamada al extremo drive.files (la API de Files de Drive) con el encabezado HTTP Authorization: Bearer podría verse de la siguiente manera: Ten en cuenta que debes especificar tu propio token de acceso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta es una llamada a la misma API para el usuario autenticado con el parámetro de cadena de consulta access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Ejemplos de curl

Puedes probar estos comandos con la aplicación de línea de comandos curl. A continuación, se muestra un ejemplo que usa la opción de encabezado HTTP (preferida):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

O bien, la opción de parámetro de cadena de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Actualización de un token de acceso

Los tokens de acceso vencen periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Puedes actualizar un token de acceso sin solicitarle permiso al usuario (incluso cuando no está presente) si solicitaste acceso sin conexión a los alcances asociados con el token.

Para actualizar un token de acceso, tu aplicación envía una solicitud POST HTTPS al servidor de autorización de Google (https://oauth2.googleapis.com/token) que incluye los siguientes parámetros:

Campos
client_id	El ID de cliente obtenido de API Console.
client_secret	El secreto de cliente obtenido de API Console
grant_type	Como se define en la especificación de OAuth 2.0, el valor de este campo debe establecerse en refresh_token.
refresh_token	El token de actualización que se muestra después del intercambio de códigos de autorización.

En el siguiente fragmento, se muestra una solicitud de muestra:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Siempre que el usuario no haya revocado el acceso otorgado a la aplicación, el servidor de tokens muestra un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra una respuesta de ejemplo:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Ten en cuenta que hay límites en la cantidad de tokens de actualización que se emitirán: un límite por combinación de cliente/usuario y otro por usuario en todos los clientes. Debes guardar los tokens de actualización en el almacenamiento a largo plazo y seguir usándolos mientras sigan siendo válidos. Si tu aplicación solicita demasiados tokens de actualización, es posible que se encuentre con estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.

Cómo revocar un token

En algunos casos, es posible que un usuario desee revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso en Configuración de la cuenta. Consulta la sección Cómo quitar el acceso de un sitio o una app del documento de asistencia Sitios y apps de terceros con acceso a tu cuenta para obtener más información.

También es posible que una aplicación revoque de forma programática el acceso que se le otorgó. La revocación programática es importante en los casos en que un usuario cancela su suscripción, quita una aplicación o los recursos de la API que requiere una app cambiaron de forma significativa. En otras palabras, parte del proceso de eliminación puede incluir una solicitud a la API para garantizar que se quiten los permisos otorgados anteriormente a la aplicación.

Para revocar un token de manera programática, tu aplicación envía una solicitud a https://oauth2.googleapis.com/revoke y, además, incluye el token como parámetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

El token puede ser un token de acceso o un token de actualización. Si el token es un token de acceso y tiene un token de actualización correspondiente, este también se revocará.

Si la revocación se procesa correctamente, el código de estado HTTP de la respuesta es 200. Para las condiciones de error, se muestra un código de estado HTTP 400 junto con un código de error.

Nota: Después de una respuesta de revocación correcta, es posible que demore un poco antes de que la revocación tenga efecto total.

Alcances permitidos

El flujo de OAuth 2.0 para dispositivos solo es compatible con los siguientes permisos:

OpenID Connect, Acceso con Google

• email
• openid
• profile

API de Drive

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

API de YouTube

• https://www.googleapis.com/auth/youtube
• https://www.googleapis.com/auth/youtube.readonly

Implementa la Protección integral de la cuenta

Un paso adicional que debes seguir para proteger las cuentas de tus usuarios es implementar la Protección entre cuentas con el servicio de Protección entre cuentas de Google. Este servicio te permite suscribirte a notificaciones de eventos de seguridad que proporcionan información a tu aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decidas responder a los eventos.

Estos son algunos ejemplos de los tipos de eventos que el servicio de Protección entre cuentas de Google envía a tu app:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulta la página Protege las cuentas de usuario con la Protección integral de la cuenta para obtener más información sobre cómo implementar la Protección integral de la cuenta y ver la lista completa de eventos disponibles.