Autenticar e autorizar apps do Chat e solicitações da API Google Chat

Autenticação e autorização são mecanismos usados para verificar a identidade e o acesso aos recursos, respectivamente. Neste documento, descrevemos como a autenticação e a autorização funcionam para apps do Chat e solicitações da API Chat.

Visão geral do processo

O diagrama a seguir mostra as etapas de alto nível de autenticação e autorização do Google Chat:

Etapas avançadas para autenticação e autorização do Google Chat
Figura 1. Etapas avançadas para autenticação e autorização do Google Chat.

  1. Configure um projeto do Google Cloud, ative a API Chat e configure o app do Chat: durante o desenvolvimento, você cria um projeto do Google Cloud. No projeto do Google Cloud, ative a API Chat, configure o app do Chat e configure a autenticação. Para mais informações, consulte Desenvolver no Google Workspace e Criar um app do Chat.

  2. Chamar a API Chat:quando o app chama a API Chat, ele envia credenciais de autenticação para a API Chat. Se o app for autenticado com uma conta de serviço, as credenciais serão enviadas como parte do código do app. Se o app exigir a chamada da API Chat usando a autenticação de um usuário que ainda não foi concedida, ele solicitará que o usuário faça login.

  3. Solicitar recursos: seu app solicita acesso com escopos especificados ao configurar a autenticação.

  4. Pedir consentimento:se o app estiver sendo autenticado como um usuário, o Google exibirá uma tela de permissão OAuth para que o usuário possa decidir se quer conceder ao app acesso aos dados solicitados. A autenticação com uma conta de serviço não requer o consentimento do usuário.

  5. Enviar solicitação aprovada de recursos:quando o usuário consente com os escopos de autorização, o app agrupa as credenciais e os escopos aprovados pelo usuário em uma solicitação. A solicitação é enviada ao servidor de autorização do Google para receber um token de acesso.

  6. O Google retorna um token de acesso: o token de acesso contém uma lista de escopos concedidos. Se a lista retornada de escopos for mais restritiva que os escopos solicitados, o app desativará todos os recursos limitados pelo token.

  7. Acesso a recursos solicitados:seu app usa o token de acesso do Google para invocar a API Chat e acessar os recursos dela.

  8. Receber um token de atualização (opcional): se o app precisar acessar a API Google Chat após o ciclo de vida de um único token de acesso, ele poderá receber um token de atualização. Para mais informações, consulte Usar o OAuth 2.0 para acessar as APIs do Google.

  9. Solicitar mais recursos:se o app precisar de mais acesso, ele vai solicitar que o usuário conceda novos escopos, resultando em uma nova solicitação para receber um token de acesso (etapas 3 a 6).

Quando os apps de chat exigem autenticação

Os apps de chat podem enviar mensagens em resposta a uma interação do usuário ou de forma assíncrona. Eles também podem concluir tarefas em nome de um usuário, como criar um espaço do Chat ou acessar uma lista de pessoas em um espaço do Chat.

Os apps de chat não exigem autenticação para responder a uma interação do usuário, a menos que o app do Chat chame a API Chat ou outra API do Google durante o processamento de uma resposta.

Para enviar mensagens assíncronas ou realizar tarefas em nome de um usuário, os apps do Chat fazem solicitações RESTful para a API Chat, que exigem autenticação e autorização.

Respostas a interações do usuário não exigem autenticação

Os apps do Google Chat não precisam ser autenticados como usuário ou app do Chat para receber e responder de maneira síncrona a eventos de interação.

Os apps do Google Chat recebem eventos de interação sempre que um usuário interage ou invoca um app do Chat, incluindo:

  • Um usuário envia uma mensagem para um app do Chat.
  • Um usuário @menciona um app do Chat.
  • Um usuário invoca um dos comandos de barra do app do Chat.

O diagrama a seguir mostra uma sequência de solicitação e resposta entre um usuário do Chat e um app do Chat:

Nenhuma autorização é necessária para eventos de interação no app do Chat
Figura 2.Os eventos de interação no app do Chat não exigem autenticação.

  1. O usuário envia uma mensagem para o app do Chat no Google Chat.
  2. O Google Chat encaminha a mensagem para o app.
  3. O app recebe a mensagem, processa e retorna uma resposta ao Google Chat.
  4. O Google Chat renderiza a resposta para o usuário ou em um espaço.

Essa sequência é repetida para cada evento de interação no app do Chat.

As mensagens assíncronas exigem autenticação

As mensagens assíncronas ocorrem quando um app do Chat faz uma solicitação à API Chat, que requer autenticação e autorização.

