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 mientras mantienen 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 está ejecutando 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 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).

Prerrequisitos

Habilite las API para su proyecto

Cualquier aplicación que llame a las API de Google debe habilitar esas API en el 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, utilice la función de 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 haya 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 de televisores y dispositivos de entrada limitada .
  4. Nombre 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 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 ver las aplicaciones o los dispositivos instalados.

Obtención de tokens de acceso de OAuth 2.0

Aunque su aplicación se ejecuta en un dispositivo con capacidades de entrada limitadas, los usuarios deben tener acceso por separado 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 ha autorizado su aplicación.
  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 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 comandos curl . Estos ejemplos deberían ser fáciles de migrar a varios idiomas y tiempos de ejecución.

Paso 1: Solicite 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 quiere acceder en el en nombre de. Debe recuperar esta URL del documento de descubrimiento utilizando el valor de metadatos device_authorization_endpoint . Incluya los siguientes parámetros de solicitud HTTP:

Parámetros
client_id Requerido

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

scope Requerido

Una lista de ámbitos delimitada por espacios que identifica 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 ver las aplicaciones o los 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 tanto, existe una relación inversa entre el número de alcances solicitados y la probabilidad de obtener el consentimiento del usuario.

Ejemplos de

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 autorización

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 contiene 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 capacidades de entrada más ricas. Por ejemplo, un usuario puede usar una computadora portátil o un teléfono móvil para autorizar la ejecución de una aplicación en un televisor. En este caso, 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 tiempo, el usuario no completa el flujo de autorización y su dispositivo tampoco realiza una encuesta 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 solicitudes de sondeo. Por ejemplo, si el valor es 5 , su dispositivo debe 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 alcances 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 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
}

Cuota excedida respuesta

Si las solicitudes de código de su dispositivo han superado 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 retirada para reducir la tasa de solicitudes.

Paso 3: muestra el código de usuario

Muestre al user_code verification_url y el user_code obtenidos en el paso 2. 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 a la verification_url en un dispositivo separado e ingrese el user_code .

Diseñe su interfaz de usuario (UI) con las siguientes reglas en mente:

  • user_code
    • El user_code debe mostrarse en un campo que pueda manejar 15 caracteres de tamaño 'W'. En otras palabras, si se puede visualizar el código WWWWWWWWWWWWWWW correctamente, su interfaz de usuario es válida, y se recomienda usar ese valor de cadena cuando se prueba la forma en que los user_code muestra en su interfaz de usuario.
    • El user_code 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 donde se muestra la verification_url debe ser lo suficientemente ancho para manejar 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 motivos de visualización, asegúrese de que su aplicación pueda manejar las variantes http y https .

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

Dado que el usuario utilizará un dispositivo separado para navegar a la verification_url y conceder (o denegar) el acceso, el dispositivo solicitante no recibe una notificación automática cuando el usuario responde 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 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 el device_code y el user_code obtenidos en el paso 2 hayan expirado. 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 de su aplicación. Puede encontrar este valor en el API Console Credentials page.
client_secret El secreto del cliente para el client_id proporcionado. Puede encontrar este valor en el API Console Credentials page.
device_code 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 de

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 mostró en el paso 3 :

Conecte un dispositivo ingresando un código

Después de ingresar el user_code 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 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 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 envía su aplicación 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 revoca el acceso. Tenga en cuenta que los tokens de actualización siempre se devuelven para los dispositivos.
scope Los alcances de acceso otorgados por el access_token expresados ​​como una lista de cadenas que access_token mayúsculas y minúsculas y delimitadas por espacios.
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 período de tiempo prolongado, 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 ha completado 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 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 faltan los parámetros necesarios o si 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 ). Estos errores incluyen:

Error Código de estado HTTP Descripción
invalid_client 401 No se encontró el cliente 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 de 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

Una vez que su aplicación obtiene un token de acceso, puede usar 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 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 utilizar 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 de HTTP GET

Una llamada al drive.files final drive.files (la API de archivos de Drive) utilizando el encabezado HTTP Authorization: Bearer puede 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 de 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 expiran periódicamente y se convierten en credenciales no válidas para una solicitud de API relacionada. Puede actualizar un token de acceso sin pedir 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 POST 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 del API Console.
client_secret El secreto de cliente obtenido del API Console.
grant_type 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 por el intercambio de códigos 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 existen 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 los tokens de actualización en un almacenamiento a largo plazo y continuar usándolos mientras sigan siendo válidos. Si su aplicación solicita demasiados tokens de actualización, puede encontrarse con estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.

Revocar una ficha

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 de Sitios y aplicaciones de terceros con acceso al documento de soporte de 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, 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 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 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