Autentica y autoriza solicitudes de API y apps de Chat

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

La autenticación y la autorización son mecanismos que se usan para verificar la identidad y el acceso a los recursos, respectivamente. En este documento, se describe cómo funcionan la autenticación y la autorización para las apps de Chat y las solicitudes a la API de Chat.

Descripción general del proceso

En el siguiente diagrama, se muestran los pasos de alto nivel de autenticación y autorización para Google Chat:

Pasos de alto nivel para la autenticación y autorización de Google Chat
Figura 1: Pasos de alto nivel para la autenticación y autorización de Google Chat

  1. Configura un proyecto de Google Cloud, habilita la API de Chat y configura tu app de Chat: durante el desarrollo, crearás un proyecto de Google Cloud. En el proyecto de Google Cloud, debe habilitar la API de Chat, configurar su aplicación de Chat y configurar la autenticación.

  2. Llamar a la API de Chat: Cuando su aplicación llama a la API de REST de Chat (lo que suele suceder después de que un usuario en Google Chat invoca la aplicación mediante un mensaje, un clic en un botón de una tarjeta o mediante un comando de barra), envía las credenciales de autenticación a la API de Chat. Si tu app se autentica con una cuenta de servicio, las credenciales se envían como parte del código de tu app. Si tu app se autentica como usuario, es posible que este reciba un mensaje de acceso.

  3. Solicitar recursos: Tu app solicita acceso con los alcances que especifiques cuando configures la autenticación.

  4. Solicitar consentimiento: Si tu app se autentica como usuario, Google mostrará una pantalla de consentimiento de OAuth para que el usuario pueda decidir si le otorga a la app acceso a los datos solicitados. La autenticación con una cuenta de servicio no requiere el consentimiento del usuario.

  5. Envía una solicitud aprobada para recursos: si el usuario da su consentimiento para los alcances de autorización, la app agrupa las credenciales y los alcances aprobados por el usuario en una solicitud. La solicitud se envía al servidor de autorización de Google para obtener un token de acceso.

  6. Google muestra un token de acceso: el token de acceso contiene una lista de alcances otorgados. Si la lista de alcances que se muestra es más limitada que los permisos solicitados, tu app desactivará cualquier función que limite el token.

  7. Acceso a los recursos solicitados: Tu app usa el token de acceso de Google para invocar la API de Chat y acceder a los recursos de la API de Chat.

  8. Obtener un token de actualización (opcional): Si su aplicación necesita acceder a la API de Google Chat más allá de la vida útil de un solo token de acceso, puede obtener un token de actualización.

  9. Solicitar más recursos: Si tu app necesita más acceso, le solicita al usuario que otorgue permisos nuevos, lo que genera una nueva solicitud para obtener un token de acceso (pasos 3-6).

Cuándo las apps de chat requieren autenticación

Las apps de chat pueden enviar mensajes a Google Chat de forma síncrona o asíncrona. También pueden completar tareas, como crear un espacio de Chat, en nombre de un usuario.

Los mensajes síncronos no requieren autenticación, a menos que la app de Chat llame a la API de REST de Chat o a otra API de Google mientras se procesa una respuesta.

Para enviar mensajes asíncronos o trabajar en nombre de un usuario, las aplicaciones de chat realizan solicitudes RESTful a la API de REST de Chat, que requieren autenticación y autorización.

Los mensajes síncronos no requieren autenticación

Los mensajes síncronos son respuestas a eventos de Chat. Las apps de Google Chat pueden recibir y responder eventos después de que se configuran y publican en la página de configuración de apps de Chat, y no requieren autenticación ni autorización.

Estos son algunos ejemplos de eventos de chat síncronos:

  • Un usuario envía un mensaje a una app de Chat en Google Chat.
  • Un usuario menciona una app de chat.
  • Un usuario invoca uno de los comandos de barra de la app de Chat.

En el siguiente diagrama, se muestra una secuencia síncrona de solicitud y respuesta básica entre un usuario de Chat y una aplicación de chat:

No se requiere autorización para los mensajes síncronos
Figura 2: Los mensajes síncronos no requieren autenticación

  1. El usuario envía un mensaje a la app de Chat en Google Chat.
  2. Google Chat reenvía el mensaje a la app.
  3. La app recibe el mensaje, lo procesa y muestra una respuesta a Google Chat.
  4. Google Chat procesa la respuesta para el usuario o en un espacio.

Esta secuencia se repite para cada evento de Chat.

Los mensajes asíncronos requieren autenticación

Los mensajes asíncronos se producen cuando una app de Chat envía una solicitud a la API de REST de Chat, que requiere autenticación y autorización.

Al llamar a la API de REST, las apps de chat pueden publicar mensajes en Google Chat o completar tareas y acceder a datos en nombre de un usuario. Por ejemplo, después de detectar una interrupción del servidor, una app de chat puede llamar a la API de Chat para lo siguiente:

  • Crear un espacio de Chat dedicado a investigar y solucionar la interrupción
  • Agrega personas al espacio de Chat.
  • Publicar un mensaje en el espacio de Chat para dar detalles sobre la interrupción.

