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

La autenticación y 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 la autenticación y trabajo de autorización para apps de Chat y solicitudes a la API de Chat.

Descripción general del proceso

En el siguiente diagrama, se muestran los pasos de alto nivel de la 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 una proyecto de Google Cloud. En el proyecto de Google Cloud, habilitas la API de Chat, configura tu app de Chat y configura la autenticación. Para obtener más información, consulta Desarrollo en Google Workspace y Compila una app de Chat.

  2. Call Chat API: Cuando tu app llama a Chat, envía credenciales de autenticación al 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 aplicación. Si tu app requiere llamar a la API de Chat usando la autenticación de un usuario que aún no se ha otorgado, usuario acceda.

  3. Solicita recursos: Tu app solicita acceso con permisos que especificas cuando configuras la autenticación.

  4. Solicita el consentimiento: Si tu app se autentica como usuario, Google muestra una pantalla de consentimiento de OAuth para que el usuario decida si le otorga a tu app acceso a los datos solicitados. La autenticación con una cuenta de servicio requerir el consentimiento del usuario.

  5. Enviar una solicitud aprobada de recursos: Si el usuario da su consentimiento permisos de autorización, tu app empaqueta las credenciales y las credenciales permisos 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 permisos solicitados, tu app desactivará las funciones limitadas por el token.

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

  8. Obtener un token de actualización (opcional): Si la aplicación debe acceder al 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. Para obtener más información, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

  9. Solicitar más recursos: Si tu app necesita más acceso, le pide al usuario que lo haga. para otorgar permisos nuevos, lo que da como resultado 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 en respuesta a una interacción del usuario. de forma asíncrona. También pueden realizar tareas en nombre de un usuario, como crear un espacio de Chat o conseguir una lista de las personas de un Espacio de Chat

Las apps de chat no requieren autenticación para responder un interacción del usuario, salvo que la aplicación de Chat llame al API de Chat o alguna otra API de Google procesar una respuesta.

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

Las respuestas a las interacciones del usuario no requieren autenticación

Las apps de Google Chat no necesitan autenticarse de chat para recibir y responder de forma síncrona eventos de interacción.

Las apps de Google Chat reciben eventos de interacción cuando un usuario interactúa o Invoca una app de Chat, que incluye lo siguiente:

  • Un usuario envía un mensaje a una app de Chat.
  • Un usuario @menciona una app de Chat.
  • Un usuario invoca uno de los servicios comandos de barra.

En el siguiente diagrama, se muestra una secuencia de solicitud-respuesta entre Usuario de Chat y app de Chat:

No se requiere autorización para los eventos de interacción con la app de Chat
Figura 2: Los eventos de interacción con 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 reenvía el mensaje a la app.
  3. La app recibe el mensaje, lo procesa y devuelve una respuesta a Google Chat.
  4. Google Chat renderiza la respuesta para el usuario o en un espacio.

Esta secuencia se repite para cada interacción con la app de Chat para cada evento.

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, lo que requiere autenticación y autorización.

Cuando se llama a la API de Chat, las apps de Chat pueden publicar mensajes a Google Chat o completar tareas y acceder a los datos en nombre de un usuario. Para ejemplo, luego de detectar una interrupción del servidor, una app de Chat puede llamar al API de Chat para:

  • Crea un espacio de Chat dedicado a investigar y solucionar los problemas y la interrupción de servicios.
  • Agregar personas al espacio de Chat
  • Publica un mensaje en el espacio de Chat para brindar detalles sobre el y la interrupción de servicios.

El siguiente diagrama muestra una secuencia de mensajes asíncrona 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 llamando al Chat con la API de spaces.messages.create método, y, además, incluye las credenciales del usuario en la solicitud HTTP.
  2. Google Chat autentica la app de Chat con cuenta de servicio o credenciales de usuario.
  3. Google Chat procesa el mensaje de la app en un Chat especificado espacio.

Permisos de la API de Chat

