OAuth 2.0 para aplicaciones de TV y dispositivos de entrada limitada

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

OAuth 2.0 permite a los usuarios compartir datos específicos con una aplicación y, al mismo tiempo, mantiene nombres de usuario, contraseñas y otra información privada. Por ejemplo, una aplicación de TV podría usar OAuth 2.0 para obtener permiso para lo siguiente: seleccionar un archivo almacenado en Google Drive.

Debido a que las aplicaciones que usan este flujo se distribuyen a dispositivos individuales, es que las apps no pueden guardar Secrets. Pueden acceder a las APIs de Google mientras el usuario presentes en la app o cuando esta se ejecuta en segundo plano.

Alternativas

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

Si solo quieres que los usuarios accedan con sus Cuentas de Google y usar El token de ID JWT para obtener información básica del perfil del usuario. consulta Inicio de sesión 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 el API Console

Para habilitar una API en tu proyecto, haz lo siguiente:

  1. Open the API Library en Google API Console
  2. If prompted, select a project, or create a new one.
  3. El elemento API Library enumera todas las APIs disponibles, agrupadas por producto familia y popularidad. Si la API que quieres habilitar no está en la lista, usa la búsqueda para la encontrarás 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 utilice OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifican la aplicación en el servidor OAuth 2.0 de Google. Los siguientes pasos explican cómo crear credenciales para tu proyecto. Así, tus aplicaciones pueden usar las credenciales para acceder a las APIs que hayas habilitado 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 limitados.
  4. Asigna un nombre a tu cliente de OAuth 2.0 y haz clic en Crear.

Identifica los permisos de acceso

Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita, al tiempo que que les permite a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, hay puede ser una relación inversa entre el número de alcances 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 que identifiques los alcances. a las que tu app necesitará permiso para acceder.

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

Obtén tokens de acceso de OAuth 2.0

Si bien tu aplicación se ejecuta en un dispositivo con capacidades de entrada limitadas, los usuarios deben tener acceso independiente a un dispositivo con capacidades de entrada enriquecidas para completar este flujo de autorización. El flujo consta de los siguientes pasos:

  1. Tu aplicación envía una solicitud al servidor de autorización de Google que identifica los alcances. a los que tu aplicación solicitará permiso para acceder.
  2. El servidor responde con varios datos que se usan en los pasos posteriores, como un el código del dispositivo y el código de usuario.
  3. Muestra información que el usuario puede ingresar en otro dispositivo para autorizar tu .
  4. Tu aplicación empieza 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 mejores funciones de entrada, inicia un navegador web navega a la URL que se muestra en el paso 3 e ingresa un código que también se muestra en el paso 3. El 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 debe autorizar. solicitudes en nombre del usuario. (Si el usuario rechazó el acceso a la aplicación, la respuesta no contiene tokens).

En la siguiente imagen, se ilustra este proceso:

El usuario accede en otro dispositivo que tiene un navegador.

En las siguientes secciones, se explican estos pasos en detalle. Dada la variedad de capacidades y entornos de ejecución los entornos que pueden tener los dispositivos, en los ejemplos de este documento, se usa el curl utilidad de línea de comandos. Estos ejemplos deben ser fáciles de transferir a varios lenguajes y entornos de ejecución.

Paso 1: Solicita los códigos de dispositivo y de usuario

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

Parámetros
client_id Obligatorio

El ID de cliente de tu aplicación. Puedes encontrar este valor en API Console Credentials page
scope Obligatorio

R delimitado por espacios una lista de alcances que identifican los recursos a los que tu aplicación podría acceder en el nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario. Consulta la Lista de permisos permitidos para dispositivos o apps instalados.

Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita al mismo tiempo que permiten a los usuarios controlar el nivel de acceso que le otorgan a su y mantener la integridad de su aplicación. Por lo tanto, existe una relación inversa entre el número de alcances 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 exitosa

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

