OAuth 2.0 para TV y aplicaciones de dispositivos de entrada limitada

Este documento explica cómo implementar la autorización OAuth 2.0 para acceder a las API de Google a través de aplicaciones que se ejecutan en dispositivos como televisores, consolas de juegos e impresoras. Más específicamente, este flujo está diseñado 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 manteniendo 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 utilizan este flujo se distribuyen a dispositivos individuales, se supone que las aplicaciones no pueden guardar secretos. Pueden acceder a las API de Google mientras el usuario está presente en la aplicación o cuando la aplicación se ejecuta en segundo plano.

Alternativas

Si está escribiendo una aplicación 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, use el flujo de OAuth 2.0 para aplicaciones móviles y de escritorio . (Debe usar ese flujo incluso si su aplicación es una herramienta de línea de comandos sin una interfaz gráfica).

Si solo desea iniciar sesión en los usuarios con sus cuentas de Google y usar el token de ID de JWT para obtener información básica del perfil de usuario, consulte Inicio de sesión en televisores y dispositivos de entrada limitada .

requisitos previos

Habilite las API para su proyecto

Cualquier aplicación que llame a las API de Google debe habilitar esas API en API Console.

Para habilitar una API para su proyecto:

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

Crear credenciales de autorización

Cualquier aplicación que use OAuth 2.0 para acceder a las API de Google debe tener credenciales de autorización que identifiquen la aplicación en el servidor OAuth 2.0 de Google. Los siguientes pasos explican cómo crear credenciales para su proyecto. Luego, sus aplicaciones pueden usar las credenciales para acceder a las API que ha habilitado para ese proyecto.

  1. Go to the Credentials page.
  2. Haga clic en Crear credenciales > ID de cliente de OAuth .
  3. Seleccione el tipo de aplicación TV y dispositivos de entrada limitada .
  4. Asigne un nombre a su cliente OAuth 2.0 y haga clic en Crear .

Identificar ámbitos de acceso

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

Antes de comenzar a implementar la autorización de OAuth 2.0, le recomendamos que identifique los ámbitos a los que su aplicación necesitará permiso para acceder.

Consulte la lista de ámbitos permitidos para aplicaciones o dispositivos instalados.

Obtención de tokens de acceso OAuth 2.0

Aunque su 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 más ricas para completar este flujo de autorización. El flujo tiene los siguientes pasos:

  1. Su aplicación envía una solicitud al servidor de autorización de Google que identifica los ámbitos a los que su aplicación solicitará permiso para acceder.
  2. El servidor responde con varios datos que se utilizan en pasos posteriores, como un código de dispositivo y un código de usuario.
  3. Muestra información que el usuario puede ingresar en un dispositivo separado para autorizar su aplicación.
  4. Su aplicación comienza a sondear el servidor de autorización de Google para determinar si el usuario autorizó su aplicación.
  5. El usuario cambia a un dispositivo con mayores capacidades 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 usuario puede otorgar (o denegar) el acceso a su aplicación.
  6. La siguiente respuesta a su solicitud de sondeo contiene los tokens que su aplicación necesita para autorizar solicitudes en nombre del usuario. (Si el usuario rechazó el acceso a su aplicación, la respuesta no contiene tokens).

La siguiente imagen ilustra este proceso:

El usuario inicia sesión en un dispositivo separado que tiene un navegador

Las siguientes secciones explican estos pasos en detalle. Dada la variedad de capacidades y entornos de tiempo de ejecución que pueden tener los dispositivos, los ejemplos que se muestran en este documento utilizan la utilidad de línea de comando curl . Estos ejemplos deberían ser fáciles de migrar a varios idiomas y tiempos de ejecución.

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

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

Parámetros
client_id Requerido

El ID de cliente para su aplicación. Puede encontrar este valor en API ConsoleCredentials page.

scope Requerido

Una lista delimitada por espacios de ámbitos que identifican los recursos a los que su aplicación podría acceder en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario. Consulte la lista de ámbitos permitidos para aplicaciones o dispositivos instalados.

Los ámbitos permiten que su aplicación solo solicite acceso a los recursos que necesita, al mismo tiempo que permite a los usuarios controlar la cantidad de acceso que otorgan a 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

El siguiente fragmento 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

Este ejemplo 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: Manejar la respuesta del servidor de autorizaciones

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

Respuesta de éxito

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