Cómo configurar la pantalla de consentimiento de OAuth y elegir los permisos para definir qué información se mostrará a los usuarios y revisores de apps, y registrarte tu aplicación para poder publicarla más tarde.

Para definir el nivel de acceso otorgado a tu app, debes identificar y declarar permisos de autorización Un alcance de autorización es un URI de OAuth 2.0 de Google Workspace que contiene el nombre de la app, los accesos y el nivel de acceso.

Alcances no sensibles

Código del permiso Descripción
https://www.googleapis.com/auth/chat.bot

El permiso chat.bot solo admite cuentas de servicio. Tú no pueden autenticarse con credenciales de usuario ni con delegación de todo el dominio al usar este alcance.

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

Permisos sensibles

Código del permiso Descripción
https://www.googleapis.com/auth/chat.spaces Crear conversaciones y espacios, y ver o editar los metadatos (incluidos los del historial y de acceso) en Chat.
https://www.googleapis.com/auth/chat.spaces.create Crea 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 Ve, agrega, actualiza y quita 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 Redactar y enviar 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 Ver las reacciones a un mensaje en Chat
https://www.googleapis.com/auth/chat.users.readstate Consulta y modifica la hora de la última lectura en las conversaciones de Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Consulta la hora de la última lectura en las conversaciones de Chat.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Ver el chat y los espacios que pertenecen al dominio del administrador en Chat
https://www.googleapis.com/auth/chat.admin.spaces Ver o editar el chat y los espacios que pertenecen al dominio del administrador en Chat
https://www.googleapis.com/auth/chat.admin.memberships.readonly Ver miembros y administradores en conversaciones que pertenecen al dominio del administrador en Chat
https://www.googleapis.com/auth/chat.admin.memberships Ver, agregar, actualizar y quitar miembros y administradores en las conversaciones que pertenecen al dominio del administrador en Chat

Permisos restringidos

Código del permiso 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 Importar espacios, mensajes y membresías a Chat Para más información, consulta Autoriza a apps de Chat para importar datos
https://www.googleapis.com/auth/chat.messages Ver, redactar, enviar, actualizar y borrar mensajes, y agregar, ver y eliminar reacciones a los mensajes.
https://www.googleapis.com/auth/chat.messages.readonly Ver mensajes y reacciones en Chat
https://www.googleapis.com/auth/chat.admin.delete Borrar conversaciones y espacios que pertenecen al dominio del administrador, y quitar el acceso a los archivos asociados en Chat.

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

Si tu app requiere acceso a otras APIs de Google, puedes agregar esos permisos a tus conjuntos de datos. Para obtener más información sobre los alcances de la API de Google, consulta Cómo usar OAuth 2.0 para Accede a las APIs 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

Hay dos formas en que las apps de Chat pueden autenticarse y autorizar 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 datos del usuario y realizar acciones en nombre de un usuario. Los permisos de OAuth especifican los datos y las acciones autorizados.

Con la autorización de apps, una app de Chat accede la API como una app con credenciales de cuenta de servicio. Autorización de la app siempre usa el permiso de autorización chat.bot.

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

  • Con la autorización de apps, los métodos solo devuelven recursos que la app puede el acceso a los datos.
  • Con la autorización del usuario, los métodos solo devuelven recursos que el user a las que puedes acceder en la IU de Chat.

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

Para las llamadas asíncronas a la API de Chat

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

Método Compatible con la autenticación de usuarios Compatible con la autenticación de apps Se admiten los permisos de autorización
Espacios  
Crea un espacio Con la autenticación de usuarios:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Configura un espacio Con la autenticación de usuarios:
  • chat.spaces.create
  • chat.spaces
Obtén un espacio Con la autenticación de usuarios:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps:
  • chat.bot
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.spaces.readonly
Crea listas de espacios Con la autenticación de usuarios:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps:
  • chat.bot
Buscar espacios Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.spaces.readonly
Actualiza un espacio Con la autenticación de usuarios:
  • chat.spaces
  • chat.import
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.spaces
Cómo borrar un espacio Con la autenticación de usuarios:
  • chat.delete
  • chat.import
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.delete
Cómo completar el proceso de importación de un espacio Con la autenticación de usuarios:
  • chat.import
