Autentica y autoriza apps de Chat y solicitudes a la API de Google Chat

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, creas un proyecto de Google Cloud. En el proyecto de Google Cloud, habilitarás la API de Chat y configurarás la app de Chat y la autenticación. Para obtener más información, consulta Desarrolla en Google Workspace y Compila una app de Chat.

  2. API de Call Chat: Cuando tu app llama a la API de Chat, 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 la app. Si tu app requiere llamar a la API de Chat con una autenticación de usuario que aún no se haya otorgado, se le pedirá que acceda.

  3. Solicita recursos: La app solicita acceso con los alcances que especificas cuando configuras la autenticación.

  4. Solicitar el consentimiento: Si la app se autentica como usuario, Google muestra 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 los recursos: Si el usuario da su consentimiento para los permisos de la autorización, tu app agrupa las credenciales y los permisos 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 permisos otorgados. Si la lista de permisos que se muestra es más restrictiva que la solicitada, tu app desactivará cualquier función que limite el token.

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

  8. Obtén un token de actualización (opcional): Si tu app debe 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. Si deseas obtener más información, consulta Usa OAuth 2.0 para acceder a las API de Google.

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

Cuando las apps de Chat requieren autenticación

Las apps de chat pueden enviar mensajes en respuesta a una interacción del usuario o de forma asíncrona. También pueden completar tareas en nombre de un usuario, como crear un espacio de Chat o obtener una lista de personas en un espacio de Chat.

Las apps de chat no requieren autenticación para responder a una interacción del usuario, a menos que la app de Chat llame a la API de Chat o a otra API de Google mientras procesa una respuesta.

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

Las respuestas a las interacciones de los usuarios no requieren autenticación

No es necesario que las apps de Google Chat se autentiquen como usuario o app de Chat para recibir y responder de forma síncrona a los eventos de interacción.

Las apps de Google Chat reciben eventos de interacción cada vez que un usuario interactúa o invoca una app de Chat, incluidos los siguientes:

  • Un usuario envía un mensaje a una app de Chat.
  • Un usuario menciona con @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 de solicitud-respuesta entre un usuario de Chat y una app de Chat:

No se requiere autorización para los eventos de interacción de apps de Chat
Figura 2: Los eventos de interacción de la app de Chat no requieren autenticación.

  1. El usuario envía un mensaje a la app de Chat en Google Chat.
  2. Google Chat reenviará 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 interacción de la app de Chat.

Los mensajes asíncronos requieren autenticación

Los mensajes asíncronos ocurren cuando una app de Chat realiza una solicitud a la API de Chat, que requiere autenticación y autorización.

Mediante una llamada a la API de Chat, 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
  • Agregar personas al espacio de Chat
  • Publica un mensaje en el espacio de Chat para brindar detalles sobre la interrupción.

En el siguiente diagrama, se muestra una secuencia de mensajes asíncronas entre una app 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 Chat mediante el método spaces.messages.create y, además, incluye las credenciales de usuario 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

Configura la pantalla de consentimiento de OAuth y elige los alcances para definir qué información se muestra a los usuarios y revisores de apps, y registra tu app para que puedas publicarla más tarde.

Para definir el nivel de acceso otorgado a tu app, debes identificar y declarar los permisos 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, el tipo de datos a los que accede y el nivel de acceso.

Permisos no sensibles

Código de alcance Descripción
https://www.googleapis.com/auth/chat.bot

El permiso chat.bot solo admite cuentas de servicio. No puedes autenticar con credenciales de usuario ni con delegación de todo el dominio mediante este permiso.

Permite que las apps de Chat vean los chats y envíen mensajes. Otorga acceso a todas las funciones disponibles para las apps de Chat.

Permisos sensibles

Código de alcance Descripción
https://www.googleapis.com/auth/chat.spaces Crear conversaciones y espacios, y visualizar o actualizar metadatos (incluida la configuración del historial) en Chat
https://www.googleapis.com/auth/chat.spaces.create Crear conversaciones nuevas en Chat
https://www.googleapis.com/auth/chat.spaces.readonly Ver el chat y los espacios en Chat
https://www.googleapis.com/auth/chat.memberships Puede ver, agregar y quitar miembros de las conversaciones en Chat.
https://www.googleapis.com/auth/chat.memberships.app Unirse a las conversaciones de Google Chat y salir de ellas
https://www.googleapis.com/auth/chat.memberships.readonly Ver a los miembros de las conversaciones de Chat
https://www.googleapis.com/auth/chat.messages.create Redacta y envía mensajes en Chat.
https://www.googleapis.com/auth/chat.messages.reactions Ver, agregar y borrar reacciones a los mensajes de Chat
https://www.googleapis.com/auth/chat.messages.reactions.create Agregar reacciones a un mensaje en Chat
https://www.googleapis.com/auth/chat.messages.reactions.readonly Consulta las reacciones a un mensaje en Chat.

Permisos restringidos

