OAuth 2.0 para apps de escritorio y dispositivos móviles

En este documento, se explica cómo las aplicaciones instaladas en dispositivos como teléfonos, tablets y computadoras usan los extremos de OAuth 2.0 de Google para autorizar el acceso a la API de YouTube Data.

OAuth 2.0 permite que los usuarios compartan datos específicos con una aplicación y, al mismo tiempo, mantengan la privacidad de sus nombres de usuario, contraseñas y otra información. Por ejemplo, una aplicación puede usar OAuth 2.0 para obtener permiso para subir videos al canal de YouTube de un usuario.

Las apps instaladas se distribuyen a dispositivos individuales, y se supone que estas apps no pueden mantener secretos. Pueden acceder a las APIs de Google mientras el usuario está en la app o cuando esta se ejecuta en segundo plano.

Este flujo de autorización es similar al que se usa para las aplicaciones de servidor web. La principal diferencia es que las apps instaladas deben abrir el navegador del sistema y proporcionar un URI de redireccionamiento local para controlar las respuestas del servidor de autorización de Google.

Bibliotecas y muestras

En el caso de las aplicaciones para dispositivos móviles, recomendamos usar la versión más reciente de la biblioteca nativa de Google Identity Services para Android y la biblioteca nativa de Acceso con Google para iOS. Estas bibliotecas controlan la autorización del usuario y son más fáciles de implementar que el protocolo de nivel inferior que se describe aquí.

En el caso de las apps que se ejecutan en dispositivos que no admiten un navegador del sistema o que tienen capacidades de entrada limitadas, como TVs, consolas de juegos, cámaras o impresoras, consulta OAuth 2.0 para TVs y dispositivos o Acceso en TVs y dispositivos de entrada limitada.

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitarlas en API Console.

Para habilitar una API en tu proyecto, sigue estos pasos:

1. Open the API Library en el Google API Console.
2. If prompted, select a project, or create a new one.
3. Usa la página Biblioteca para buscar y habilitar la API de YouTube Data. Busca otras APIs que usará tu aplicación y habilítalas también.

Crea credenciales de autorización

Todas las aplicaciones que usan OAuth 2.0 para acceder a las APIs de Google deben tener credenciales de autorización que identifiquen la aplicación en el servidor OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Luego, tus aplicaciones podrán usar las credenciales para acceder a las APIs que habilitaste para ese proyecto.

1. Go to the Credentials page.
2. Haz clic en Crear cliente.
3. En las siguientes secciones, se describen los tipos de clientes que admite el servidor de autorización de Google. Elige el tipo de cliente recomendado para tu aplicación, asígnale un nombre a tu cliente OAuth y configura los demás campos del formulario según corresponda.

Identifica los permisos de acceso

Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, puede haber una relación inversa entre la cantidad de permisos solicitados y la probabilidad de obtener el consentimiento del usuario.

Antes de que comiences a implementar la autorización de OAuth 2.0, te recomendamos identificar los permisos a los que tu app necesitará acceder.

La versión 3 de la API de YouTube Data usa los siguientes alcances:

El documento Permisos de la API de OAuth 2.0 contiene una lista completa de los permisos que puedes usar para acceder a las APIs de Google.

Cómo obtener tokens de acceso de OAuth 2.0

En los siguientes pasos, se muestra cómo tu aplicación interactúa con el servidor de OAuth 2.0 de Google para obtener el consentimiento de un usuario para realizar una solicitud a la API en su nombre. Tu aplicación debe tener ese consentimiento antes de poder ejecutar una solicitud de la API de Google que requiera autorización del usuario.

Paso 1: Genera un verificador y un desafío de código

Google admite el protocolo de clave de prueba para el intercambio de código (PKCE) para que el flujo de la app instalada sea más seguro. Se crea un verificador de código único para cada solicitud de autorización, y su valor transformado, llamado "code_challenge", se envía al servidor de autorización para obtener el código de autorización.

Crea el verificador de código