Cómo encontrar un mensaje directo Con la autenticación de usuarios:
  • chat.spaces.readonly
  • chat.spaces
Con la autenticación de apps:
  • chat.bot
Miembros  
Crea un miembro Con la autenticación de usuarios:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.memberships
Obtén un miembro Con la autenticación de usuarios:
  • chat.memberships.readonly
  • chat.memberships
Con la autenticación de apps:
  • chat.bot
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.memberships.readonly
Miembros de la lista Con la autenticación de usuarios:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Con la autenticación de apps:
  • chat.bot
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.memberships.readonly
Cómo borrar un miembro Con la autenticación de usuarios:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.memberships
Cómo actualizar un miembro Con la autenticación de usuarios:
  • chat.memberships
  • chat.import
Si usas la autenticación de usuarios con privilegios de administrador, ocurre lo siguiente:
  • chat.admin.memberships
Mensajes  
Crea un mensaje Con la autenticación de usuarios:
  • chat.messages.create
  • chat.messages
  • chat.import
Con la autenticación de apps:
  • chat.bot
Recibir un mensaje Con la autenticación de usuarios:
  • chat.messages.readonly
  • chat.messages
Con la autenticación de apps:
  • chat.bot
Cómo enumerar mensajes Con la autenticación de usuarios:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Actualiza un mensaje Con la autenticación de usuarios:
  • chat.messages
  • chat.import
Con la autenticación de apps:
  • chat.bot
Cómo borrar un mensaje Con la autenticación de usuarios:
  • chat.messages
  • chat.import
Con la autenticación de apps:
  • chat.bot
Reacciones  
Cómo crear una reacción Con la autenticación de usuarios:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Cómo enumerar reacciones Con la autenticación de usuarios:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Cómo borrar una reacción Con la autenticación de usuarios:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Contenido multimedia y archivos adjuntos  
Cómo subir contenido multimedia como archivo adjunto Con la autenticación de usuarios:
  • chat.messages.create
  • chat.messages
  • chat.import
Descarga contenido multimedia Con la autenticación de usuarios:
  • chat.messages.readonly
  • chat.messages
Con la autenticación de apps:
  • chat.bot
Cómo recibir un archivo adjunto de un mensaje Con la autenticación de apps:
  • chat.bot
Estados de lectura de los usuarios
Obtén el estado de lectura del espacio de un usuario Con la autenticación de usuarios:
  • chat.users.readstate
  • chat.users.readstate.readonly
Actualiza el estado de lectura del espacio de un usuario Con la autenticación de usuarios:
  • chat.users.readstate
Obtén el estado de lectura de subprocesos de un usuario Con la autenticación de usuarios:
  • chat.users.readstate
  • chat.users.readstate.readonly
Eventos espaciales
Obtener eventos del espacio Con la autenticación de usuarios, debes utilizar un alcance basado en el tipo de evento:
    .
  • En el caso de los eventos relacionados con los mensajes:
    • chat.messages
    • chat.messages.readonly
  • En el caso de los eventos sobre reacciones:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • En el caso de los eventos sobre las membresías, sigue estos pasos:
    • chat.memberships
    • chat.memberships.readonly
  • En el caso de eventos sobre el espacio:
    • chat.spaces
    • chat.spaces.readonly
Mostrar lista de eventos del espacio Con la autenticación de usuarios, debes usar un alcance para cada tipo de evento incluido en la solicitud:
    .
  • En el caso de los eventos relacionados con los mensajes:
    • chat.messages
    • chat.messages.readonly
  • En el caso de los eventos sobre reacciones:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • En el caso de los eventos sobre las membresías, sigue estos pasos:
    • chat.memberships
    • chat.memberships.readonly
  • En el caso de eventos sobre el espacio:
    • chat.spaces
    • chat.spaces.readonly

Eventos de interacción con la app 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 admite autenticación:

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