OAuth 2.0 Flow: Devices

Este flujo de OAuth 2.0 está diseñado para aplicaciones que se ejecutan en dispositivos con capacidades de entrada limitadas, como consolas de juegos o cámaras de video. En este flujo, el usuario interactúa con una aplicación en el dispositivo para obtener una URL y un código de dispositivo. Posteriormente, el usuario cambia a otro dispositivo con mayores capacidades de entrada, como una computadora o un teléfono inteligente, para autorizar el código de dispositivo.

Important: You need to obtain authorization credentials in the Google API Console to be able to use OAuth 2.0 authorization.

This document contains the following sections:

The Obtaining OAuth 2.0 access tokens section explains how to obtain OAuth 2.0 access tokens for devices. The Google Accounts Authentication and Authorization documentation also provides complete details for implementing OAuth 2.0 in different types of applications.
The Making an authorized API request section explains how to use the OAuth 2.0 tokens that your application obtains to make authorized API requests on a user's behalf.
The Client libraries section describes client library support for OAuth 2.0.

Obtaining OAuth 2.0 access tokens

Este flujo tiene los siguientes pasos:

Insertar el client_id y el client_secret en la aplicación

Es necesario registrar la aplicación con Google e insertar el client ID y el client secret creados durante el proceso de registro en la aplicación. Ambos valores se muestran en la Google APIs console.

Solicitar un código de dispositivo

El dispositivo envía una solicitud de POST al servidor de autorización de Google en https://accounts.google.com/o/oauth2/device/code. La solicitud especifica los siguientes parámetros:

Parámetros
`client_id`	Obligatorio. El ID de cliente de OAuth 2.0 para la aplicación.
`scope`	Obligatorio. Una lista delimitada por espacios de los alcances que identifican los recursos a los que la aplicación podría acceder en nombre del usuario.

La solicitud de ejemplo siguiente muestra cómo recuperar un código de dispositivo:

POST /o/oauth2/device/code HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
scope=https://www.googleapis.com/auth/youtube

Manejar la respuesta de Google

Google responde a tu solicitud mostrando un objeto JSON para tu dispositivo. A continuación se muestra una respuesta de ejemplo:
```
{
  "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
  "user_code" : "a9xfwk9c",
  "verification_url" : "http://www.google.com/device",
  "expires_in" : "1800"
  "interval" : 5,
}
```
La aplicación en el dispositivo debe mostrar el user_code y la verification_url al usuario. Debe guardar los valores de device_code, expires_in e interval para utilizarlos en el paso 4.

Comenzar el sondeo del servidor de autorización de Google

La aplicación puede comenzar a sondear el servidor de autorización de Google utilizando el device_code que se mostró en la respuesta JSON en el paso 3. Para ello, la aplicación envía una solicitud de POST a https://accounts.google.com/o/oauth2/token que especifica los siguientes pares clave-valor:

Claves
`client_id`	El ID de cliente de OAuth 2.0 para la aplicación.
`client_secret`	El secreto de cliente asociado con el ID de cliente. Este valor se muestra en la Google APIs console.
`code`	El código de dispositivo obtenido en el paso 3.
`grant_type`	Establece este valor en `http://oauth.net/grant_type/device/1.0`.

A continuación se muestra un ejemplo de una solicitud de sondeo. El interval que se mostró en la respuesta JSON en el paso 3 especifica la cantidad mínima de tiempo, en segundos, que la aplicación debe esperar entre solicitudes de sondeo.

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

client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
grant_type=http://oauth.net/grant_type/device/1.0

Hasta que el usuario complete los pasos 5 a 7, la aplicación recibe una de las siguientes respuestas a cada solicitud de sondeo:

La siguiente respuesta indica que el usuario no ha completado los pasos para conceder el acceso a la API al dispositivo:
```
{
  "error" : "authorization_pending"
}
```
La siguiente respuesta indica que la aplicación está enviando solicitudes de sondeo con demasiada frecuencia:
```
{
  "error" : "slow_down"
}
```

El usuario ingresa el user_code en un navegador aparte

El usuario ejecuta un navegador en otro dispositivo, como una computadora o un teléfono celular, y navega a la verification_url. Esa URL muestra una página donde el usuario puede ingresar el user_code obtenido en el paso 3.

Nota: El user_code distingue entre mayúsculas y minúsculas, por lo que el usuario debe ingresarlo exactamente como aparece en la respuesta.
El usuario accede a la cuenta de Google

Tras ingresar el user_code, se le pide al usuario que acceda a la cuenta de Google que se utilizará para autorizar las solicitudes de YouTube Data API del dispositivo. (Los usuarios que ya hayan accedido procederán directamente al paso siguiente.)
Decisión de consentimiento del usuario

Después de que el usuario acceda, el servidor de autorización de Google muestra una página con el nombre de la aplicación y los servicios de Google a los cuales solicita permiso para acceder en nombre del usuario. El usuario puede conceder o denegar el acceso a la aplicación.
Proceso de respuesta desde el servidor de sondeo para obtener tokens

