Usar OAuth 2.0 para acceder a las API de Google

Las API de Google utilizan el protocolo OAuth 2.0 para la autenticación y autorización. Google admite escenarios comunes de OAuth 2.0, como los del servidor web, del lado del cliente, instalados y aplicaciones de dispositivo de entrada limitada.

Para comenzar, obtenga las credenciales de cliente de OAuth 2.0 del Google API Console . Luego, su aplicación cliente solicita un token de acceso del servidor de autorización de Google, extrae un token de la respuesta y envía el token a la API de Google a la que desea acceder. Para obtener una demostración interactiva del uso de OAuth 2.0 con Google (incluida la opción de usar sus propias credenciales de cliente), experimente con OAuth 2.0 Playground .

Esta página ofrece una descripción general de los escenarios de autorización de OAuth 2.0 que admite Google y proporciona vínculos a contenido más detallado. Para obtener detalles sobre el uso de OAuth 2.0 para la autenticación, consulte OpenID Connect .

Pasos básicos

Todas las aplicaciones siguen un patrón básico al acceder a una API de Google mediante OAuth 2.0. En un nivel alto, sigues cinco pasos:

1. Obtenga las credenciales de OAuth 2.0 del Google API Console.

Visite Google API Console para obtener credenciales de OAuth 2.0, como un ID de cliente y un secreto de cliente, que tanto Google como su aplicación conocen. El conjunto de valores varía según el tipo de aplicación que esté creando. Por ejemplo, una aplicación de JavaScript no requiere un secreto, pero una aplicación de servidor web sí.

2. Obtenga un token de acceso del servidor de autorización de Google.

Antes de que su aplicación pueda acceder a datos privados mediante una API de Google, debe obtener un token de acceso que le otorgue acceso a esa API. Un solo token de acceso puede otorgar distintos grados de acceso a varias API. Un parámetro variable llamado scope controla el conjunto de recursos y operaciones que permite un token de acceso. Durante la solicitud del token de acceso, su aplicación envía uno o más valores en el parámetro de scope .

Hay varias formas de realizar esta solicitud y varían según el tipo de aplicación que esté creando. Por ejemplo, una aplicación de JavaScript puede solicitar un token de acceso mediante un redireccionamiento del navegador a Google, mientras que una aplicación instalada en un dispositivo que no tiene navegador utiliza solicitudes de servicios web.

Algunas solicitudes requieren un paso de autenticación en el que el usuario inicia sesión con su cuenta de Google. Después de iniciar sesión, se le pregunta al usuario si está dispuesto a otorgar uno o más permisos que solicita su 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 su aplicación un token de acceso (o un código de autorización que su aplicación puede usar para obtener un token de acceso) y una lista de los alcances de acceso otorgados por ese token. Si el usuario no otorga el permiso, el servidor devuelve un error.

Por lo general, es una buena práctica solicitar los ámbitos de forma incremental, en el momento en que se requiere el acceso, en lugar de hacerlo por adelantado. Por ejemplo, una aplicación que desee admitir el almacenamiento de un evento en un calendario no debe solicitar acceso a Google Calendar hasta que el usuario presione el botón "Agregar al calendario"; consulte Autorización incremental .

3. Examinar los alcances de acceso otorgados por el usuario.

Compare los alcances incluidos en la respuesta del token de acceso con los alcances necesarios para acceder a las funciones y la funcionalidad de su aplicación, dependiendo del acceso a una API de Google relacionada. Deshabilite cualquier característica de su aplicación que no pueda funcionar sin acceso a la API relacionada.

El alcance incluido en su solicitud puede no coincidir con el alcance incluido en su respuesta, incluso si el usuario otorgó todos los alcances solicitados. Consulte la documentación de cada API de Google para conocer los alcances necesarios para el acceso. Una API puede asignar varios valores de cadena de alcance a un único alcance de acceso, devolviendo la misma cadena de alcance para todos los valores permitidos en la solicitud. Ejemplo: la API de Google People puede devolver un alcance de https://www.googleapis.com/auth/contacts cuando una aplicación solicita a un usuario autorizar un alcance de https://www.google.com/m8/feeds/ el método people.updateContact API de Google People requiere un alcance otorgado de https://www.googleapis.com/auth/contacts .

4. Envíe el token de acceso a una API.

