Usar OAuth 2.0 para acceder a las API de Google

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 empezar, obtener las credenciales del cliente de OAuth 2.0 de la 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 una demostración interactiva de usar OAuth 2.0 con Google (incluyendo la opción de utilizar sus propias credenciales del cliente), experimenta con el espacio OAuth 2.0 .

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 detalles sobre el uso de OAuth 2.0 para la autenticación, consulte OpenID Conectar .

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. Obtener credenciales de OAuth 2.0 de la Google API Console.

Visita la Google API Console para obtener credenciales de OAuth 2.0 como un secreto ID de cliente y el cliente que se sabe que tanto Google como su aplicación. 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 llamada scope controla el conjunto de recursos y operaciones que un acceso permisos simbólicos. Durante la solicitud de acceso token, la aplicación envía uno o más valores en el scope de parámetros.

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 llama el 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 quiera admitir el guardado de un evento en un calendario no debe solicitar acceso a Google Calendar hasta que el usuario presione el botón "Agregar al calendario"; ver 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 La gente puede devolver un alcance de https://www.googleapis.com/auth/contacts cuando una aplicación solicita un usuario autoriza a un alcance de https://www.google.com/m8/feeds/ ; el método API de Google La gente people.updateContact requiere un alcance otorgado de https://www.googleapis.com/auth/contacts .

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

Después de una aplicación obtiene un token de acceso, envía el token a una API de Google en una solicitud de encabezado HTTP de Autorización . 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.

Los tokens de acceso son válidos sólo para el conjunto de las operaciones y los recursos descritos en el 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, 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 más detalles, 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 se crea un ID de cliente a través de la Google API Console , especificar que se trata de una aplicación instalada, a continuación, seleccione Android, Chrome, iOS, la plataforma de Windows universal (UWP), o para computadora de aplicación como el tipo de aplicación.

El proceso da como resultado un ID de cliente y, en algunos casos, un secreto de cliente, que se incrusta 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 más detalles, consulte Uso de OAuth 2.0 para las 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 más detalles, 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 más detalles, consulte Uso de OAuth 2.0 para los 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 estos tipos 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 se obtiene de la Google API Console, incluyen una dirección de correo electrónico generado que es único, un ID de cliente, y al menos una pública / clave privada pareja. 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 usa 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 más detalles, consulte la documentación de servicio de la cuenta .

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

Tokens de acceso devuelto por la nube de Google API del servicio de token de seguridad están estructurados de manera similar a la API de Google OAuth 2.0 tokens de acceso, pero tienen diferentes límites de tamaño de símbolo. Para más detalles, 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 una de estas razones:

  • El usuario ha revocado el acceso de 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 concedidos (activos).
  • 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 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 en el número 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 desarrollador utilizada para probar una implementación podría hacerlo.

Si tiene que autorizar varios programas, máquinas o dispositivos, una solución consiste en limitar el número de clientes que usted autorice por cuenta de Google a 15 o 20. Si usted es un administrador de Google espacio de trabajo , puede crear usuarios adicionales con privilegios administrativos y 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 GCP pueden requerir reautenticación frecuente de los usuarios, mientras que accedan a los recursos de GCP, utilizando la función de control de sesión de la nube de Google . Esto afecta a la política de acceso a Google Cloud Console, el SDK de Google Cloud (también conocida como la CLI gcloud), y cualquier solicitud de OAuth tercero que requiere el alcance Cloud Platform. Si un usuario tiene una política de control de sesión en su lugar, a la expiración de la duración de la sesión, sus llamadas API error cabo de forma similar a lo que sucedería si el token de actualización fue revocada - la llamada fallará con un tipo de error invalid_token ; el tipo de sub-error se puede utilizar para distinguir entre un token de revocación y una falla debido a una política de control de sesión. Como las duraciones de las sesiones pueden ser muy limitadas (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 de administración-centrado.

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.