Propiedades
device_code Un valor que Google asigna de forma única para identificar el dispositivo que ejecuta la aplicación que solicita autorización. El usuario autorizará ese dispositivo desde otro dispositivo con mayores capacidades de entrada. Por ejemplo, un usuario puede usar una computadora portátil o un teléfono móvil para autorizar una aplicación que se ejecuta en un televisor. En este caso, el device_code identifica el televisor.

Este código permite que el dispositivo que ejecuta la aplicación determine de forma segura si el usuario ha concedido o denegado el acceso.

expires_in El período de tiempo, en segundos, que el device_code y el user_code son válidos. Si, en ese momento, el usuario no completa el flujo de autorización y su dispositivo tampoco realiza un sondeo para recuperar información sobre la decisión del usuario, es posible que deba reiniciar este proceso desde el paso 1.
interval El tiempo, en segundos, que su dispositivo debe esperar entre las solicitudes de sondeo. Por ejemplo, si el valor es 5 , su dispositivo debería enviar una solicitud de sondeo al servidor de autorización de Google cada cinco segundos. Consulte el paso 3 para obtener más detalles.
user_code Un valor que distingue entre mayúsculas y minúsculas que identifica a Google los ámbitos a los que la aplicación solicita acceso. Su interfaz de usuario le indicará al usuario que ingrese este valor en un dispositivo separado con capacidades de entrada más ricas. Luego, Google usa el valor para mostrar el conjunto correcto de ámbitos cuando solicita al usuario que otorgue acceso a su aplicación.
verification_url Una URL a la que el usuario debe navegar, en un dispositivo separado, para ingresar el user_code de usuario y otorgar o denegar el acceso a su aplicación. Su interfaz de usuario también mostrará este valor.

El siguiente fragmento 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 sus solicitudes de código de dispositivo han excedido la cuota asociada con su ID de cliente, recibirá una respuesta 403 que contiene el siguiente error:

{
  "error_code": "rate_limit_exceeded"
}

En ese caso, utilice una estrategia de retroceso para reducir la tasa de solicitudes.

Paso 3: Mostrar el código de usuario

Muestre la URL de verification_url y el código de user_code obtenidos en el paso 2 al usuario. Ambos valores pueden contener cualquier carácter imprimible del juego de caracteres US-ASCII. El contenido que le muestra al usuario debe indicarle que navegue hasta la verification_url en un dispositivo separado e ingrese el user_code .

Diseñe su interfaz de usuario (UI) teniendo en cuenta las siguientes reglas:

  • user_code
    • El user_code de usuario debe mostrarse en un campo que pueda manejar caracteres de tamaño 15 'W'. En otras palabras, si puede mostrar el código WWWWWWWWWWWWWWW correctamente, su interfaz de usuario es válida y recomendamos usar ese valor de cadena cuando pruebe la forma en que se muestra el user_code de usuario en su interfaz de usuario.
    • El user_code de usuario distingue entre mayúsculas y minúsculas y no debe modificarse de ninguna manera, como cambiar el caso o insertar otros caracteres de formato.
  • verification_url
    • El espacio en el que muestres la verification_url debe ser lo suficientemente ancho para admitir una cadena de URL de 40 caracteres.
    • No debe modificar la verification_url de ninguna manera, excepto para eliminar opcionalmente el esquema para su visualización. Si planea eliminar el esquema (por ejemplo, https:// ) de la URL por razones de visualización, asegúrese de que su aplicación pueda manejar las variantes http y https .

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

Dado que el usuario utilizará 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 el usuario ha respondido a la solicitud.

El dispositivo solicitante debe continuar enviando solicitudes de sondeo hasta que reciba una respuesta que indique que el usuario ha respondido a la solicitud de acceso o hasta que caduquen el device_code y el user_code obtenidos en el paso 2 . El interval devuelto en el paso 2 especifica la cantidad de tiempo, en segundos, para esperar entre solicitudes.

La URL del punto final 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 para su aplicación. Puede encontrar este valor en API ConsoleCredentials page.
client_secret El secreto del cliente para el client_id proporcionado. Puede encontrar este valor en API ConsoleCredentials page.
device_code El device_code devuelto por el servidor de autorización en el paso 2 .
grant_type Establezca este valor en urn:ietf:params:oauth:grant-type:device_code .

Ejemplos

El siguiente fragmento 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

Este ejemplo 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" \
         /token

Paso 5: El usuario responde a la solicitud de acceso

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

Conectar un dispositivo ingresando un código

Después de ingresar el user_code de usuario y, si aún no ha iniciado sesión, iniciar sesión en 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: Manejar 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 permitido

Si el usuario concedió 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 su dispositivo acceda a las API de Google en nombre del usuario. (La propiedad de scope en la respuesta determina a qué API puede acceder el dispositivo).

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

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

El siguiente fragmento 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 su aplicación necesita acceso a una API durante un largo período de tiempo, puede usar el token de actualización para obtener un nuevo token de acceso. Si su 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 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 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"
}

