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 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 alto nivel de autenticación y autorización para Google Chat:
Configura un proyecto de Google Cloud, habilita la API de Chat y configura tu app de Chat: durante el desarrollo, crea un proyecto de Google Cloud. En el proyecto de Google Cloud, debes habilitar la API de Chat, configurar 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.
API de Llamada de Chat: Cuando tu app llama a la API de Chat, envía 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 la autenticación de un usuario que todavía no se otorgó, se le solicitará que acceda.
Solicitar recursos: Tu app solicita acceso con los alcances que especificas mientras configuras la autenticación.
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 tu app acceso a los datos solicitados. La autenticación con una cuenta de servicio no requiere el consentimiento del usuario.
Envía una solicitud aprobada para los recursos: Si el usuario otorga su consentimiento para los permisos 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.
Google muestra un token de acceso: El token de acceso contiene una lista de alcances otorgados. Si la lista de permisos que se muestra es más restrictiva que los permisos solicitados, la app desactivará cualquier función que el token limite.
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.
Obtén un token de actualización (opcional): Si la 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.
Solicitar más recursos: Si tu app necesita más acceso, le pide al usuario que otorgue permisos nuevos, lo que resulta en una solicitud nueva 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 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 apps de chat realizan solicitudes RESTful a la API 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-respuesta entre un usuario de Chat y una app de Chat:
- El usuario envía un mensaje a la app de Chat en Google Chat.
- Google Chat reenviará el mensaje a la app.
- La app recibe el mensaje, lo procesa y muestra una respuesta a Google Chat.
- 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 envía una solicitud a la API de Chat, que requiere autenticación y autorización.
Si se llama a la API de Chat, las apps de Chat pueden publicar mensajes en Google Chat o completar tareas y acceder a los 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
- 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íncronos entre una app de chat y un espacio de Chat:
- Una app de chat crea un mensaje mediante una llamada a la API de Chat con
spaces.messages.create methody, además, incluye las credenciales del usuario en la solicitud HTTP. - Google Chat autentica la app de Chat con una cuenta de servicio o credenciales de usuario.
- 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 la app, debes identificar y declarar los permisos 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 permisos:
| 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. Otorga acceso a todas las funciones disponibles para las apps de Chat. |
https://www.googleapis.com/auth/chat.delete
|
Borra las conversaciones y los 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 app de Chat se agregue a una conversación y se quite de ella (pero no de otras apps) de Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Obtener detalles sobre una membresía y enumerar las membresías en un espacio |
| 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.create
|
Crear mensajes y subir archivos adjuntos en Google Chat |
https://www.googleapis.com/auth/chat.messages.reactions
|
Ver, agregar y borrar reacciones a los mensajes de Google Chat |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Agregar reacciones a los mensajes de Google Chat |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Vea reacciones a mensajes de Google Chat. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Obtenga y enumere 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
|
Crear conversaciones en Google Chat |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Consulta el chat y los espacios en Google Chat. |
Si quieres obtener más información sobre los permisos para las API de Google Workspace, consulta Cómo elegir los permisos de tu app.
Si deseas ver una lista de los alcances disponibles, consulta Alcances de OAuth 2.0 para las API de Google.
Tipos de autenticación obligatoria
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 app de chat puede acceder a los datos del usuario y completar acciones en su nombre. Los permisos de OAuth especifican los datos y las acciones 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 apps, una app de chat accede a la API como una app mediante las credenciales de la cuenta de servicio. La autorización de la app siempre usa el permiso de autorización chat.bot.
Si eres 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 requerir que cada uno otorgue su consentimiento. Después de configurar la delegación de todo el dominio, puedes realizar llamadas a la API con la cuenta de servicio para actuar en nombre de una cuenta de usuario. Aunque una cuenta de servicio se usa para la autenticación, la delegación de todo el dominio actúa en nombre de un usuario y, por lo tanto, se la considera autenticación de usuario. Cualquier funcionalidad que requiera la 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 credenciales. Si un método de la API admite ambas credenciales, el tipo de credencial que se usó 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 puede acceder la app.
- 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 llamas al método ListSpaces con la autorización de la app, se muestra la lista de espacios de los que forma parte la app. Si llamas a ListSpaces con la autorización del usuario, se muestra la lista de espacios de los que forma parte el usuario. En la práctica, tu app puede usar ambos tipos de autorización cuando llama a la API de Chat, según la funcionalidad que desees.
Para llamadas asíncronas de la API de Chat
En la siguiente tabla, se enumeran los métodos de la API de Chat y sus permisos de autorización admitidos:
| Método | Se admite la autenticación de usuarios | Se admite la autenticación de apps | Alcances de autorización admitidos | |
|---|---|---|---|---|
| Espacios | ||||
| Cómo crear un espacio | — |
|
||
| Configura un espacio | — |
|
||
| Obtener un espacio |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Enumera los espacios |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo actualizar un espacio | — |
|
||
| Cómo borrar un espacio | — |
|
||
| Cómo buscar un mensaje directo |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Miembros | ||||
| Cómo crear un miembro | — |
|
||
| Obtener un miembro |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Miembros de la lista |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo borrar un miembro | — |
|
||
| Mensajes | ||||
| Cómo crear un mensaje |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo recibir un mensaje |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo enumerar mensajes | — |
|
||
| Cómo actualizar un mensaje |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo borrar un mensaje |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Reacciones | ||||
| Cómo crear una reacción | — |
|
||
| Enumera reacciones | — |
|
||
| Cómo borrar una reacción | — |
|
||
| Contenido multimedia y archivos adjuntos | ||||
| Cómo subir contenido multimedia como un archivo adjunto | — |
|
||
| Descargar contenido multimedia |
Con la autenticación de usuarios, puedes hacer lo siguiente:
|
|||
| Cómo obtener un archivo adjunto de un mensaje | — |
|
||
Para recibir interacciones del usuario y responderlas de manera síncrona
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 no la autenticación:
| Situación | No se requiere autenticación | Se admite la autenticación de usuarios | Se admite la autenticación de apps | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Recibir mensajes de: |
|
|||||||||||||||
| Responde mensajes: |
|
|||||||||||||||
| Enviar mensajes nuevos: |
|
|||||||||||||||
Temas relacionados
- Para obtener una descripción general de la autenticación y la autorización en Google Workspace, consulta Más información sobre la autenticación y la autorización.
- Para obtener una descripción general de la autenticación y autorización en Google Cloud, consulta Descripción general de la autenticación.
- Para obtener más información sobre las cuentas de servicio, consulta Cuentas de servicio.
- Si quieres obtener más información sobre cómo las API de Google aprovechan OAuth 2.0, consulta Usa OAuth 2.0 para acceder a las API de Google.
- Configura la autenticación y autorización con credenciales de usuarios o una cuenta de servicio.