Código de alcance Descripción
https://www.googleapis.com/auth/chat.delete Borrar conversaciones y espacios, y quitar el acceso a los archivos asociados en Chat
https://www.googleapis.com/auth/chat.import Importa espacios, mensajes y membresías a Chat. Para obtener más información, consulta Autoriza a apps de Chat a importar datos.
https://www.googleapis.com/auth/chat.messages Puedes ver, redactar, enviar, actualizar y borrar mensajes, así como agregar, ver y borrar reacciones a los mensajes.
https://www.googleapis.com/auth/chat.messages.readonly Vea los mensajes y las reacciones en Chat.

Los alcances de las tablas anteriores indican su sensibilidad, según las siguientes definiciones:

Si tu app requiere acceso a cualquier otra API de Google, también puedes agregar esos permisos. Si deseas obtener más información sobre los alcances de la API de Google, consulta Uso de OAuth 2.0 para acceder a las API de Google.

Para obtener más información sobre los permisos de las APIs de Google Workspace, consulta Configura la pantalla de consentimiento de OAuth y elige los permisos.

Tipos de autenticación requerida

Existen dos formas en las que las apps de Chat pueden autenticarse y autorizarse con la API de Chat: credenciales de usuario o cuentas de servicio.

Con la autorización de credenciales de usuario, una app de Chat puede acceder a los datos del usuario y completar acciones en su nombre. Los permisos de OAuth especifican las acciones y los datos autorizados. Sin embargo, estas apps de chat no se pueden publicar de forma pública. Para obtener más información, consulta Publica apps de Google Chat.

Con la autorización de la app, una app de Chat accede a la API como una app que usa credenciales de cuenta de servicio. La autorización de la app siempre usa el alcance de autorización chat.bot.

Si eres un administrador de dominio, puedes otorgar 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 necesidad de que cada uno de ellos den su consentimiento. Después de configurar la delegación de todo el dominio, puedes realizar llamadas a la API con tu cuenta de servicio para actuar en nombre de una cuenta de usuario. Aunque se usa una cuenta de servicio para la autenticación, la delegación de todo el dominio suplanta la identidad de un usuario y, por lo tanto, se considera autenticación de usuario. Cualquier funcionalidad que requiera autenticación del usuario puede usar la delegación de todo el dominio.

Cuando decidas qué tipo de credencial usar para una solicitud a la API en particular, ten en cuenta que algunos métodos de la API solo admiten un tipo particular de credencial. Si un método de API admite ambas credenciales, el tipo de credencial que se usa en la llamada afecta el resultado que se muestra:

  • Con la autorización de la app, los métodos solo muestran recursos a los que la app puede acceder.
  • Con la autorización del usuario, los métodos solo muestran recursos a los que el usuario puede acceder en la IU de Chat.

Por ejemplo, si se llama al método ListSpaces con la autorización de la app, se muestra la lista de espacios a los que pertenece la app. Llamar a ListSpaces con autorización del usuario muestra la lista de espacios de los que es miembro el usuario. En la práctica, tu app puede usar ambos tipos de autorización cuando llame a la API de Chat, según la funcionalidad que desees.

Para llamadas asíncronas a la API de Chat

En la siguiente tabla, se enumeran los métodos de la API de Chat y sus alcances de autorización admitidos:

Método Compatibilidad con la autenticación de usuarios Compatibilidad con la autenticación de apps Permisos de autorización admitidos
Espacios  
Cómo crear un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Cómo configurar un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces.create
  • chat.spaces
Consigue un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Cómo enumerar espacios Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Actualiza un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces
  • chat.import
Cómo borrar un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.delete
  • chat.import
Completa el proceso de importación de un espacio Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.import
Cómo buscar un mensaje directo Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Miembros  
Crea un miembro Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Obtén un miembro Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.memberships.readonly
  • chat.memberships
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Miembros de la lista Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Cómo borrar un miembro Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Mensajes  
Crea un mensaje Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.create
  • chat.messages
  • chat.import
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Recibe un mensaje Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.readonly
  • chat.messages
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Cómo enumerar mensajes Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Cómo actualizar un mensaje Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages
  • chat.import
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Cómo borrar un mensaje Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages
  • chat.import
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Reacciones  
Cómo crear una reacción Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Reacciones en lista Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Cómo borrar una reacción Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Contenido multimedia y archivos adjuntos  
Cómo subir contenido multimedia como un archivo adjunto Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.create
  • chat.messages
  • chat.import
Cómo descargar contenido multimedia Con la autenticación de usuarios, ocurre lo siguiente:
  • chat.messages.readonly
  • chat.messages
Con la autenticación de apps, haz lo siguiente:
  • chat.bot
Cómo obtener un archivo adjunto en un mensaje Con la autenticación de apps:
  • chat.bot

Para eventos de interacción con apps de Chat

En la siguiente tabla, se enumeran las formas comunes en que los usuarios interactúan con las apps de Chat y si se requiere o se admite la autenticación:

Situación No se requiere autenticación Compatibilidad con la autenticación de usuarios Compatibilidad con la autenticación de apps
Recibir mensajes de:
Eventos de interacción de la app de Chat
Devoluciones de llamada de Apps Script
Google Cloud Pub/Sub
Responde mensajes:
De forma síncrona, mediante un evento de interacción de la app de Chat
De manera síncrona, con un valor de retorno de devolución de llamada de Apps Script
Enviar mensajes nuevos:
Con webhooks entrantes