Un code_verifier es una cadena aleatoria criptográfica de alta entropía que usa los caracteres no reservados [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", con una longitud mínima de 43 caracteres y una longitud máxima de 128 caracteres.

El verificador de código debe tener suficiente entropía para que sea poco práctico adivinar el valor.

Crea el desafío de código

Se admiten dos métodos para crear el desafío de código.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Paso 2: Envía una solicitud al servidor de OAuth 2.0 de Google

Para obtener la autorización del usuario, envía una solicitud al servidor de autorización de Google en https://accounts.google.com/o/oauth2/v2/auth. Este extremo controla la búsqueda de sesiones activas, autentica al usuario y obtiene su consentimiento. Solo se puede acceder al extremo a través de SSL y rechaza las conexiones HTTP (sin SSL).

El servidor de autorización admite los siguientes parámetros de cadena de consulta para las aplicaciones instaladas:

URLs de autorización de muestra

En las siguientes pestañas, se muestran URLs de autorización de ejemplo para las diferentes opciones de URI de redireccionamiento.

Las URLs son idénticas, excepto por el valor del parámetro redirect_uri. Las URLs también contienen los parámetros obligatorios response_type y client_id, así como el parámetro opcional state. Cada URL contiene saltos de línea y espacios para facilitar la lectura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Paso 3: Google le solicita al usuario su consentimiento

En este paso, el usuario decide si otorga a tu aplicación el acceso solicitado. En esta etapa, Google muestra una ventana de consentimiento que incluye el nombre de tu aplicación y los servicios de la API de Google a los que solicita permiso para acceder con las credenciales de autorización del usuario, así como un resumen de los permisos de acceso que se otorgarán. Luego, el usuario puede dar su consentimiento para otorgar acceso a uno o más permisos solicitados por tu aplicación, o bien rechazar la solicitud.

Tu aplicación no necesita hacer nada en esta etapa, ya que espera la respuesta del servidor OAuth 2.0 de Google que indica si se otorgó acceso. Esa respuesta se explica en el siguiente paso.

Paso 4: Controla la respuesta del servidor de OAuth 2.0

La forma en que tu aplicación recibe la respuesta de autorización depende del esquema de URI de redireccionamiento que usa. Independientemente del esquema, la respuesta contendrá un código de autorización (code) o un error (error). Por ejemplo, error=access_denied indica que el usuario rechazó la solicitud.

Si el usuario otorga acceso a tu aplicación, puedes intercambiar el código de autorización por un token de acceso y un token de actualización, como se describe en el siguiente paso.

Paso 5: Intercambia el código de autorización por tokens de actualización y acceso

Para intercambiar un código de autorización por un token de acceso, llama al extremo https://oauth2.googleapis.com/token y configura los siguientes parámetros:

En el siguiente fragmento, se muestra una solicitud de ejemplo:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google responde a esta solicitud devolviendo un objeto JSON que contiene un token de acceso de corta duración y un token de actualización.

La respuesta contiene los siguientes campos:

En el siguiente fragmento, se muestra una respuesta de ejemplo:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Paso 6: Verifica a qué permisos otorgaron los usuarios acceso

Cuando solicitas varios permisos (alcances), es posible que los usuarios no le otorguen acceso a tu app a todos ellos. Tu app debe verificar qué alcances se otorgaron realmente y controlar de forma adecuada las situaciones en las que se deniegan algunos permisos, por lo general, inhabilitando las funciones que dependen de esos alcances denegados.

Sin embargo, hay algunas excepciones. Las apps de Google Workspace Enterprise con delegación de autoridad de todo el dominio o las apps marcadas como Confiables omiten la pantalla de consentimiento de permisos detallados. En el caso de estas apps, los usuarios no verán la pantalla de consentimiento de permisos detallados. En cambio, tu app recibirá todos los alcances solicitados o ninguno.

Para obtener información más detallada, consulta Cómo controlar los permisos detallados.

Para verificar si el usuario otorgó acceso a tu aplicación a un alcance en particular, examina el campo scope en la respuesta del token de acceso. Son los permisos de acceso que otorga el access_token, expresados como una lista de cadenas sensibles a mayúsculas y minúsculas delimitadas por espacios.

Por ejemplo, la siguiente respuesta de muestra del token de acceso indica que el usuario otorgó permiso a tu aplicación para ver, editar y borrar de forma permanente los videos, las calificaciones, los comentarios y los subtítulos de YouTube del usuario:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Llama a las APIs de Google

Después de que tu aplicación obtiene un token de acceso, puedes usarlo para realizar llamadas a una API de Google en nombre de una cuenta de usuario determinada si se otorgaron los permisos de acceso requeridos por la API. Para ello, incluye el token de acceso en una solicitud a la API con un parámetro de consulta access_token o un valor Bearer del encabezado HTTP Authorization. Cuando sea posible, se recomienda usar el encabezado HTTP, ya que las cadenas de consulta suelen ser visibles en los registros del servidor. En la mayoría de los casos, puedes usar una biblioteca cliente para configurar tus llamadas a las APIs de Google (por ejemplo, cuando llamas a la API de YouTube Data).

Ten en cuenta que la API de YouTube Data solo admite cuentas de servicio para los propietarios de contenido de YouTube que poseen y administran varios canales de YouTube, como sellos discográficos y estudios cinematográficos.

Puedes probar todas las APIs de Google y ver sus permisos en OAuth 2.0 Playground.

Ejemplos de HTTP GET

Una llamada al extremo youtube.channels (la API de YouTube Data) con el encabezado HTTP Authorization: Bearer podría verse de la siguiente manera. Ten en cuenta que debes especificar tu propio token de acceso:

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

Esta es una llamada a la misma API para el usuario autenticado con el parámetro de cadena de consulta access_token:

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

Ejemplos de curl

Puedes probar estos comandos con la aplicación de línea de comandos de curl. A continuación, se muestra un ejemplo que usa la opción de encabezado HTTP (preferida):

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

O, de forma alternativa, la opción del parámetro de cadena de consulta:

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

Actualización de un token de acceso

Los tokens de acceso vencen periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Puedes actualizar un token de acceso sin solicitarle permiso al usuario (incluso cuando el usuario no está presente) si solicitaste acceso sin conexión a los alcances asociados con el token.

Para actualizar un token de acceso, tu aplicación envía una solicitud POST HTTPS al servidor de autorización de Google (https://oauth2.googleapis.com/token) que incluye los siguientes parámetros:

En el siguiente fragmento, se muestra una solicitud de ejemplo:

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 devolverá un objeto JSON que contiene un nuevo token de acceso. En el siguiente fragmento, se muestra una respuesta de ejemplo:

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

Ten 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 y usuario, y otro por usuario en todos los clientes. Debes guardar los tokens de actualización en un almacenamiento a largo plazo y seguir usándolos mientras sigan siendo válidos. Si tu 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.

Cómo revocar un token

En algunos casos, es posible que un usuario desee revocar el acceso otorgado a una aplicación. Para revocar el acceso, el usuario debe visitar la configuración de la cuenta. Consulta la sección para quitar el acceso de sitios o apps del documento de asistencia Sitios y apps de terceros con acceso a tu cuenta para obtener más información.

También es posible que una aplicación revoque de forma programática el acceso que se le otorgó. La revocación programática es importante en los casos en que un usuario cancela su suscripción, quita una aplicación o los recursos de la API que requiere una app cambiaron significativamente. En otras palabras, parte del proceso de eliminación puede incluir una solicitud a la API para garantizar que se quiten los permisos que se otorgaron anteriormente a la aplicación.

Para revocar un token de forma programática, tu aplicación realiza una solicitud a https://oauth2.googleapis.com/revoke y, luego, 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 será 200. En caso de error, se muestra un código de estado HTTP 400 junto con un código de error.

Métodos de redireccionamiento de apps

Protege tus apps

Acceso basado en el tiempo

El acceso basado en el tiempo permite que un usuario le otorgue a tu app acceso a sus datos durante un período limitado para completar una acción. El acceso basado en el tiempo está disponible en algunos productos de Google durante el flujo de consentimiento, lo que les brinda a los usuarios la opción de otorgar acceso por un período limitado. Un ejemplo es la API de Data Portability, que permite una transferencia única de datos.

Cuando un usuario otorga a tu aplicación acceso basado en el tiempo, el token de actualización vencerá después de la duración especificada. Ten en cuenta que los tokens de actualización pueden invalidarse antes en circunstancias específicas. Consulta estos casos para obtener más detalles. En estos casos, el campo refresh_token_expires_in que se devuelve en la respuesta del intercambio de código de autorización representa el tiempo restante hasta que venza el token de actualización.

Lecturas adicionales

La práctica recomendada actual del IETF OAuth 2.0 para aplicaciones nativas establece muchas de las prácticas recomendadas que se documentan aquí.