Las APIs de Google usan el protocolo OAuth 2.0 para la autenticación y la autorización. Google admite situaciones comunes de OAuth 2.0, como las de aplicaciones de servidor web, del cliente, instaladas y de dispositivos de entrada limitada.
Para comenzar, obtén las credenciales de cliente de OAuth 2.0 de la Consola de APIs de Google. Luego, tu aplicación cliente solicita un token de acceso al servidor de autorización de Google, extrae un token de la respuesta y lo envía a la API de Google a la que deseas acceder. Para obtener una demostración interactiva del uso de OAuth 2.0 con Google (incluida la opción de usar tus propias credenciales de cliente), experimenta con OAuth 2.0 Playground.
En esta página, se proporciona una descripción general de las situaciones de autorización de OAuth 2.0 que admite Google y se incluyen vínculos a contenido más detallado. Para obtener detalles sobre el uso de OAuth 2.0 para la autenticación, consulta OpenID Connect.
Pasos básicos
Todas las aplicaciones siguen un patrón básico cuando acceden a una API de Google con OAuth 2.0. En un nivel alto, debes seguir cinco pasos:
1. Obtén credenciales de OAuth 2.0 en la Consola de APIs de Google.
Visita la Consola de APIs de Google para obtener credenciales de OAuth 2.0, como un ID de cliente y un secreto del cliente que conozcan tanto Google como tu aplicación. El conjunto de valores varía según el tipo de aplicación que estés compilando. Por ejemplo, una aplicación de JavaScript no requiere un secreto, pero una aplicación de servidor web sí.
Debes crear un cliente de OAuth adecuado para la plataforma en la que se ejecutará tu app, por ejemplo:
- En el caso de las apps para Android, usa el tipo de aplicación Android.
-
En el caso de las apps para iOS, usa
el tipo de aplicación iOS.
- desktop_windows Para las apps para computadoras (como las aplicaciones de Windows, macOS o Linux, o las herramientas de CLI), usa el tipo de aplicación App para computadoras.
- code Para las apps web de JavaScript o del servidor, usa el tipo de aplicación Aplicación web. No uses este tipo de aplicación para ninguna otra, como las apps nativas o para dispositivos móviles.
- chrome_extension Para las extensiones de Chrome, usa el tipo de aplicación Extensión de Chrome.
- tv En el caso de los dispositivos de entrada limitada, como TVs o dispositivos incorporados, usa el tipo de aplicación TVs y dispositivos de entrada limitada.
- host Para las interacciones servidor a servidor, usa cuentas de servicio. No se requiere un ID de cliente de OAuth.
2. Obtén un token de acceso del servidor de autorización de Google.
Antes de que tu aplicación pueda acceder a datos privados con una API de Google, debe obtener un
token de acceso que otorgue acceso a esa API. Un solo token de acceso puede otorgar distintos grados
de acceso a varias APIs. Un parámetro de variable llamado scope controla el conjunto
de recursos y operaciones que permite un token de acceso. Durante la solicitud del token de acceso,
tu aplicación envía uno o más valores en el parámetro scope.
Existen varias maneras de realizar esta solicitud, y varían según el tipo de aplicación que estés compilando. Por ejemplo, una aplicación JavaScript puede solicitar un token de acceso con un redireccionamiento del navegador a Google, mientras que una aplicación instalada en un dispositivo que no tiene navegador usa solicitudes de servicio web. Para obtener más información sobre cómo realizar la solicitud, consulta Scenarios y las guías de implementación detalladas para cada tipo de app.
Algunas solicitudes requieren un paso de autenticación en el que el usuario accede con su Cuenta de Google. Después de acceder, se le pregunta al usuario si está dispuesto a otorgar uno o más permisos que solicita tu aplicación. Este proceso se denomina consentimiento del usuario.
Si el usuario otorga al menos un permiso, el servidor de autorización de Google envía a tu aplicación un token de acceso (o un código de autorización que tu aplicación puede usar para obtener un token de acceso) y una lista de permisos de acceso otorgados por ese token. Si el usuario no otorga el permiso, el servidor devuelve un error.
Por lo general, se recomienda solicitar permisos de forma incremental, en el momento en que se requiere el acceso, en lugar de hacerlo por adelantado. Por ejemplo, una app que quiera admitir el guardado de un evento en un calendario no debería solicitar acceso al Calendario de Google hasta que el usuario presione el botón "Agregar al calendario"; consulta Autorización incremental.
3. Examinar los permisos de acceso que otorgó el usuario
Compara los permisos incluidos en la respuesta del token de acceso con los permisos necesarios para acceder a las funciones y características de tu aplicación que dependen del acceso a una API de Google relacionada. Inhabilita las funciones de tu app que no puedan funcionar sin acceso a la API relacionada.
Es posible que el permiso incluido en tu solicitud no coincida con el incluido en tu respuesta, incluso
si el usuario otorgó todos los permisos solicitados. Consulta la documentación de cada API de Google para
conocer los permisos necesarios para el acceso. Una API puede asignar varios valores de cadena de permiso a un solo
permiso de acceso, lo que devuelve la misma cadena de permiso para todos los valores permitidos en la solicitud.
Por ejemplo, la API de Google People puede devolver un permiso de
https://www.googleapis.com/auth/contacts cuando una app solicita que un usuario autorice
un permiso de https://www.google.com/m8/feeds/; el método de la API de Google People
people.updateContact
requiere un permiso otorgado de https://www.googleapis.com/auth/contacts.
4. Envía el token de acceso a una API.
Después de que una aplicación obtiene un token de acceso, lo envía a una API de Google en un encabezado de la solicitud de autorización HTTP. Es posible enviar tokens como parámetros de cadena de consulta de URI, pero no lo recomendamos, ya que los parámetros de URI pueden terminar en archivos de registro que no son completamente seguros. Además, es una buena práctica de REST evitar la creación de nombres de parámetros de URI innecesarios.
Los tokens de acceso solo son válidos para el conjunto de operaciones y recursos descritos en el
scope de la solicitud de token. Por ejemplo, si se emite un token de acceso para la
API de Calendario de Google, no se otorga acceso a la API de Contactos de Google. Sin embargo, puedes
enviar ese token de acceso a la API de Calendario de Google varias veces para operaciones similares.
5. Actualiza el token de acceso, si es necesario.
Los tokens de acceso tienen una vida útil limitada. Si tu aplicación necesita acceder a una API de Google más allá del ciclo de vida de un solo token de acceso, puede obtener un token de actualización. Un token de actualización permite que tu aplicación obtenga tokens de acceso nuevos.
Situaciones
En estas situaciones, se describe cómo usar OAuth 2.0 para solicitar códigos de autorización y obtener tokens de acceso y de actualización para diferentes tipos de aplicaciones.
Aplicaciones de servidor web
El endpoint de Google OAuth 2.0 admite aplicaciones de servidor web que usan lenguajes y frameworks como PHP, Java, Go, Python, Ruby y ASP.NET.
La secuencia de autorización comienza cuando tu aplicación redirecciona un navegador a una URL de Google. La URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google se encarga de la autenticación del usuario, la selección de la sesión y el consentimiento del usuario. El resultado es un código de autorización que la aplicación puede intercambiar por un token de acceso y un token de actualización.
La aplicación debe almacenar el token de actualización para usarlo en el futuro y usar el token de acceso para acceder a una API de Google. Una vez que venza el token de acceso, la aplicación usará el token de actualización para obtener uno nuevo.
Si deseas obtener más detalles, consulta Cómo usar OAuth 2.0 para aplicaciones de servidor web.
Aplicaciones instaladas
El extremo de Google OAuth 2.0 admite aplicaciones que se instalan en dispositivos como computadoras, dispositivos móviles y tablets. Cuando crees un ID de cliente a través de la Consola de APIs de Google, especifica que se trata de una aplicación instalada y, luego, selecciona Android, extensión de Chrome, iOS o app para computadoras como el tipo de aplicación.
El proceso genera un ID de cliente y, en algunos casos, un secreto del cliente, que incorporas en el código fuente de tu aplicación. (En este contexto, el secreto del cliente no se trata como un secreto).
La secuencia de autorización comienza cuando tu aplicación redirecciona un navegador a una URL de Google. La URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google se encarga de la autenticación del usuario, la selección de la sesión y el consentimiento del usuario. El resultado es un código de autorización que la aplicación puede intercambiar por un token de acceso. La aplicación debe validar el token de acceso antes de incluirlo en una solicitud a la API de Google. Cuando el token vence, la aplicación repite el proceso.
De manera opcional, un servidor de backend puede intercambiar el código de autorización por un token de actualización y almacenarlo en una ubicación segura. Una vez que venza el token de acceso, el servidor de backend usará el token de actualización para obtener uno nuevo para la aplicación.
Para obtener más detalles, consulta Autoriza el acceso a los datos de usuario de Google para Android, Accede a las APIs de Google en una app para iOS y OAuth 2.0 para apps para computadoras.
Aplicaciones del cliente (JavaScript)
El extremo de Google OAuth 2.0 admite aplicaciones JavaScript que se ejecutan en un navegador.
La secuencia de autorización comienza cuando tu aplicación redirecciona un navegador a una URL de Google. La URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google se encarga de la autenticación del usuario, la selección de la sesión y el consentimiento del usuario.
El resultado es un token de acceso, que el cliente debe validar antes de incluirlo en una solicitud a la API de Google. Cuando el token vence, la aplicación repite el proceso.
Para obtener más detalles, consulta Cómo usar OAuth 2.0 para aplicaciones del cliente.
Aplicaciones en dispositivos de entrada limitada
El extremo de Google OAuth 2.0 admite aplicaciones que se ejecutan en dispositivos con entrada limitada, como consolas de juegos, cámaras de video y, también, impresoras.
La secuencia de autorización comienza cuando la aplicación realiza una solicitud de servicio web a una URL de Google para obtener un código de autorización. La respuesta contiene varios parámetros, incluidos una URL y un código que la aplicación muestra al usuario.
El usuario obtiene la URL y el código del dispositivo y, luego, cambia a otro dispositivo o computadora con mejores capacidades de entrada. El usuario inicia un navegador, navega a la URL especificada, accede y, luego, ingresa el código.
Mientras tanto, la aplicación sondea una URL de Google en un intervalo especificado. Después de que el usuario aprueba el acceso, la respuesta del servidor de Google contiene un token de acceso y un token de actualización. La aplicación debe almacenar el token de actualización para usarlo en el futuro y usar el token de acceso para acceder a una API de Google. Cuando el token de acceso vence, la aplicación usa el token de actualización para obtener uno nuevo.
Para obtener más información, consulta Usa OAuth 2.0 para dispositivos.
Cuentas de servicio
Las APIs de Google, como la API de Prediction y Google Cloud Storage, pueden actuar en nombre de tu aplicación sin acceder a la información del usuario. En estas situaciones, tu aplicación debe probar su propia identidad ante la API, pero no se necesita el consentimiento del usuario. De manera similar, en situaciones empresariales, tu aplicación puede solicitar acceso delegado a algunos recursos.
Para estos tipos de interacciones de servidor a servidor, necesitas una cuenta de servicio, que es una cuenta que pertenece a tu aplicación, no a un usuario final individual. Tu aplicación llama a las APIs de Google en nombre de la cuenta de servicio, y no se requiere el consentimiento del usuario. (En situaciones que no son de cuentas de servicio, tu aplicación llama a las APIs de Google en nombre de los usuarios finales y, a veces, se requiere el consentimiento del usuario).
Las credenciales de una cuenta de servicio, que obtienes de la Consola de APIs de Google, incluyen una dirección de correo electrónico generada que es única, un ID de cliente y, al menos, un par de claves pública y privada. Usa el ID de cliente y una clave privada para crear un JWT firmado y una solicitud de token de acceso en el formato adecuado. Luego, tu aplicación envía la solicitud de token al servidor de autorización de Google OAuth 2.0, que devuelve un token de acceso. La aplicación usa el token para acceder a una API de Google. Cuando el token vence, la aplicación repite el proceso.
Para obtener más información, consulta la documentación de la cuenta de servicio.
Tamaño del token
Los tokens pueden variar de tamaño, hasta los siguientes límites:
Los tokens de acceso que devuelve la API del Servicio de tokens de seguridad de Google Cloud tienen una estructura similar a la de los tokens de acceso de OAuth 2.0 de la API de Google, pero tienen límites de tamaño diferentes. Para obtener más detalles, consulta la documentación de la API.
Google se reserva el derecho de cambiar el tamaño de los tokens dentro de estos límites, y tu aplicación debe admitir tamaños de tokens variables según corresponda.
Actualiza el vencimiento del token
Debes escribir tu código para anticipar la posibilidad de que un token de actualización otorgado ya no funcione. Un token de actualización puede dejar de funcionar por uno de los siguientes motivos:
Un proyecto de Google Cloud Platform con una pantalla de consentimiento de OAuth configurada para un tipo de usuario externo y un estado de publicación de "Prueba" recibe un token de actualización que vence en 7 días, a menos que los únicos permisos de OAuth solicitados sean un subconjunto de nombre, dirección de correo electrónico y perfil de usuario (a través de los permisos
userinfo.email, userinfo.profile, openid o sus equivalentes de OpenID Connect).
Actualmente, hay un límite de 100 tokens de actualización por Cuenta de Google y por ID de cliente de OAuth 2.0. Si se alcanza el límite, la creación de un nuevo token de actualización invalida automáticamente el token de actualización más antiguo sin previo aviso. Este límite no se aplica a las cuentas de servicio.
También hay un límite mayor para la cantidad total de tokens de actualización que puede tener una cuenta de usuario o de servicio en todos los clientes. La mayoría de los usuarios normales no superarán este límite, pero es posible que sí lo haga la cuenta de un desarrollador que se use para probar una implementación.
Si necesitas autorizar varios programas, máquinas o dispositivos, una solución alternativa es limitar la cantidad de clientes que autorizas por Cuenta de Google a 15 o 20. Si eres administrador de Google Workspace, puedes crear usuarios adicionales con privilegios de administrador y usarlos para autorizar algunos de los clientes.
Cómo lidiar con las políticas de control de sesiones para las organizaciones de Google Cloud Platform (GCP)
Es posible que los administradores de organizaciones de GCP requieran que los usuarios se vuelvan a autenticar con frecuencia mientras
acceden a los recursos de GCP con la
función de control de sesiones de
Google Cloud. Esta política afecta el acceso a la consola de Google Cloud, al
SDK de Google Cloud (también conocido como la CLI de gcloud)
y a cualquier aplicación de OAuth de terceros que requiera el permiso de Cloud Platform. Si un
usuario tiene una política de control de sesiones, cuando venza la duración de la sesión, tus
llamadas a la API generarán un error similar al que se produciría si se revocara el token de actualización: la
llamada fallará con un tipo de error invalid_grant. El campo
error_subtype se puede usar para distinguir entre un token revocado y una falla debido a una política de
control de sesiones (por ejemplo, "error_subtype": "invalid_rapt"). Como la duración de las sesiones
puede ser muy limitada (entre 1 y 24 horas), este caso se debe controlar
reiniciando una sesión de autenticación.
Del mismo modo, no debes usar ni fomentar el uso de credenciales de usuario para la implementación de servidor a servidor. Si las credenciales de usuario se implementan en un servidor para trabajos o tareas de larga duración y un cliente aplica políticas de control de sesiones a esos usuarios, la aplicación del servidor fallará, ya que no habrá forma de volver a autenticar al usuario cuando venza la duración de la sesión.
Para obtener más información sobre cómo ayudar a tus clientes a implementar esta función, consulta este artículo de ayuda para administradores.
Bibliotecas cliente
Las siguientes bibliotecas cliente se integran en frameworks populares, lo que simplifica la implementación de OAuth 2.0. Con el tiempo, se agregarán más funciones a las bibliotecas.
- Biblioteca de Google Auth para Java
- Biblioteca cliente de la API de Google para Python
- Biblioteca cliente de la API de Google para Dart
- Biblioteca cliente de la API de Google para Go
- Biblioteca cliente de la API de Google para .NET
- Biblioteca cliente de la API de Google para Ruby
- Biblioteca cliente de la API de Google para PHP
- Biblioteca cliente de la API de Google para JavaScript
- GTMAppAuth: Biblioteca cliente de OAuth para Mac y iOS