Las APIs de Google usan el protocolo OAuth 2.0 para la autenticación y autorización. Google admite situaciones comunes de OAuth 2.0, como las de servidor web, del cliente, instaladas y de las aplicaciones de dispositivo de entrada limitada.
Para comenzar, obtén las credenciales de cliente de OAuth 2.0 en Google API Console. Luego, la 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 ver una demostración interactiva del uso de OAuth 2.0 con Google (incluye la opción de usar tus propias credenciales de cliente), experimenta con OAuth 2.0 Playground.
En esta página, se brinda una descripción general de las situaciones de autorización de OAuth 2.0 que admite Google y se proporcionan vínculos a contenido más detallado. Si quieres obtener información 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 general, debes seguir cinco pasos:
1. Obtén credenciales de OAuth 2.0 de Google API Console.
Visita Google API Console para obtener credenciales de OAuth 2.0, como un ID de cliente y un secreto de cliente, que Google y tu aplicación conocen. El conjunto de valores varía según el tipo de aplicación que compiles. 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 apropiado para la plataforma en la que se ejecutará tu app, por ejemplo:
- Para las apps web de JavaScript o del servidor, usa el tipo de cliente "Web". No uses este tipo de cliente para ninguna otra aplicación, como apps nativas o para dispositivos móviles.
- En el caso de las apps para Android, usa el tipo de cliente "Android".
- En el caso de las apps para iOS y macOS, usa el tipo de cliente "iOS".
- Para las apps de Universal Windows Platform, usa el tipo de cliente "Universal Windows Platform".
- Para dispositivos de entrada limitada, como TV o dispositivos incorporados, usa el tipo de cliente "TVs y dispositivos de entrada limitada".
- Para las interacciones de servidor a servidor, usa cuentas de servicio.
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 diferentes grados de acceso a varias APIs. Un parámetro variable llamado scope controla el conjunto de recursos y operaciones que permite un token de acceso. Durante la solicitud de token de acceso, la aplicación envía uno o más valores en el parámetro scope.
Existen varias formas de realizar esta solicitud y varían según el tipo de aplicación que compiles. Por ejemplo, una aplicación de JavaScript podría solicitar un token de acceso mediante un redireccionamiento del navegador a Google, mientras que una aplicación instalada en un dispositivo sin navegador usa solicitudes de servicio web.
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 la aplicación está solicitando. 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 la aplicación puede usar para obtener un token de acceso) y una lista de alcances de acceso otorgados por ese token. Si el usuario no otorga el permiso, se mostrará un error en el servidor.
Por lo general, se recomienda solicitar permisos de forma incremental, en el momento en que se requiere acceso, en lugar de hacerlo por adelantado. Por ejemplo, una app que desee admitir el guardado de un evento en un calendario no debe solicitar acceso al Calendario de Google hasta que el usuario presione el botón "Agregar al Calendario". Consulta Autorización incremental.
3. Examina los alcances de acceso otorgados por el usuario.
Compara los alcances incluidos en la respuesta del token de acceso con los permisos necesarios para acceder a las funciones y funcionalidades 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 alcance incluido en tu solicitud no coincida con el alcance incluido en tu respuesta, incluso si el usuario otorgó todos los permisos solicitados. Consulta la documentación de cada API de Google a fin de conocer los permisos necesarios para acceder. Una API puede asignar varios valores de string de alcance a un solo alcance de acceso y mostrar la misma string de alcance para todos los valores permitidos en la solicitud.
Ejemplo: Es posible que la API de Google People muestre un alcance de https://www.googleapis.com/auth/contacts cuando una app solicitó que un usuario autorice un alcance de https://www.google.com/m8/feeds/; el método people.updateContact de la API de Google People requiere un permiso otorgado de https://www.googleapis.com/auth/contacts.
4. Envía el token de acceso a una API.
Cuando una aplicación obtiene un token de acceso, lo envía a una API de Google en un encabezado de 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, se recomienda que REST evite crear 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 del 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 del Calendario de Google varias veces para operaciones similares.
5. Si es necesario, actualiza el token de acceso.
Los tokens de acceso tienen una vida útil limitada. Si tu aplicación necesita acceder a una API de Google más allá de la vida útil de un único token de acceso, puede obtener un token de actualización. Los tokens de actualización permiten que la aplicación obtenga nuevos tokens de acceso.
Situaciones
Aplicaciones de servidor web
El extremo de Google OAuth 2.0 es compatible con aplicaciones de servidor web que usan lenguajes y frameworks, como PHP, Java, 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, 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 vence el token de acceso, la aplicación utiliza el token de actualización para obtener uno nuevo.
Si deseas obtener información detallada, consulta Usa OAuth 2.0 para aplicaciones de servidor web.
Aplicaciones instaladas
El extremo de Google OAuth 2.0 admite aplicaciones instaladas en dispositivos como computadoras, dispositivos móviles y tablets. Cuando crees un ID de cliente a través de Google API Console, especifica que se trata de una aplicación instalada y, luego, selecciona Android, Chrome app, iOS, Universal Windows Platform (UWP) or Desktop app como el tipo de aplicación.
El proceso genera un ID de cliente y, en algunos casos, un secreto de cliente, que incorporas en el código fuente de tu aplicación. (En este contexto, el secreto del cliente obviamente no se trata como uno 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, 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 vence el token de acceso, la aplicación utiliza el token de actualización para obtener uno nuevo.
Para averiguar detalles, consulta Cómo usar OAuth 2.0 para aplicaciones instaladas.
Aplicaciones del cliente (JavaScript)
El extremo de Google OAuth 2.0 admite aplicaciones de 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, 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 información detallada, consulta Usa OAuth 2.0 para aplicaciones del cliente.
Aplicaciones en dispositivos de entrada limitada
El extremo de Google OAuth 2.0 es compatible con aplicaciones que se ejecutan en dispositivos de entrada limitada, como consolas de juegos, impresoras y cámaras de video.
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, como una URL y un código que la aplicación le muestra al usuario.
El usuario obtiene la URL y el código del dispositivo y, luego, cambia a otro dispositivo o computadora con capacidades de entrada más completas. 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 a un intervalo específico. Cuando 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. Una vez que vence el token de acceso, la aplicación utiliza el token de actualización para obtener uno nuevo.
Para obtener más información, consulta Cómo usar OAuth 2.0 para dispositivos.
Cuentas de servicio
Las APIs de Google, como Prediction API 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 a la API, pero no es necesario el consentimiento del usuario. Del mismo modo, en situaciones empresariales, tu aplicación puede solicitar acceso delegado a algunos recursos.
Para estos tipos de interacciones servidor a servidor, necesitas una cuenta de servicio, que corresponde a una cuenta que pertenece a tu aplicación en lugar de 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 sean de cuentas de servicio, tu aplicación llama a las APIs de Google en nombre de los usuarios finales y, a veces, se requiere su consentimiento).
Las credenciales de una cuenta de servicio, que se obtienen de Google API Console, incluyen una dirección de correo electrónico generada que es única, un ID de cliente y al menos un par de claves públicas/privadas. Usa el ID de cliente y una clave privada para crear un JWT firmado y construir una solicitud de token de acceso con el formato adecuado. Luego, tu aplicación envía la solicitud de token al servidor de autorización de Google OAuth 2.0, que muestra 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 detalles, consulta la documentación de la cuenta de servicio.
Tamaño del token
El tamaño de los tokens puede variar hasta con los siguientes límites:
- Códigos de autorización: 256 bytes
- Tokens de acceso: 2,048 bytes
- Tokens de actualización: 512 bytes
Los tokens de acceso que muestra la API de Security Token Service de Google Cloud están estructurados de manera similar a 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 del token dentro de estos límites, y tu aplicación debe admitir tamaños de token variables según corresponda.
Actualiza el vencimiento del token
Debes escribir el código para anticipar la posibilidad de que un token de actualización otorgado deje de funcionar. Un token de actualización puede dejar de funcionar por alguno de los siguientes motivos:
- El usuario revocó el acceso de tu app.
- El token de actualización no se usó durante seis meses.
- El usuario cambió la contraseña, y el token de actualización contiene permisos de Gmail.
- La cuenta de usuario superó la cantidad máxima de tokens de actualización otorgados (activos).
- Si un administrador
configuró alguno de los servicios solicitados en los permisos de tu app como Restringido (el error es
admin_policy_enforced). - En el caso de las APIs de Google Cloud Platform, se podría haber superado la duración de la sesión que estableció el administrador.
Un proyecto de Google Cloud Platform con una pantalla de consentimiento de OAuth configurada para un tipo de usuario externo y el estado de publicación "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 de
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 por ID de cliente de OAuth 2.0. Si se alcanza el límite, crear un nuevo token de actualización invalida automáticamente el token de actualización más antiguo sin advertencia. Este límite no se aplica a las cuentas de servicio.
También hay un límite mayor en la cantidad total de tokens de actualización que una cuenta de usuario o de servicio puede tener en todos los clientes. La mayoría de los usuarios normales no superarán este límite, pero sí lo hará la cuenta de un desarrollador que se use para probar una implementación.
Si necesitas autorizar varios programas, máquinas o dispositivos, puedes 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 a algunos de los clientes.
Trabaja con políticas de control de sesiones para organizaciones de Google Cloud Platform (GCP)
Los administradores de las organizaciones de GCP pueden requerir una reautenticación frecuente de los usuarios mientras acceden a los recursos de GCP mediante la función de control de sesiones de Google Cloud. Esta política afecta el acceso a la consola de Google Cloud, el
SDK de Google Cloud (también conocido como la CLI de
gcloud) y cualquier aplicación de OAuth de terceros que requiera el permiso de Cloud Platform. Si un
usuario tiene una política de control de sesión implementada, cuando se venza la duración de la sesión, las
llamadas a la API fallarán de manera similar a lo que sucederí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 un error debido a una política
de control de sesión (por ejemplo, "error_subtype": "invalid_rapt"). Como las duraciones de sesión
de sesión pueden ser muy limitadas (la duración de una sesión de autenticación debe ser de 4 horas a 2 horas) de manera fluida.
Igualmente, 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 operaciones o trabajos de larga duración y un cliente aplica políticas de control de sesión 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.
Si quieres obtener más información para ayudar a tus clientes a implementar esta función, consulta este artículo de ayuda centrado en los administradores.
Bibliotecas cliente
Las siguientes bibliotecas cliente se integran en los frameworks populares, lo que facilita la implementación de OAuth 2.0. Con el tiempo, se agregarán más funciones a las bibliotecas.
- Biblioteca cliente de las APIs de Google para Java
- Biblioteca cliente de las API de Google para Python
- Biblioteca cliente de la API de Google para Go
- Biblioteca cliente de las API de Google para .NET
- Biblioteca cliente de las API de Google para Ruby
- Biblioteca cliente de las API de Google para PHP
- Biblioteca cliente de las API de Google para JavaScript
- GTMAppAuth: Biblioteca cliente de OAuth para iOS y Mac