Cómo usar OAuth 2.0 para acceder a las API de Google

Las API 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 del servidor web, las aplicaciones de dispositivo limitado, instaladas y del cliente.

Para comenzar, obtén las credenciales de cliente de OAuth 2.0 de Google API Console. 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 quieres acceder. Si deseas ver una demostración interactiva de cómo usar 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 ofrece 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 deseas 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 al acceder 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 desde Google API Console.

Visita Google API Console para obtener credenciales de OAuth 2.0, como un ID de cliente y un secreto del 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í.

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

Antes de que tu 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 diversos 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 de token de acceso, la aplicación envía uno o más valores en el parámetro scope.

Existen varias maneras de realizar esta solicitud, que varían según el tipo de aplicación que compiles. Por ejemplo, una aplicación de JavaScript puede solicitar un token de acceso utilizando un redireccionamiento del navegador a Google, mientras que una aplicación instalada en un dispositivo que no tiene navegador utiliza 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 tu aplicación está solicitando. Este proceso se denomina consentimiento de los usuarios.

Si el usuario otorga al menos un permiso, el servidor de autorización de Google envía a la 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 permisos de acceso otorgados por ese token. Si el usuario no otorga el permiso, el servidor muestra un error.

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 desea 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 a Calendario" (consulta Autorización incremental).

3. Examina los permisos de acceso otorgados por el usuario.

Compara los permisos incluidos en la respuesta del token de acceso con los alcances necesarios para acceder a las características y funciones de tu aplicación que dependen del acceso a una API de Google relacionada. Inhabilita cualquier función de la app que no pueda funcionar sin acceso a la API relacionada.

Es posible que el alcance incluido en la solicitud no coincida con el alcance de la 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 mapear varios valores de string de alcance a un solo permiso de acceso y mostrar la misma string de alcance para todos los valores permitidos en la solicitud. Ejemplo: La API de personas de Google puede mostrar un permiso de https://www.googleapis.com/auth/contacts cuando una aplicación solicitó a un usuario autorizar un alcance de https://www.google.com/m8/feeds/; el método people.updateContact de la API de personas de Google 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 solicitud de autorización HTTP. Es posible enviar tokens como parámetros de string de consulta de URI, pero no los recomendamos, ya que los parámetros de URI pueden terminar en archivos de registro que no son completamente seguros. Además, se recomienda evitar los 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 archivo scope de la solicitud de 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, puedes enviar ese token de acceso a la API de Google Calendar 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 desde el principio de un solo token de acceso, puede obtener un token de actualización. Un token de actualización permite a tu aplicación obtener nuevos tokens de acceso.

Situaciones

Aplicaciones de servidor web

El extremo de Google OAuth 2.0 admite 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 búsqueda que indican el tipo de acceso que se solicita. Google controla la autenticación, la selección de sesiones 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 usarlo para acceder a una API de Google. Una vez que caduca el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

La 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 lo usa para llamar a un extremo de la API de Google.

Si quieres 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 Google API Console, especifica que se trata de una aplicación instalada y, luego, selecciona Android, Chrome, iOS, Universal Platform Platform (UWP) o la app de escritorio como el tipo de aplicación.

El proceso da como resultado 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 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 búsqueda que indican el tipo de acceso que se solicita. Google controla la autenticación, la selección de sesiones 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 usarlo para acceder a una API de Google. Una vez que caduca el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

La 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 lo usa para llamar a un extremo de la API de Google.

Si quieres obtener más 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 búsqueda que indican el tipo de acceso que se solicita. Google controla la autenticación, la selección de sesiones 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.

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

Si quieres obtener más información, 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 de entrada limitada, como consolas de juegos, impresoras y cámaras de video.

La secuencia de autorización comienza con la aplicación que 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 y, luego, cambia a un dispositivo o computadora independiente con capacidades de entrada enriquecidas. 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 usarlo para acceder a una API de Google. Una vez que caduca el token de acceso, la aplicación usa el token de actualización para obtener uno nuevo.

El usuario accede en un dispositivo aparte que tiene un navegador.

Para obtener más información, consulta Cómo usar OAuth 2.0 para dispositivos.

Cuentas de servicio

Las API de Google, como la API de predicción 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 necesita demostrar su propia identidad a la API, pero no necesita el consentimiento del usuario. Del mismo modo, en situaciones empresariales, la 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 y no a un usuario final individual. Tu aplicación llama a las API de Google en nombre de la cuenta de servicio y no se requiere el consentimiento del usuario. (En situaciones que no pertenezcan a cuentas de servicio, la 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 obtienes 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 o privadas. Usas el ID de cliente y una clave privada para crear un JWT firmado y crear una solicitud de token de acceso en el formato adecuado. La 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.

Tu aplicación de servidor usa un JWT para solicitar un token del servidor de autorización de Google y después usa el token para llamar a un extremo de la API de Google. No
                    hay usuarios finales involucrados.

Para obtener más detalles, 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:

  • 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 servicio de tokens de seguridad de Google Cloud están estructurados de manera similar a los tokens de acceso de OAuth 2.0 de las API de Google, pero tienen límites de tamaño distintos. 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 prever la posibilidad de que un token de actualización otorgado ya no funcione. Un token de actualización puede dejar de funcionar por alguno de los siguientes motivos:

  • El usuario revocó el acceso de tu app.
  • No se ha usado el token de actualización durante seis meses.
  • El usuario cambió las contraseñas 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 (en vivo).
  • 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 el estado de publicación de “Prueba” recibe un token de actualización que vence en 7 días.

Actualmente, hay un límite de 50 tokens de actualización por Cuenta de Google por ID de cliente de OAuth 2.0. Si se alcanza el límite, la creación automática de un nuevo token invalida el más antiguo sin previo aviso. Este límite no se aplica a las cuentas de servicio.

También existe un límite mayor en la cantidad total de tokens de actualización que pueden tener las cuentas de usuario o de servicio entre todos los clientes. La mayoría de los usuarios normales no superarán este límite, pero es posible que una cuenta de desarrollador que se use para probar una implementación sí lo haga.

Si necesitas autorizar varios programas, máquinas o dispositivos, una solución alternativa es limitar a 15 o 20 la cantidad de clientes que autorices por cuenta de Google. Si eres un administrador de Google Workspace, puedes crear usuarios adicionales con privilegios de administrador y usarlos para autorizar a algunos de los clientes.

Cómo abordar las políticas de control de sesiones para organizaciones de Google Cloud Platform (GCP)

Los administradores de organizaciones de GCP pueden necesitar una reautenticación frecuente de los usuarios cuando acceden a los recursos de GCP mediante la función de control de sesiones 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 de OAuth de terceros que requiera el permiso de Cloud Platform. Si un usuario tiene implementada una política de control de sesión, cuando 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 el tipo de error invalid_token. Se puede usar el tipo de suberror entre un token de revocación y un error debido a una política de control de sesión. Como la duración de las sesiones puede ser muy limitada (de 1 hora a 24 horas), esta situación se debe controlar de manera fluida mediante el reinicio de una sesión de autenticación.

Del mismo modo, no debes usar ni alentar el uso de credenciales de usuario para la implementación de servidor a servidor. Si se implementan credenciales de usuario en un servidor para operaciones o trabajos de larga duración y un cliente aplica políticas de control de sesiones en 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 deseas obtener más información sobre cómo ayudar a los clientes a implementar esta función, consulta este artículo de ayuda centrado en el administrador.

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.