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 utilizan 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 aplicaciones de Chat y las solicitudes a la API de Chat.

Descripción general del proceso

En el siguiente diagrama, se muestran los pasos de autenticación y autorización de alto nivel 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. Configurar un proyecto de Google Cloud, habilitar la API de Chat y configurar 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 ocurrir después de que un usuario de Google Chat invoca la aplicación mediante un mensaje en la aplicación, hace clic en un botón de una tarjeta o emite 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 la 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 otorgarás acceso a los datos solicitados. La autenticación con una cuenta de servicio no requiere el consentimiento del usuario.

  5. Enviar solicitud aprobada para los recursos: Si el usuario da su consentimiento para los alcances de autorización, tu app agrupa en una solicitud las credenciales y los alcances aprobados por el usuario. 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á las funciones limitadas por el token.

  7. Acceso a los recursos solicitados: La 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. Obtén un token de actualización (opcional): Si tu app 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).

Cuando 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 los eventos de Chat. Las apps de Google Chat pueden recibir eventos y responder a ellos 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 aplicación de Chat en Google Chat.
  • Un usuario menciona una aplicación de Chat.
  • Un usuario invoca uno de los comandos de barra de la app de Chat.

En el siguiente diagrama, se muestra una secuencia básica de solicitud-respuesta síncrona 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 renderiza 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 realiza una solicitud a la API de REST de Chat, que requiere autenticación y autorización.

Al llamar a la API de REST, las aplicaciones 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 aplicación de chat puede llamar a la API de chat para realizar lo siguiente:

  • Crear un espacio de Chat dedicado a investigar y solucionar la interrupción
  • Agrega personas al espacio de Chat.
  • Publica 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íncronos básicos 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 REST de Chat con el método spaces.messages.create y, luego, 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 renderiza 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 permiso 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 de Google Chat.
https://www.googleapis.com/auth/chat.memberships.app Permite que la app de Chat se agregue a las conversaciones de Google Chat y las quite de ella (pero no de otras).
Mensajes  
https://www.googleapis.com/auth/chat.messages Crea, obtén, actualiza, borra y enumera mensajes en Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions Ver, agregar y borrar reacciones a mensajes en Google Chat
https://www.googleapis.com/auth/chat.messages.reactions.create Agregar reacciones a mensajes en Google Chat
https://www.googleapis.com/auth/chat.messages.reactions.readonly Permite ver las reacciones a los mensajes en Google Chat.
https://www.googleapis.com/auth/chat.messages.readonly Obtenga y enumere los mensajes en Google Chat.
Espacios  
https://www.googleapis.com/auth/chat.spaces Crea conversaciones y espacios, y visualiza o actualiza metadatos (incluida la configuración del historial) en Google Chat.
https://www.googleapis.com/auth/chat.spaces.create Crea 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.

Para 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 maneras de autenticar y autorizar apps de Chat con la API de Chat: credenciales de usuario o cuentas de servicio.

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

Con la autorización de la cuenta de servicio, una aplicación de Chat accede a la API como una aplicación con credenciales de cuenta de servicio o suplanta a un usuario mediante la delegación de todo el dominio.

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 Se admite la autenticación de usuarios Cuenta de servicio compatible
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 manera 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
Cómo usar la delegación de todo el dominio
Agrega usuarios y apps a un espacio de Chat:
Con la API de REST de Chat
Cómo usar la delegación de todo el dominio

Próximo paso

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