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 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:
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, habilitas la API de Chat, configuras la app de Chat y configuras la autenticación. Para obtener más información, consulta Desarrolla en Google Workspace y Compila una app de Chat.
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 la autenticación de un usuario que aún no se otorgó, se le solicita que acceda.
Solicita recursos: La app solicita acceso con los permisos que especificas cuando configuras la autenticación.
Solicitar consentimiento: Si tu app se autentica como usuario, Google muestra una pantalla de consentimiento de OAuth para que el usuario pueda decidir si otorgarle 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 da su consentimiento para los permisos de autorización, la app empaqueta 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.
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 los permisos solicitados, la app desactivará todas las funciones limitadas por el token.
Acceder 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.
Obtener 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 quieres obtener más información, consulta Usa OAuth 2.0 para acceder a las API de Google.
Solicita 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).
Cuándo 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 conseguir 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.
Las apps de Google Chat no necesitan autenticarse como usuario ni como app de Chat para recibir y responder de forma síncrona a 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 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:
- 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 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 hacer lo siguiente:
- Crea 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 brindar detalles sobre la interrupción.
En el siguiente diagrama, se muestra una secuencia de mensajes asíncrona entre una app de Chat y un espacio de Chat:
- Una app de Chat crea un mensaje llamando a la API de Chat con el método
spaces.messages.create
y, luego, incluye las credenciales de 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
Configura la pantalla de consentimiento de OAuth y elige los alcances para definir la información que se muestra a los usuarios y revisores de la app, 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 permiso | Descripción |
---|---|
https://www.googleapis.com/auth/chat.bot
|
El permiso Permite que las apps de Chat vean chats y envíen mensajes. Otorga acceso a todas las funciones disponibles para las apps de Chat. |
Permisos sensibles
Código de permiso | Descripción |
---|---|
https://www.googleapis.com/auth/chat.spaces
|
Crear conversaciones y espacios, y ver o actualizar los 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
|
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 abandonarlas |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Ver los miembros en 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
|
Consulta, agrega y borra reacciones a los mensajes en Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Agrega reacciones a un mensaje en Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Vea las reacciones a un mensaje en Chat. |
https://www.googleapis.com/auth/chat.users.readstate
|
Ver y modificar 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. |
Permisos restringidos
Código de 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
|
Importa espacios, mensajes y membresías a Chat. Para obtener más información, consulta Autoriza apps de Chat para 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
|
Consulta los mensajes y las reacciones en Chat. |
Los alcances de las tablas anteriores indican su sensibilidad, según las siguientes definiciones:
No sensibles: Estos alcances proporcionan la esfera más pequeña de acceso de autorización y solo requieren la verificación básica de la app. Para obtener información sobre este requisito, consulta Pasos de preparación para la verificación.
Sensibles: Estos permisos le brindan a tu app acceso a los datos de Google de un usuario específico después de recibir la autorización del usuario. Requiere que realices una verificación adicional de la app. Si deseas obtener información sobre este requisito, consulta Pasos para las apps que solicitan permisos sensibles.
Restringido: Estos permisos proporcionan un amplio acceso a los datos del usuario de Google y requieren que realices el proceso de verificación de permiso restringido. Para obtener información sobre este requisito, consulta Servicios de la API de Google: Política de datos del usuario y Requisitos adicionales para permisos específicos de API. Consulta también Pasos para las apps que solicitan alcances restringidos.
Si tu app requiere acceso a cualquier otra API de Google, también puedes agregar esos permisos. Si quieres obtener más información sobre los alcances de la API de Google, consulta Usa 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 obligatoria
Existen dos formas en las que las apps de Chat pueden autenticarse y autorizarse con la API de Chat: con credenciales de usuario o con 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.
Con la autorización de la app, una app de Chat accede a la API como una app con las credenciales de la cuenta de servicio. La autorización de la app siempre usa el alcance de autorización chat.bot
.
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 use en la llamada afectará el resultado que se muestre:
- Con la autorización de la app, los métodos solo devuelven 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 de los que la app es miembro. Si se llama a ListSpaces
con la autorización del usuario, se muestra la lista de espacios de los que es miembro el usuario. En la práctica, tu app podría usar ambos tipos de autorización cuando llame a la API de Chat, según la funcionalidad que desees.
Llamadas a la API de Chat asíncronas
En la siguiente tabla, se enumeran los métodos de la API de Chat y sus permisos de autorización admitidos:
Método | Compatibilidad con la autenticación de usuarios | Compatibilidad con la autenticación de apps | Permisos de autorización compatibles | |
---|---|---|---|---|
Espacios | ||||
Cómo crear un espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo configurar un espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Obtén un espacio |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Crea listas de espacios |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Actualiza un espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo borrar un espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo completar el proceso de importación de un espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo buscar un mensaje directo |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Miembros | ||||
Crea un miembro | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Obtén un miembro |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Cómo enumerar miembros |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Cómo borrar un miembro | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Mensajes | ||||
Crea un mensaje |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Recibe mensajes |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Cómo enumerar mensajes | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo actualizar un mensaje |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Cómo borrar un mensaje |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Reacciones | ||||
Cómo crear una reacción | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo enumerar reacciones | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo borrar una reacción | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Contenido multimedia y archivos adjuntos | ||||
Cómo subir contenido multimedia como un archivo adjunto | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo descargar contenido multimedia |
Con la autenticación de usuarios, ocurre lo siguiente:
|
|||
Cómo obtener un archivo adjunto de mensaje | — |
Con la autenticación de la app, haz lo siguiente:
|
||
Estados de lectura del usuario | ||||
Obtén el estado de lectura del espacio de un usuario | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Actualiza el estado de lectura del espacio de un usuario | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Cómo obtener el estado de lectura del subproceso de un usuario | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Eventos espaciales | ||||
Obtener eventos espaciales | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
||
Enumera los eventos de espacio | — |
Con la autenticación de usuarios, ocurre lo siguiente:
|
Para los eventos de interacción de 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 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: |
|
|||||||||||||||
Responde los 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 la 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.
- Para obtener más información sobre cómo las APIs de Google aprovechan OAuth 2.0, consulta Usa OAuth 2.0 para acceder a las APIs de Google.
- Configura la autenticación y la autorización con credenciales de usuario o una cuenta de servicio.