Autenticar e autorizar solicitações de API e apps do Chat

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

Visão geral do processo

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

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

  1. Configurar um projeto do Google Cloud, ativar a API Chat e o app de chat:durante o desenvolvimento, você cria um projeto do Google Cloud. No projeto do Google Cloud, ative a API Chat, configure o app Chat e a autenticação.

  2. Ligar para a API Chat:quando o app chama a API REST do Chat⁠, que geralmente acontece depois que um usuário do Google Chat o chama enviando uma mensagem, clicando em um botão em um card ou emitindo um comando de barra⁠, 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 fizer a autenticação como usuário, ele poderá receber uma solicitação de login.

  3. Solicitar recursos: seu app pede acesso com os escopos que você especifica ao configurar a autenticação.

  4. Solicitar consentimento:se o app estiver sendo autenticado como usuário, o Google exibirá uma tela de consentimento do OAuth para que o usuário decida se quer conceder acesso aos dados solicitados. A autenticação com uma conta de serviço não exige o consentimento do usuário.

  5. Enviar solicitação aprovada de recursos:se o usuário consentir com os escopos de autorização, o app vai agrupar 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 limitada que os escopos solicitados, o app vai desativar todos os recursos limitados pelo token.

  7. Acessar recursos solicitados: o 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 além do ciclo de vida de um único token de acesso, ele poderá receber um token de atualização.

  9. Solicitar mais recursos:se o app precisar de mais acesso, ele 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 ao Google Chat de forma síncrona ou assíncrona. Eles também podem concluir tarefas, como criar um espaço do Chat, em nome de um usuário.

As mensagens síncronas não exigem autenticação, a menos que o app Chat chame a API REST do Chat ou outra API do Google ao processar uma resposta.

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

Mensagens síncronas não exigem autenticação

As mensagens síncronas são respostas aos eventos do Chat. Os apps do Google Chat podem receber e responder a eventos depois de serem configurados e publicados na página de configuração do app de chat e não exigem autenticação nem autorização.

Veja alguns exemplos de eventos de chat síncronos:

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

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

Nenhuma autorização é necessária para mensagens síncronas
Figura 2. Mensagens síncronas não exigem autenticação

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

Essa sequência é repetida em cada evento do Chat.

As mensagens assíncronas precisam de autenticação

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

Ao chamar a API REST, os apps de chat podem postar mensagens no Google Chat ou concluir tarefas e acessar dados em nome de um usuário. Por exemplo, após detectar uma falha temporária no servidor, um app de chat pode chamar a API Chat para:

  • Crie um espaço do Chat dedicado a investigar e corrigir a falha temporária.
  • Adicione pessoas ao espaço do Chat.
  • Poste uma mensagem no espaço do Chat para informar detalhes sobre a falha temporária.

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

Autenticação necessária para mensagens assíncronas
Figura 3. Mensagens assíncronas precisam de autenticação.

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

Escopos da API Chat

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

O Google Chat é compatível com os seguintes escopos:

Escopo da API Google Chat Descrição
https://www.googleapis.com/auth/chat.bot Permite que os apps do Chat vejam e enviem mensagens.
https://www.googleapis.com/auth/chat.delete Exclua conversas e espaços e remova o acesso aos arquivos associados no Google Chat.
Assinaturas  
https://www.googleapis.com/auth/chat.memberships Ver, adicionar e remover participantes de conversas no Google Chat
https://www.googleapis.com/auth/chat.memberships.app Permite que o app Chat adicione e remova a si mesmo (mas não outros apps) de conversas do Google Chat.
Mensagens  
https://www.googleapis.com/auth/chat.messages Crie, receba, atualize, exclua e liste mensagens no Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions Ver, adicionar e excluir reações a mensagens no Google Chat
https://www.googleapis.com/auth/chat.messages.reactions.create Adicione reações às mensagens no Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Veja as reações às mensagens no Google Chat.
https://www.googleapis.com/auth/chat.messages.readonly receber e listar mensagens no Google Chat;
Espaços  
https://www.googleapis.com/auth/chat.spaces Crie conversas e espaços e veja ou atualize os metadados (incluindo as configurações do histórico) no Google Chat.
https://www.googleapis.com/auth/chat.spaces.create Crie conversas no Google Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Veja o chat e os espaços no Google Chat.

Saiba mais sobre os escopos das APIs do Google Workspace em Como escolher escopos para seu app.

Para ver uma lista de escopos disponíveis, consulte Escopos do OAuth 2.0 para APIs do Google.

Tipos de autenticação necessária

Os apps de chat podem ser autenticados e autorizados com a API Chat de duas formas: credenciais de usuário ou contas de serviço.

Com a autorização de credencial do usuário, um app de chat pode acessar determinados dados do usuário e realizar determinadas ações em nome do usuário. Os dados e as ações autorizadas são especificados por escopos.

Com a autorização da conta de serviço, um app do Chat acessa a API como um app usando credenciais da conta de serviço ou falsificando a identidade de um usuário com a delegação em todo o domínio.

A tabela a seguir lista os cenários comuns que os apps de chat enfrentam (se exigem autenticação) e, se necessário, qual tipo:

Cenário Nenhuma autenticação é necessária Autenticação do usuário compatível Conta de serviço compatível
Receber mensagens de:
Eventos de chat
Callbacks do Apps Script
Google Cloud Pub/Sub
Responder a mensagens:
de forma síncrona, por um evento do Chat.
De forma síncrona, por meio de um valor de retorno de chamada do Apps Script
De maneira assíncrona, use a API REST do Chat.
Enviar novas mensagens:
Com webhooks de entrada
Com a API REST do Chat
Criar um espaço do Chat:
Com a API REST do Chat
Usando a delegação em todo o domínio
Adicionar usuários e apps a um espaço do Chat:
Com a API REST do Chat
Usando a delegação em todo o domínio

Próxima etapa

Configure a autenticação e a autorização com as credenciais do usuário ou uma conta de serviço.