Una vez que una aplicación obtiene un token de acceso, envía el token 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 URI, pero no lo recomendamos, porque los parámetros 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 URI innecesarios. Tenga en cuenta que la compatibilidad con cadenas de consulta quedará obsoleta el 1 de junio de 2021.

Los tokens de acceso son válidos solo para el conjunto de operaciones y recursos descritos en el scope de la solicitud del token. Por ejemplo, si se emite un token de acceso para la API de Google Calendar, no otorga acceso a la API de Contactos de Google. Sin embargo, puede enviar ese token de acceso a la API de Google Calendar varias veces para operaciones similares.

5. Actualice el token de acceso, si es necesario.

Los tokens de acceso tienen una vida útil limitada. Si su aplicación necesita acceso a una API de Google más allá de la vida útil de un solo token de acceso, puede obtener un token de actualización. Un token de actualización permite que su aplicación obtenga nuevos tokens de acceso.

Escenarios

Aplicaciones de servidor web

El punto final de Google OAuth 2.0 admite aplicaciones de servidor web que utilizan lenguajes y marcos como PHP, Java, Python, Ruby y ASP.NET.

La secuencia de autorización comienza cuando su aplicación redirige un navegador a una URL de Google; la URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google maneja 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 uso futuro y usar el token de acceso para acceder a una API de Google. Una vez que expira el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

Tu aplicación envía una solicitud de token al servidor de autorización de Google, recibe un código de autorización, intercambia el código por un token y usa el token para llamar a un extremo de la API de Google.

Para obtener más información, consulte Uso de OAuth 2.0 para aplicaciones de servidor web .

Aplicaciones instaladas

El punto final de Google OAuth 2.0 admite aplicaciones que están instaladas en dispositivos como computadoras, dispositivos móviles y tabletas. Cuando cree un ID de cliente a través del Google API Console , especifique que se trata de una aplicación instalada, luego seleccione Android, aplicación Chrome, iOS, Plataforma universal de Windows (UWP) o aplicación de escritorio como tipo de aplicación.

El proceso da como resultado un ID de cliente y, en algunos casos, un secreto de cliente, que incrustar en el código fuente de su aplicación. (En este contexto, el secreto del cliente obviamente no se trata como un secreto).

La secuencia de autorización comienza cuando su aplicación redirige un navegador a una URL de Google; la URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google maneja 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 uso futuro y usar el token de acceso para acceder a una API de Google. Una vez que expira el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

Tu aplicación envía una solicitud de token al servidor de autorización de Google, recibe un código de autorización, intercambia el código por un token y usa el token para llamar a un extremo de la API de Google.

Para obtener más información, consulte Uso de OAuth 2.0 para aplicaciones instaladas .

Aplicaciones del lado del cliente (JavaScript)

El punto final de Google OAuth 2.0 admite aplicaciones JavaScript que se ejecutan en un navegador.

La secuencia de autorización comienza cuando su aplicación redirige un navegador a una URL de Google; la URL incluye parámetros de consulta que indican el tipo de acceso que se solicita. Google maneja 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 de API de Google. Cuando el token caduca, la aplicación repite el proceso.

Su aplicación JS envía una solicitud de token al servidor de autorización de Google, recibe un token, valida el token y usa el token para llamar a un extremo de la API de Google.

Para obtener más información, consulte Uso de OAuth 2.0 para aplicaciones del lado del cliente .

Aplicaciones en dispositivos de entrada limitada

El punto final de Google OAuth 2.0 admite aplicaciones que se ejecutan en dispositivos de entrada limitada, como consolas de juegos, cámaras de video e 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, incluida una URL y un código que la aplicación muestra al usuario.

El usuario obtiene la URL y el código del dispositivo, luego cambia a un dispositivo o computadora separada con capacidades de entrada más ricas. El usuario inicia un navegador, navega a la URL especificada, inicia sesión e ingresa el código.

Mientras tanto, la aplicación sondea una URL de Google en un intervalo específico. Una vez 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 uso futuro y usar el token de acceso para acceder a una API de Google. Una vez que expira el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

El usuario inicia sesión en un dispositivo separado que tiene un navegador.

Para obtener más información, consulte Uso de OAuth 2.0 para dispositivos .

Cuentas de servicio