Votar con demasiada frecuencia

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 requerido o tiene un valor de parámetro incorrecto. Estas solicitudes suelen tener un código de estado de respuesta HTTP 400 ( Bad Request ) o 401 ( Unauthorized ). Esos errores incluyen:

Error Código de estado HTTP Descripción
invalid_client 401 No se encontró el cliente de OAuth. Por ejemplo, este error ocurre si el valor del parámetro client_id no es válido.
invalid_grant 400 El valor del parámetro code no es válido.
unsupported_grant_type 400 El valor del parámetro grant_type no es válido.

Llamar a las API de Google

Después de que su aplicación obtenga un token de acceso, puede utilizar el token para realizar llamadas a una API de Google en nombre de una cuenta de usuario determinada si se han otorgado los alcances de acceso requeridos por la API. Para hacer esto, incluya el token de acceso en una solicitud a la API incluyendo un parámetro de consulta access_token o un valor de Bearer de encabezado HTTP de Authorization . Cuando sea posible, es preferible el encabezado HTTP, porque las cadenas de consulta tienden a ser visibles en los registros del servidor. En la mayoría de los casos, puede usar una biblioteca cliente para configurar sus llamadas a las API de Google (por ejemplo, al llamar a la API de archivos de Drive ).

Puede probar todas las API de Google y ver sus alcances en OAuth 2.0 Playground .

Ejemplos HTTP GET

Una llamada al extremo de drive.files (la API de Drive Files) mediante el encabezado HTTP Authorization: Bearer podría tener el siguiente aspecto. Tenga en cuenta que debe especificar su propio token de acceso:

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

Aquí hay una llamada a la misma API para el usuario autenticado usando el parámetro de cadena de consulta access_token :

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

ejemplos curl

Puede probar estos comandos con la aplicación de línea de comandos curl . Aquí hay un ejemplo que usa la opción de encabezado HTTP (preferido):

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

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

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

Actualizar un token de acceso

Los tokens de acceso caducan periódicamente y se convierten en credenciales no válidas para una solicitud de API relacionada. Puede actualizar un token de acceso sin solicitar permiso al usuario (incluso cuando el usuario no está presente) si solicitó acceso sin conexión a los ámbitos asociados con el token.

Para actualizar un token de acceso, su 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:

Campos
client_id El ID de cliente obtenido de API Console.
client_secret El secreto del cliente obtenido del API Console.
grant_type Tal como se define en la especificación OAuth 2.0 , el valor de este campo debe establecerse en refresh_token .
refresh_token El token de actualización devuelto del intercambio de código de autorización.

El siguiente fragmento 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 nuevo token de acceso. El siguiente fragmento muestra una respuesta de muestra:

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

Tenga 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. Debe guardar tokens de actualización en el almacenamiento a largo plazo y continuar usándolos mientras sigan siendo válidos. Si su 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 un token

En algunos casos, un usuario puede desear revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso visitando Configuración de la cuenta . Consulte la sección Eliminar el acceso a sitios o aplicaciones del documento de soporte Sitios y aplicaciones de terceros con acceso a su cuenta para obtener más información.

También es posible que una aplicación revoque mediante programación el acceso que se le ha otorgado. La revocación programática es importante en los casos en que un usuario cancela su suscripción, elimina una aplicación o los recursos de API requeridos por una aplicación han cambiado significativamente. En otras palabras, parte del proceso de eliminación puede incluir una solicitud de API para garantizar que se eliminen los permisos otorgados previamente a la aplicación.

Para revocar un token mediante programación, su 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 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, el token de actualización también se revocará.

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

Ámbitos permitidos

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

OpenID Connect , inicio de sesión de Google

  • email
  • openid
  • profile

API de unidad

  • 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