OAuth 2.0 para aplicaciones de TV y dispositivos de entrada limitada

En este documento, se explica cómo implementar la autorización de OAuth 2.0 para acceder a las APIs de Google con aplicaciones que se ejecutan en dispositivos como TVs, consolas de juegos y 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 de 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 supone que las apps no pueden mantener 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 solo quieres que los usuarios accedan con sus Cuentas de Google y usen el token de ID de JWT para obtener información básica del perfil de usuario, consulta Acceso en TVs y dispositivos de entrada limitada.

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitar esas APIs en la Consola de APIs.

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

1. Abre la Biblioteca de APIs en la Consola de APIs de Google.
2. Si se te solicita, selecciona un proyecto o crea uno nuevo.
3. La Biblioteca de APIs muestra 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. Si se te solicita, habilita la facturación.
6. Si se te solicita, lee y acepta las Condiciones del Servicio de la API.

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 la identifiquen ante el servidor de OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Luego, tus aplicaciones pueden usar las credenciales para acceder a las APIs que habilitaste para ese proyecto.

1. Ve a la página Clientes.
2. Haz clic en Crear cliente.
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.

Identificar los permisos de acceso

Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita y, al mismo tiempo, permiten que los usuarios controlen la cantidad 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 comenzar a implementar la autorización de OAuth 2.0, te recomendamos que identifiques los permisos a los que tu app necesitará acceder.

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

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 completas 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 para los que tu aplicación solicitará acceso.
2. El servidor responde con varios datos que se usan en los pasos posteriores, como un código de dispositivo y un código de usuario.
3. Muestras información que el usuario puede ingresar en un dispositivo independiente 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 funciones de entrada más completas, 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 imagen, se ilustra este proceso:

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

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

En este paso, tu dispositivo envía una solicitud POST de HTTP al servidor de autorización de Google, en https://oauth2.googleapis.com/device/code, que identifica tu aplicación y los permisos de acceso a los que tu aplicación 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:

Ejemplos

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

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 devolverá una de las siguientes respuestas:

Respuesta exitosa

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

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 de usuario

Muestra al usuario el verification_url y el user_code que se obtuvieron en el paso 2. 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 un dispositivo independiente y que ingrese el 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 admitir 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 el user_code en tu IU.
  • El user_code distingue mayúsculas de minúsculas y no se debe modificar de ninguna manera, como cambiar las mayúsculas y minúsculas o insertar otros caracteres de formato.
• verification_url
  • El espacio en el que se muestra la verification_url debe ser lo suficientemente amplio como para admitir una cadena de URL de 40 caracteres.
  • No debes modificar el verification_url de ninguna manera, excepto para quitar opcionalmente el esquema de visualización. 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.

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

Dado que el usuario usará un dispositivo independiente para navegar a la verification_url y otorgar (o denegar) el acceso, el dispositivo solicitante no recibe una notificación automática cuando el usuario responde a la solicitud de acceso. Por ese motivo, el dispositivo solicitante debe sondear el servidor de autorización de Google para determinar cuándo respondió el usuario a 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 venzan los valores de device_code y user_code obtenidos en el paso 2. El interval que se devuelve en el paso 2 especifica la cantidad de tiempo, en segundos, que se debe esperar entre las solicitudes.

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

Ejemplos

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

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 la que ven los usuarios cuando navegan a la verification_url que mostraste en el paso 3:

Después de ingresar el user_code y, si aún no accedió, acceder a Google, el usuario verá una pantalla de consentimiento:

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 contendrá 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:

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 acceder a una API durante un período prolongado, puede usar el token de actualización para obtener un nuevo token de acceso. 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 tendrá un código de estado de respuesta HTTP 403 (Forbidden). La respuesta contendrá 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 devuelve un código de estado de respuesta HTTP 428 (Precondition Required). La respuesta contiene el siguiente error:

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

Sondeo demasiado frecuente

Si el dispositivo envía solicitudes de sondeo con demasiada frecuencia, el servidor devuelve 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 devuelve errores si a la solicitud de sondeo le falta algún parámetro obligatorio 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:

Llama a las APIs de Google

Después de que tu aplicación obtenga un token de acceso, puedes 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 de encabezado HTTP Authorization Bearer. Cuando sea posible, es preferible 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 Drive Files) 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

Aquí se muestra 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 de curl. A continuación, se muestra un ejemplo en el que se usa la opción de encabezado HTTP (preferida):

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

O, 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 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 permisos asociados con el token.

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

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

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

client_id=your_client_id&
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 devolverá 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 y usuario, y otro por usuario en todos los clientes. Debes guardar los tokens de actualización en un 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 alcance estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.

Revocación de tokens

En algunos casos, es posible que un usuario quiera revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso visitando la configuración de la cuenta. Consulta la sección Quita el acceso de un sitio o una app de terceros con acceso a tu cuenta del documento de asistencia 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 la 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 realiza una solicitud a https://oauth2.googleapis.com/revoke y, luego, incluye el token como un 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. En caso de condiciones de error, se devuelve un código de estado HTTP 400 junto con un código de error.

Permisos aceptados

El flujo de OAuth 2.0 para dispositivos solo se admite en los siguientes permisos:

Acceso basado en el tiempo

El acceso basado en el tiempo permite que un usuario otorgue a tu app acceso a sus datos durante un período limitado para completar una acción. El acceso basado en el tiempo está disponible en algunos productos de Google durante el flujo de consentimiento, lo que les permite a los usuarios otorgar acceso por un período limitado. Un ejemplo es la API de Data Portability, que permite una transferencia de datos única.

Cuando un usuario otorga a tu aplicación acceso basado en el tiempo, el token de actualización vencerá después de la duración especificada. Ten en cuenta que los tokens de actualización pueden invalidarse antes en circunstancias específicas. Consulta estos casos para obtener más detalles. El campo refresh_token_expires_in que se devuelve en la respuesta del intercambio de código de autorización representa el tiempo restante hasta que venza el token de actualización en esos casos.