Las API de Google, como la API Prediction y Google Cloud Storage, pueden actuar en nombre de su aplicación sin acceder a la información del usuario. En estas situaciones, su aplicación debe demostrar su propia identidad a la API, pero no es necesario el consentimiento del usuario. De manera similar, en escenarios empresariales, su aplicación puede solicitar acceso delegado a algunos recursos.

Para este tipo de interacciones de servidor a servidor, necesita una cuenta de servicio , que es una cuenta que pertenece a su aplicación en lugar de a un usuario final individual. Su aplicación llama a las API de Google en nombre de la cuenta de servicio y no se requiere el consentimiento del usuario. (En escenarios sin cuentas de servicio, su aplicación llama a las API 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 obtiene del 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ública / privada. Utiliza el ID de cliente y una clave privada para crear un JWT firmado y construir una solicitud de token de acceso en el formato apropiado. Luego, su 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 utiliza el token para acceder a una API de Google. Cuando el token caduca, la aplicación repite el proceso.

Su aplicación de servidor usa un JWT para solicitar un token del servidor de autorización de Google y luego usa el token para llamar a un punto final de la API de Google. Ningún usuario final está involucrado.

Para obtener más información, consulte la documentación de la cuenta de servicio .

Tamaño del token

Los tokens pueden variar en tamaño, hasta los siguientes límites:

  • Códigos de autorización: 256 bytes
  • Tokens de acceso: 2048 bytes
  • Actualizar tokens: 512 bytes

Los tokens de acceso devueltos por la API del servicio de token de seguridad de Google Cloud están estructurados de manera similar a los tokens de acceso OAuth 2.0 de la API de Google, pero tienen diferentes límites de tamaño de token. Para obtener más información, consulte la documentación de la API .

Google se reserva el derecho de cambiar el tamaño del token dentro de estos límites, y su aplicación debe admitir tamaños de token variables en consecuencia.

Actualizar el vencimiento del token

Debe escribir su 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 estos motivos:

  • El usuario ha revocado el acceso a su aplicación .
  • El token de actualización no se ha utilizado durante seis meses.
  • El usuario cambió las contraseñas y el token de actualización contiene los alcances de Gmail.
  • La cuenta de usuario ha superado el número máximo de tokens de actualización (activos) concedidos.
  • El usuario pertenece a una organización de Google Cloud Platform que tiene políticas de control de sesiones vigentes.

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.

Actualmente, existe un límite de 50 tokens de actualización por cuenta de Google por ID de cliente 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 en la cantidad total de tokens de actualización que una cuenta de usuario o cuenta de servicio puede tener en todos los clientes. La mayoría de los usuarios normales no excederán este límite, pero la cuenta de un desarrollador utilizada para probar una implementación podría hacerlo.

Si necesita autorizar varios programas, máquinas o dispositivos, una solución alternativa es limitar la cantidad de clientes que autoriza por cuenta de Google a 15 o 20. Si es administrador de Google Workspace , puede crear usuarios adicionales con privilegios administrativos utilícelos para autorizar a algunos de los clientes.

Tratar con las políticas de control de sesiones para las organizaciones de Google Cloud Platform (GCP)

Los administradores de 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 sesión de Google Cloud. Esta política afecta el acceso a Google Cloud Console, el SDK de Google Cloud (también conocido como CLI de gcloud) y cualquier aplicación OAuth de terceros que requiera el alcance de Cloud Platform. Si un usuario tiene una política de control de sesión implementada, al expirar la duración de la sesión, sus llamadas a la API generarán un error similar a lo que sucedería si se revocara el token de actualización. Dado que la duración de las sesiones puede ser muy limitada (entre 1 hora y 24 horas), este escenario debe manejarse correctamente reiniciando una sesión de autenticación.

Del mismo modo, no debe utilizar 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 u operaciones de larga ejecución y un cliente aplica políticas de control de sesión en dichos usuarios, la aplicación del servidor fallará ya que no habrá forma de volver a autenticar al usuario cuando expire la duración de la sesión.

Para obtener más información sobre cómo ayudar a sus clientes a implementar esta función, consulte este artículo de ayuda centrado en el administrador.

Bibliotecas cliente

Las siguientes bibliotecas cliente se integran con marcos populares, lo que simplifica la implementación de OAuth 2.0. Se agregarán más funciones a las bibliotecas con el tiempo.