Propiedades
device_code Valor que Google asigna de forma única para identificar el dispositivo que ejecuta la app que solicita permiso autorización. El usuario autorizará ese dispositivo desde otro dispositivo con de entrada de texto. Por ejemplo, un usuario puede usar una laptop o un teléfono celular para autorizar un app que se ejecuta en una TV. En este caso, device_code identifica la TV.

Este código permite que el dispositivo, al ejecutar la app, determine de forma segura si el usuario otorgó o se les rechaza el acceso.
expires_in La cantidad de tiempo, en segundos, que los parámetros device_code y Las user_code son válidas. Si, en ese tiempo, el usuario no completa el de autorización y el dispositivo no sondea para obtener información sobre el decisión del usuario, deberás reiniciar este proceso desde el paso 1.
interval La cantidad de tiempo, en segundos, que el dispositivo debe esperar entre las solicitudes de sondeo. Para Por ejemplo, si el valor es 5, el dispositivo debería enviar una solicitud de sondeo a el servidor de autorización de Google cada cinco segundos. Consulta paso 3 para obtener más detalles.
user_code Un valor que distingue mayúsculas de minúsculas que le identifica a Google los alcances a los que está destinado la aplicación. solicitando acceso. Tu interfaz de usuario le indicará al usuario que ingrese este valor en un con capacidades de entrada enriquecidas. Luego, Google usa el valor para mostrar la con el conjunto correcto de alcances cuando le pidas al usuario que otorgue acceso a tu aplicación.
verification_url Una URL a la que el usuario debe navegar, en otro dispositivo, para ingresar el user_code y otorga o rechaza el acceso a tu aplicación. Tu interfaz de usuario también mostrará este valor.

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

