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 elclient_secret
en la aplicaciónEs necesario registrar la aplicación con Google e insertar el
client ID
y elclient 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 enhttps://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 laverification_url
al usuario. Debe guardar los valores dedevice_code
,expires_in
einterval
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 dePOST
ahttps://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 aparteEl 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 eluser_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:
- 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.
- Sigue el vínculo para la página de configuración de Seguridad.
- 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 es400
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.
- Biblioteca cliente de API de Google para Java
- Biblioteca cliente de API de Google para JavaScript
- Biblioteca cliente de API de Google para Python
- Biblioteca cliente de API de Google para .NET
- Biblioteca cliente de API de Google para Ruby
- Biblioteca cliente de API de Google para PHP
- Biblioteca de OAuth 2.0 para Google Web Toolkit
- Controladores de OAuth 2.0 para Google Toolbox para Mac
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.