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 privados 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 usted está escribiendo una aplicación para una plataforma como Android, iOS, MacOS, Linux o Windows (incluyendo Windows universal Plataforma), que tiene acceso al navegador y capacidades de entrada completos, utilizar 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).

Prerrequisitos

Habilite las API para su proyecto

Cualquier aplicación que llama a las API de Google necesita para que estas APIs en la 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 listas de todas las APIs disponibles, agrupados por familias de productos y popularidad. Si la API desea activar no es visible en la lista, el uso de búsqueda para encontrarlo, o haga clic en Ver todos en la familia de productos al que pertenece.
  4. Seleccione la API que desea activar, a continuación, haga clic en el botón de activación.
  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 utilice 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> OAuth ID de cliente.
  3. Seleccione el tipo de aplicación Dispositivos de entrada televisores y Limited.
  4. El nombre de su cliente de 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.

Ver la alcances mascotas lista de aplicaciones o 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 gama de capacidades y entornos de ejecución que los dispositivos pueden tener, los ejemplos mostrados en este documento utilizan el curl utilidad de línea de comandos. 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, el dispositivo envía una solicitud HTTP POST al servidor de autorización de Google, por lo https://oauth2.googleapis.com/device/code , que identifica a su aplicación, así como el acceso alcances que su aplicación desea tener acceso en la década de los usuarios en nombre de. Usted debe recuperar esta URL en el documento de descubrimiento mediante el device_authorization_endpoint valor de metadatos. 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 el API ConsoleCredentials 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. Ver la alcances mascotas lista de 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 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 curl comando para enviar la misma petición:

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, 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 La cantidad de tiempo, en segundos, que el device_code y user_code son válidos. Si, en ese tiempo, 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 solicitudes de sondeo. Por ejemplo, si el valor es 5 , el dispositivo debería enviar una solicitud de sondeo al servidor de autorización de Google cada cinco segundos. Vea el paso 3 para 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 que el usuario debe navegar a, en un dispositivo separado, para entrar en el user_code y conceder o denegar el acceso a la 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 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 retirada para reducir la tasa de solicitudes.

Paso 3: muestra el código de usuario

Visualizar el verification_url y user_code obtenido en la etapa 2 para el usuario. Ambos valores pueden contener cualquier carácter imprimible del juego de caracteres US-ASCII. El contenido que se visualiza para el usuario debe instruir al usuario navegar a la verification_url en un dispositivo independiente y entrar en el user_code .

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

  • user_code
    • El user_code se debe mostrar en un campo que puede 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 mayúsculas y minúsculas y no debe ser modificado de ninguna manera, como cambiar el caso o la inserción de otros caracteres de formato.
  • verification_url
    • El espacio donde se muestra el verification_url debe ser lo suficientemente amplia para manejar una cadena de URL que es de 40 caracteres.
    • No se debe modificar el verification_url de ninguna manera, excepto para eliminar opcionalmente el esquema para su visualización. Si lo hace plan para quitarse el esquema (por ejemplo, https:// ) de la URL, por razones de visualización, puede asegurarse de que su aplicación puede manejar tanto http y https variantes.

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

Dado que el usuario va a utilizar un dispositivo separado para navegar a la verification_url y concesión (o negar) el acceso, el dispositivo que solicita no es notificado automáticamente 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 ha respondido el usuario a la solicitud.

El dispositivo que solicita debe continuar enviando solicitudes de sondeo hasta que recibe una respuesta que indica que el usuario ha respondido a la solicitud de acceso o hasta que el device_code y user_code obtenido en el paso 2 han expirado. El interval devuelto en el paso 2 especifica la cantidad de tiempo, en segundos, para esperar entre solicitudes.

La dirección URL del punto final de la encuesta 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 ConsoleCredentials page.
client_secret El secreto para el cliente proporcionado client_id . Puede encontrar este valor en el API ConsoleCredentials page.
device_code El device_code devuelto por el servidor de autorización en el paso 2 .
grant_type Establecer 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 curl comando para enviar la misma petición:

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

A continuación se muestra una imagen de la página similar a lo que ven los usuarios cuando navegan a la verification_url que se visualizó en el paso 3 :

Conecte un dispositivo ingresando un código

Después de introducir el user_code y, si no se ha iniciado la sesión en, iniciar sesión en Google, el usuario ve una pantalla de consentimiento como el 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 concede el acceso al dispositivo (haciendo clic en Allow en la pantalla de consentimiento), entonces la respuesta contiene un token de acceso y una actualización de fichas. Las fichas permiten que su dispositivo acceder a las API de Google en nombre del usuario. (El scope propiedad en los determina la respuesta que Apis el acceso al dispositivo lata.)

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

Los 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 concedidos por el access_token expresada como una lista de cadenas delimitados por espacios, 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 la aplicación necesita acceso a una API durante un largo período de tiempo, se puede utilizar la actualización de token para obtener un nuevo token de acceso. Si su aplicación necesita este tipo de acceso, entonces debe almacenar el token de actualización para su uso posterior.

Acceso denegado

Si el usuario se niega a permitir el acceso al dispositivo, a continuación, la respuesta del servidor tiene un 403 código de estado de respuesta HTTP ( 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 428 código de estado de respuesta HTTP ( 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 403 código de estado de respuesta HTTP ( 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 400 ( Bad Request ) o 401 ( Unauthorized ) código de estado HTTP de respuesta. Estos errores incluyen:

Error Código de estado HTTP Descripción
invalid_client 401 No se encontró el cliente OAuth. Por ejemplo, este error se produce si la client_id valor del parámetro no es válido.
invalid_grant 400 El code valor de parámetro no es válido.
unsupported_grant_type 400 El grant_type valor del parámetro 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 ello, incluya el acceso de ficha en una solicitud a la API mediante la inclusión de un bien access_token parámetro de consulta o un Authorization cabecera HTTP Bearer valor. Cuando es 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 se puede utilizar una biblioteca de cliente para configurar sus llamadas a las API de Google (por ejemplo, al llamar a la API de archivos de la unidad ).

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

Ejemplos de HTTP GET

Una llamada a la drive.files punto final (la API de archivos de la unidad) utilizando la Authorization: Bearer cabecera HTTP podría parecerse a lo siguiente. 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í es una llamada a la misma API para el usuario autenticado mediante el access_token parámetro de cadena de consulta:

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

curl ejemplos

Puede probar estos comandos con el curl la aplicación de línea de comandos. 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 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, la aplicación envía un HTTPS POST petición al servidor de autorización de Google ( https://oauth2.googleapis.com/token ) que incluye los siguientes parámetros:

Los campos
client_id El ID de cliente obtiene de la API Console.
client_secret El secreto del cliente obtenida de la API Console.
grant_type Como se define en la especificación OAuth 2.0 , el valor de este campo se debe establecer 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 al visitar Configuración de la cuenta . Vea la sección de acceso Retire el sitio o aplicación de los Sitios y aplicaciones de terceros con acceso a su cuenta documento de soporte para 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 mediante programación una ficha, la aplicación realiza una solicitud al 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, entonces el código de estado HTTP de la respuesta es 200 . Para las condiciones de error, un código de estado HTTP 400 es devuelto 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 Conectar , iniciar sesión en 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