Si el usuario concede el acceso a la aplicación, la siguiente solicitud de sondeo que el dispositivo envíe mostrará un objeto JSON que contiene un token de acceso y un token de actualización.
```
{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer",
  "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
}
```
Importante: La aplicación debe almacenar ambos valores.
- La sección Invocación de YouTube Data API explica cómo enviar una solicitud autorizada mediante el token de acceso.
- La sección Actualización de un token de acceso explica cómo utilizar el token de actualización para obtener un nuevo token de acceso si el anterior ha expirado.

Invocación de YouTube Data API

Tras obtener un token de acceso para un usuario, la aplicación puede utilizar ese token para enviar solicitudes autorizadas de API en nombre de ese usuario. La API permite especificar un token de acceso de dos maneras:

Especifique el token de acceso como el valor del encabezado de solicitud HTTP de Authorization: Bearer. Este es el método recomendado.

GET /youtube/v3/channels?part=id&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer ACCESS_TOKEN
...

Para probar este método, puedes usar cURL con el siguiente comando:

curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true

Especifica el token de acceso como el valor del parámetro de consulta de access_token:

https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

Para probar este método, puedes usar cURL con el siguiente comando:

curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

La API muestra un código de respuesta HTTP 401 (Unauthorized) si envías una solicitud para acceder a un recurso protegido con un token de acceso caduco, falso, de alcance incorrecto o no válido por cualquier otra razón.

Si la API muestra un código de respuesta HTTP 403, la aplicación no se puede registrar. Muchas API establecen un límite de consultas-volumen de 0 para aplicaciones no registradas y muestran un código de respuesta 403 cuando se excede este límite.

La siguiente sección explica cómo actualizar un token de acceso.

Actualización de un token de acceso

Los tokens de acceso caducan periódicamente. Cuando esto sucede, es necesario actualizarlos. La aplicación puede usar un token de actualización para obtener un nuevo token de acceso válido cuando el anterior haya caducado o en cualquier otro momento. Las aplicaciones web del servidor, las aplicaciones instaladas y los dispositivos obtienen tokens de actualización durante el proceso de autorización.

Para actualizar un token de acceso, la aplicación envía una solicitud de POST al servidor de autorización de Google que especifica el ID de cliente, el secreto de cliente y el token de actualización para el usuario. Además, la solicitud establece el valor del parámetro grant_type en refresh_token. A continuación se muestra un ejemplo de solicitud:

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

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

El servidor de autorización muestra un objeto JSON que contiene un nuevo token de acceso:

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "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 combinación cliente-usuario y otro por usuario a través de todos los clientes. Guarda los tokens de actualización en un almacenamiento a largo plazo y sigue usándolos mientras sean válidos. Si la aplicación solicita demasiados tokens de actualización, podría llegar a estos límites, en cuyo caso los tokens de actualización antiguos dejarán de funcionar.

Revocación de un token

Existen dos formas para revocar un token de acceso:

Un usuario puede revocar el acceso dado a una solicitud a través de la siguiente URL y revocar explícitamente el acceso:
```
https://accounts.google.com/b/0/IssuedAuthSubTokens
```
Los siguientes pasos explican cómo llegar a esta página:
1. Haz clic en la imagen del usuario en la barra de Google y en el vínculo Cuenta, o bien, desplázate de alguna otra forma a la página Vista general de la cuenta de la cuenta de Google del usuario.
2. Sigue el vínculo para la página de configuración de Seguridad.
3. Haz clic en el botón para administrar el acceso a las aplicaciones y sitios web conectados que pueden acceder y utilizar los detalles de la cuenta de Google del usuario.
Una aplicación puede revocar su propio acceso de manera programática. Este tipo de revocación es importante en los casos en que un usuario cancela la suscripción o elimina una aplicación, en la que una solicitud de la API para eliminar los permisos concedidos a la aplicación debe ser parte del proceso de eliminación.

Para revocar un token de manera programática, la aplicación envía una solicitud a https://accounts.google.com/o/oauth2/revoke e incluye el token como parámetro:
```
curl https://accounts.google.com/o/oauth2/revoke?token={token}
```
El token especificado puede ser un token de acceso o de actualización. Si se trata de un token de acceso y tiene un token de actualización correspondiente, este último también se revoca.

Si la revocación se realiza correctamente, el código de estado de la respuesta es 200. Si se produce un error, el código de estado de respuesta es 400 y la respuesta también contiene un código de error.

Bibliotecas cliente

Nota: Si pretendes proporcionar una característica de acceso con Google, te recomendamos que utilices Google+ Sign-in, que ofrece el mecanismo de autenticación OAuth 2.0 junto con un acceso adicional a las características sociales de Google+.

Puedes usar las bibliotecas cliente a continuación para implementar OAuth 2.0 en tu aplicación. Recomendamos usar una biblioteca de cliente en lugar de escribir tu propio código. El uso de estas bibliotecas de cliente estándar es importante para la seguridad y la seguridad de los usuarios y tu aplicación.

También puedes seguir las instrucciones en la sección Invocación de YouTube Data API para modificar el código y así configurar correctamente los valores de token de OAuth 2.0.