Ao chamar a API Chat, os apps do Chat podem postar mensagens no Google Chat ou concluir tarefas e acessar dados em nome de um usuário. Por exemplo, após a detecção de uma interrupção do servidor, um app do Chat pode chamar a API Chat para:

  • Crie um espaço do Chat dedicado a investigar e corrigir a falha temporária.
  • Adicionar participantes ao espaço do Chat
  • Poste uma mensagem no espaço do Chat com detalhes sobre a interrupção.

O diagrama a seguir mostra uma sequência de mensagens assíncronas entre um app do Chat e um espaço do Chat:

Autenticação necessária para mensagens assíncronas
Figura 3. As mensagens assíncronas exigem autenticação.

  1. Um app do Chat cria uma mensagem chamando a API Chat usando o método spaces.messages.create e inclui credenciais de usuário na solicitação HTTP.
  2. O Google Chat autentica o app do Chat com credenciais de conta de serviço ou usuário.
  3. O Google Chat renderiza a mensagem do app em um espaço especificado do Chat.

Escopos da API Chat

Configure a tela de permissão OAuth e escolha escopos para definir quais informações são mostradas aos usuários e revisores de apps e registre seu app para poder publicá-lo depois.

Para definir o nível de acesso concedido ao app, é necessário identificar e declarar escopos de autorização. Um escopo de autorização é uma string de URI do OAuth 2.0 que contém o nome do app do Google Workspace, os tipos de dados que ele acessa e o nível de acesso.

Escopos não confidenciais

Código do escopo Descrição
https://www.googleapis.com/auth/chat.bot

O escopo chat.bot só oferece suporte a contas de serviço. Não é possível autenticar com credenciais de usuário ou com delegação em todo o domínio usando esse escopo.

Permite que os apps de chat acessem chats e enviem mensagens. Concede acesso a todos os recursos disponíveis para apps de chat.

Escopos confidenciais

Código do escopo Descrição
https://www.googleapis.com/auth/chat.spaces Crie conversas e espaços e confira ou atualize metadados (incluindo as configurações do histórico) no Chat.
https://www.googleapis.com/auth/chat.spaces.create Criar novas conversas no Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Conferir o chat e os espaços no Chat.
https://www.googleapis.com/auth/chat.memberships Acessar, adicionar e remover participantes de conversas no Chat.
https://www.googleapis.com/auth/chat.memberships.app Adicionar e remover o app das conversas no Google Chat
https://www.googleapis.com/auth/chat.memberships.readonly Conferir os participantes nas conversas do Chat.
https://www.googleapis.com/auth/chat.messages.create Escrever e enviar mensagens no Chat.
https://www.googleapis.com/auth/chat.messages.reactions Confira, adicione e exclua as reações às mensagens no Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Adicione reações a uma mensagem no Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Confira as reações a uma mensagem no Chat.
https://www.googleapis.com/auth/chat.users.readstate Conferir e modificar o horário da última leitura de conversas do Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Conferir o horário da leitura mais recente das conversas do Chat.

Escopos restritos

Código do escopo Descrição
https://www.googleapis.com/auth/chat.delete Exclua conversas e espaços e remova o acesso a arquivos associados no Chat.
https://www.googleapis.com/auth/chat.import Importar espaços, mensagens e assinaturas para o Chat. Para mais informações, consulte Autorizar apps do Chat a importar dados
https://www.googleapis.com/auth/chat.messages Você pode acessar, escrever, enviar, atualizar e excluir mensagens, além de adicionar, visualizar e excluir reações a elas.
https://www.googleapis.com/auth/chat.messages.readonly Confira mensagens e reações no Chat.

Os escopos nas tabelas anteriores indicam a confidencialidade deles, de acordo com as definições a seguir:

Se o app exigir acesso a outras APIs do Google, você também pode adicionar esses escopos. Para mais informações sobre os escopos da API do Google, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Para saber mais sobre os escopos das APIs do Google Workspace, consulte Configurar a tela de permissão OAuth e escolher escopos.

Tipos de autenticação obrigatória

Há duas maneiras de os apps do Chat se autenticarem e autorizarem com a API Chat: credenciais de usuário ou contas de serviço.

Com a autorização de credencial, um app do Chat pode acessar os dados do usuário e concluir ações em nome dele. Os escopos OAuth especificam os dados e as ações autorizadas. No entanto, esses apps do Chat não podem ser publicados publicamente. Para mais informações, consulte Publicar apps do Google Chat.

Com a autorização, um app do Chat acessa a API como um app usando credenciais de conta de serviço. A autorização de apps sempre usa o escopo de autorização chat.bot.