En el siguiente diagrama, se muestra una secuencia de mensajes asíncrona básica entre una aplicación de chat y un espacio de chat:

Se requiere autenticación para los mensajes asíncronos
Figura 3: Los mensajes asíncronos requieren autenticación

  1. Una app de chat crea un mensaje mediante una llamada a la API de REST de Chat con el método spaces.messages.create y, además, incluye las credenciales de la cuenta de servicio en la solicitud HTTP.
  2. Google Chat autentica la app de Chat con una cuenta de servicio o credenciales de usuario.
  3. Google Chat procesa el mensaje de la app en un espacio de Chat especificado.

Permisos de la API de Chat

Para definir el nivel de acceso otorgado a tu app, debes identificar y declarar los alcances de autorización. Un alcance de autorización es una string de URI de OAuth 2.0 que contiene el nombre de la app de Google Workspace, a qué tipo de datos accede y el nivel de acceso.

Google Chat admite los siguientes alcances:

Alcance de la API de Google Chat Descripción
https://www.googleapis.com/auth/chat.bot Permite que las apps de chat vean los chats y envíen mensajes.
https://www.googleapis.com/auth/chat.delete Borra conversaciones y espacios, y quita el acceso a los archivos asociados en Google Chat.
Membresías  
https://www.googleapis.com/auth/chat.memberships Vea, agregue y quite miembros de las conversaciones en Google Chat.
https://www.googleapis.com/auth/chat.memberships.app Permite que la aplicación de Chat se agregue y se quite de las conversaciones de Google Chat (y no de otras aplicaciones).
Mensajes  
https://www.googleapis.com/auth/chat.messages Crear, obtener, actualizar, borrar y enumerar mensajes en Google Chat
https://www.googleapis.com/auth/chat.messages.reactions Ver, agregar y borrar reacciones a los mensajes en Google Chat
https://www.googleapis.com/auth/chat.messages.reactions.create Agrega reacciones a los mensajes en Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Ver reacciones a mensajes en Google Chat
https://www.googleapis.com/auth/chat.messages.readonly Obtenga mensajes de Google Chat y enumérelos.
Espacios  
https://www.googleapis.com/auth/chat.spaces Cree conversaciones y espacios, y consulte o actualice los metadatos (incluida la configuración del historial) en Google Chat.
https://www.googleapis.com/auth/chat.spaces.create Cree conversaciones en Google Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Consulta el chat y los espacios en Google Chat.

Para obtener más información sobre los alcances de las API de Google Workspace, consulta Cómo elegir alcances para tu app.

Si deseas obtener una lista de los alcances disponibles, consulta Alcances de OAuth 2.0 para las API de Google.

Tipos de autenticación requerida

Existen dos formas de autenticar y autorizar con las API de Chat las credenciales del usuario o las cuentas de servicio de la API de Chat.

Con la autorización de credenciales del usuario, una app de Chat puede acceder a datos específicos del usuario y completar acciones específicas en su nombre. Los datos y las acciones autorizados se especifican por permisos.

Con la autorización de la cuenta de servicio, una app de Chat accede a la API como una app mediante las credenciales de la cuenta de servicio.

Si eres un administrador de dominio, puedes otorgar la delegación de autoridad de todo el dominio para autorizar que la cuenta de servicio de una aplicación acceda a los datos de tus usuarios sin requerir que cada usuario otorgue su consentimiento. Después de configurar la delegación de todo el dominio, puedes hacer llamadas a la API con la cuenta de servicio para robar la identidad de una cuenta de usuario. Aunque una cuenta de servicio se usa para la autenticación, la delegación de todo el dominio roba la identidad de un usuario y, por lo tanto, se considera autenticación de usuario. Puedes usar la delegación de todo el dominio para cualquier funcionalidad que requiera autenticación del usuario.

En la siguiente tabla, se enumeran las situaciones comunes con las que se encuentran las apps de chat, si requieren autenticación y, de ser así, el tipo:

Situación No se requiere autenticación Compatible con autenticación de usuario Cuenta de servicio admitida
Recibir mensajes de:
Eventos de chat
Devoluciones de llamada de Apps Script
Google Cloud Pub/Sub
Responde mensajes:
De forma síncrona, a través de un evento de Chat
De forma síncrona, a través de un valor de devolución de llamada de devolución de llamada de Apps Script
De forma asíncrona, a través de la API de REST de Chat
Enviar mensajes nuevos:
Con webhooks entrantes
Con la API de REST de Chat
Crea un espacio de Chat:
Con la API de REST de Chat
Agrega usuarios y apps a un espacio de Chat:
Con la API de REST de Chat

Próximo paso

Configura la autenticación y la autorización con credenciales de usuarios o una cuenta de servicio.