{
  "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 las solicitudes de código de tu dispositivo han excedido la cuota asociada con tu ID de cliente, Reciben una respuesta 403, que contiene el siguiente error:

{
  "error_code": "rate_limit_exceeded"
}

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

Paso 3: Muestra el código de usuario

Muestra al verification_url y el user_code obtenidos en el paso 2 al usuario. Ambos valores pueden contener cualquier carácter imprimible del grupo de caracteres US-ASCII. El contenido que muestres al usuario deben indicarle que navegue a la verification_url en otro dispositivo y, luego, ingresa el user_code.

Ten en cuenta las siguientes reglas para diseñar tu interfaz de usuario (IU):

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

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

Dado que el usuario utilizará otro dispositivo para navegar a la verification_url y otorgan (o deniegan) acceso, el dispositivo solicitante no recibe una notificación automática cuando responde a la solicitud de acceso. Por ese motivo, el dispositivo solicitante debe sondear el de autorización del usuario para determinar cuándo el usuario respondió a la solicitud.

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

La URL del extremo para 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 API Console Credentials page
client_secret El secreto del cliente para el client_id proporcionado. Puedes encontrar este valor en API Console Credentials page
device_code El device_code que muestra el servidor de autorización en 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

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

Ingresa un código para conectar un dispositivo

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

Ejemplo de pantalla de consentimiento para un cliente de dispositivo

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 opciones: respuestas:

Se permite el acceso

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

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

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

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

{
  "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 acceder a una API durante un período extenso período, puede usar el token de actualización para obtener un nuevo acceso token. Si tu aplicación necesita este tipo de acceso, debe almacenar el token de actualización para su uso posterior.

Acceso denegado

Si el usuario se niega a otorgar acceso al dispositivo, la respuesta del servidor tendrá un Código de estado de respuesta HTTP 403 (Forbidden). La respuesta contiene 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"
}

Sondear con demasiada frecuencia

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

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

Otros errores

El servidor de autorización también devuelve errores si a la solicitud de sondeo le falta información obligatoria parámetros o tiene un valor de parámetro incorrecto. Estas solicitudes suelen tener un 400 Estado de respuesta HTTP (Bad Request) o 401 (Unauthorized) código. Entre esos errores, 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 la políticas de su administrador de Google Workspace. Consulta la ayuda para administradores de Google Workspace artículo Controle qué aplicaciones de terceros las apps internas acceden a los datos de Google Workspace para obtener más información sobre cómo una el administrador puede restringir el acceso a los permisos hasta que se otorgue acceso explícitamente a tu OAuth ID de cliente.
invalid_client 401

No se encontró el cliente de OAuth. Por ejemplo, este error ocurre si el El valor del parámetro client_id no es válido.

El tipo de cliente de OAuth es incorrecto. Asegúrate de que los tipo de aplicación para el ID de cliente se establece en TVs y dispositivos de entrada limitados.
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 de la solicitud forma parte de un proyecto que limita el acceso a las Cuentas de Google de una forma específica Organización de Google Cloud. Confirma el tipo de usuario actual de tu aplicación de OAuth.

Llama a las APIs de Google

Luego de que la aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a un servicio API en nombre de un proveedor de servicios de usuario si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API mediante una consulta access_token o un valor de encabezado HTTP Bearer Authorization. Cuando sea posible, se prefiere el encabezado HTTP, ya que las cadenas de consulta tienden a ser visibles en los registros del servidor. En la mayoría puedes usar una biblioteca cliente para configurar las llamadas a las APIs de Google (por ejemplo, cuando llamar a la API de Drive Files).

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

Ejemplos de solicitudes GET de HTTP

Un llamado a la drive.files extremo (la API de Drive Files) con el HTTP Authorization: Bearer el encabezado 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 access_token. Parámetro de cadena de consulta:

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 de curl. Este es un ejemplo que usa la opción de encabezado HTTP (preferida):

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

Como alternativa, 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 caducan periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Tú puede actualizar un token de acceso sin pedirle permiso al usuario (incluso cuando (inexistente) si solicitaste acceso sin conexión a los permisos asociados con el token.

Para actualizar un token de acceso, tu aplicación envía un POST HTTPS solicitud 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 del cliente obtenido de API Console.
grant_type Como definidas en el especificación de OAuth 2.0, el valor de este campo debe establecerse en refresh_token.
refresh_token El token de actualización que muestra el intercambio del código 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 devuelve un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra un ejemplo respuesta:

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

Ten en cuenta que existen límites en la cantidad de tokens de actualización que se emitirán. un límite por una combinación de cliente y usuario y otra por usuario en todos los clientes. Debes guardar los tokens de actualización. en un almacenamiento a largo plazo y seguir usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, se pueden alcanzar estos límites, en cuyo caso los tokens de actualización más antiguos dejará de funcionar.

Revoca un token

En algunos casos, es posible que el usuario desee revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso en Configuración de la cuenta. Consulta la Quitar Acceso al sitio o la aplicación de la sección de Sitios de terceros y apps 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 anula la suscripción, quita aplicación o los recursos de API necesarios para una aplicación han cambiado considerablemente. En otras palabras, parte del proceso de eliminación pueden incluir una solicitud a la API para garantizar que los permisos previos otorgadas a la aplicación.

Para revocar un token de manera programática, la aplicación realiza una solicitud a https://oauth2.googleapis.com/revoke e 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 de acceso o de actualización. Si el token es de acceso y tiene un token de actualización correspondiente, también se revocará el token de actualización.

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 el código de estado HTTP 400 junto con un código de error.

Permisos permitidos

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

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

Cómo implementar la Protección integral de la cuenta

Un paso adicional que debes seguir para proteger las contraseñas de cuentas está implementando Protección con el Servicio de protección integral de la cuenta de Google Este servicio te permite suscribirse a las notificaciones de eventos de seguridad, que proporcionan información a su aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decides responder a los eventos.

Estos son algunos ejemplos de los tipos de eventos que el Servicio de Protección integral de la cuenta 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 Cómo proteger las cuentas de usuario con la página Protección integral de la cuenta para obtener más información sobre cómo implementar la Protección integral de la cuenta y consultar la lista completa de eventos disponibles.