Se você é um administrador de domínio, pode conceder a delegação de autoridade em todo o domínio para autorizar a conta de serviço de um aplicativo a acessar os dados dos seus usuários sem exigir o consentimento de cada um. Depois de configurar a delegação em todo o domínio, faça chamadas de API usando sua conta de serviço para representar uma conta de usuário. Embora uma conta de serviço seja usada para autenticação, a delegação em todo o domínio se passa por um usuário e, portanto, é considerada uma autenticação de usuário. Qualquer funcionalidade que exija autenticação do usuário pode usar a delegação em todo o domínio.

Ao decidir que tipo de credencial usar para uma solicitação de API específica, lembre-se de que alguns métodos de API oferecem suporte apenas a um tipo específico de credencial. Se um método de API oferecer suporte às duas credenciais, o tipo de credencial usado na chamada afetará o resultado retornado:

  • Com a autorização do app, os métodos retornam apenas os recursos que o app pode acessar.
  • Com a autorização do usuário, os métodos retornam apenas recursos que o usuário pode acessar na interface do Chat.

Por exemplo, chamar o método ListSpaces com autorização do app retorna a lista de espaços de que o app faz parte. Chamar ListSpaces com autorização do usuário retorna a lista de espaços de que o usuário participa. Na prática, seu app pode usar os dois tipos de autorização ao chamar a API Chat, dependendo da funcionalidade que você quer.

Para chamadas assíncronas da API Chat

A tabela a seguir lista os métodos da API Chat e os escopos de autorização compatíveis:

Método Autenticação de usuário compatível Autenticação de app compatível Escopos de autorização compatíveis
Espaços  
Criar um espaço Com a autenticação de usuários:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Configurar um espaço Com a autenticação de usuários:
  • chat.spaces.create
  • chat.spaces
Comprar um espaço Com a autenticação de usuários:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de apps:
  • chat.bot
Listar espaços Com a autenticação de usuários:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de apps:
  • chat.bot
Atualizar um espaço Com a autenticação de usuários:
  • chat.spaces
  • chat.import
Excluir um espaço Com a autenticação de usuários:
  • chat.delete
  • chat.import
Concluir o processo de importação de um espaço Com a autenticação de usuários:
  • chat.import
Encontrar uma mensagem direta Com a autenticação de usuários:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de apps:
  • chat.bot
Membros  
Criar um participante Com a autenticação de usuários:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Assinar um membro Com a autenticação de usuários:
  • chat.memberships.readonly
  • chat.memberships
Com a autenticação de apps:
  • chat.bot
Listar participantes Com a autenticação de usuários:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Com a autenticação de apps:
  • chat.bot
Excluir um participante Com a autenticação de usuários:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Mensagens  
Criar uma mensagem Com a autenticação de usuários:
  • chat.messages.create
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Receber uma mensagem Com a autenticação de usuários:
  • chat.messages.readonly
  • chat.messages
Com a autenticação de apps:
  • chat.bot
Listar mensagens Com a autenticação de usuários:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Atualizar uma mensagem Com a autenticação de usuários:
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Excluir uma mensagem Com a autenticação de usuários:
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Reações  
Criar uma reação Com a autenticação de usuários:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Listar reações Com a autenticação de usuários:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Excluir uma reação Com a autenticação de usuários:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Mídia e anexos  
Fazer upload de mídia como um arquivo anexado Com a autenticação de usuários:
  • chat.messages.create
  • chat.messages
  • chat.import
Fazer o download de mídia Com a autenticação de usuários:
  • chat.messages.readonly
  • chat.messages
Com a autenticação de apps:
  • chat.bot
Gerar um anexo de mensagem Com a autenticação de apps:
  • chat.bot
Estados de leitura do usuário
Acessar o estado de leitura do espaço de um usuário Com a autenticação de usuários:
  • chat.users.readstate
  • chat.users.readstate.readonly
Atualizar o estado de leitura do espaço de um usuário Com a autenticação de usuários:
  • chat.users.readstate
Ver o estado de leitura da conversa de um usuário Com a autenticação de usuários:
  • chat.users.readstate
  • chat.users.readstate.readonly

Para eventos de interação no app do Chat

A tabela a seguir lista as formas comuns de interação dos usuários com os apps do Chat e se a autenticação é obrigatória ou compatível:

Cenário Nenhuma autenticação necessária Autenticação de usuário compatível Autenticação de app compatível
Receber mensagens de:
Eventos de interação com o app do Chat
Callbacks do Apps Script
Google Cloud Pub/Sub
Para responder a mensagens:
De forma síncrona, usando um evento de interação no app do Chat
De forma síncrona, usando um valor de retorno de callback do Apps Script
Enviar novas mensagens:
Com Webhooks de entrada