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

A autenticação e a 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 para apps do Chat e solicitações de API do Chat.

Visão geral do processo

O diagrama a seguir mostra as etapas gerais de autenticação e autorização do Google Chat:

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

  1. Configure um projeto do Google Cloud, ative a API Chat e configure seu app do Chat:durante o desenvolvimento, você cria um projeto do Google Cloud. No projeto na nuvem do Google Cloud, você ativa a API Chat, configura o app do Chat e define 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 precisar chamar a API Chat usando a autenticação de um usuário que ainda não foi concedida, ele vai solicitar que o usuário faça login.

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

  4. Pedir consentimento:se o app estiver se autenticando como um usuário, o Google vai mostrar uma tela de permissão OAuth para que o usuário decida 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 para 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 de escopos retornada for mais restritiva do que os escopos solicitados, o app vai desativar todos os recursos limitados pelo token.

  7. Acessar os 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 além do 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 pedir ao usuário para conceder novos escopos, o que resulta em uma nova solicitação para receber um token de acesso (etapas 3 a 6).

Quando os apps do Chat exigem autenticação

Os apps do 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 receber uma lista de pessoas em um espaço do Chat.

Os apps do Chat não exigem autenticação para responder a uma interação do usuário, a menos que chamem a API Chat ou outra API do Google ao processar 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.

As respostas às interações do usuário não exigem autenticação

Os apps do Google Chat não precisam se autenticar como usuário ou app do Chat para receber e responder de forma síncrona às interações do usuário.

Os apps do Google Chat recebem objetos de evento sempre que um usuário interage com eles ou os invoca, 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 do app do Chat.

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

Não é necessária autorização para interações do usuário com o app do Chat
Figura 2. As interações do usuário com o 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, a 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 se repete para cada interação do usuário com o app do Chat.

Mensagens assíncronas exigem autenticação

As mensagens assíncronas ocorrem quando um app do Chat faz uma solicitação à API Chat, que exige 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, depois de detectar uma falha no servidor, um app do Chat pode chamar a API Chat para:

  • Crie um espaço do Chat dedicado a investigar e corrigir a interrupção.
  • Adicione pessoas ao espaço do Chat.
  • Poste uma mensagem no espaço do Chat para dar 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 obrigató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 as credenciais do usuário na solicitação HTTP.
  2. O Google Chat autentica o app do Chat com as credenciais da conta de serviço ou do usuário.
  3. O Google Chat renderiza a mensagem do app em um espaço especificado.

Escopos da API Chat

Configure a tela de permissão OAuth e escolha os escopos para definir quais informações serão mostradas aos usuários e revisores de apps e registre seu app para que ele possa ser publicado mais tarde.

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, o tipo 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

Permite que os apps do Chat vejam conversas e enviem mensagens.

Esse escopo só aceita a autenticação de apps com 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.

Escopos confidenciais

Código do escopo Descrição
https://www.googleapis.com/auth/chat.spaces Criar conversas e espaços e conferir ou editar metadados (incluindo as configurações do histórico e de acesso) no Chat.
https://www.googleapis.com/auth/chat.spaces.create Criar novas conversas no Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Ver conversas e espaços no Chat.
https://www.googleapis.com/auth/chat.memberships Ver, adicionar, atualizar e remover participantes de conversas no Chat.
https://www.googleapis.com/auth/chat.memberships.app Adicionar e remover o app de conversas no Google Chat.
https://www.googleapis.com/auth/chat.memberships.readonly Ver 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 Ver, adicionar e excluir reações a mensagens no Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Adicionar reações a uma mensagem no Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Ver as reações a uma mensagem no Chat.
https://www.googleapis.com/auth/chat.users.readstate Acessar 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.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Ver as conversas e os espaços do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.spaces Ver ou editar chats e espaços do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Ver os participantes e administradores em conversas do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.memberships Ver, adicionar, atualizar e remover participantes e administradores em conversas do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.app.spaces

Criar conversas e espaços e ver ou atualizar metadados (incluindo as configurações do histórico e de acesso) no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.app.spaces.readonly

Ver metadados (incluindo as configurações do histórico) no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.app.spaces.create

Criar conversas e espaços no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.app.memberships

Mostrar, adicionar, atualizar e remover participantes de conversas e espaços no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.app.memberships.readonly

Ver participantes de conversas e espaços no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.customemojis Ver, criar e excluir emojis personalizados no Chat.
https://www.googleapis.com/auth/chat.customemojis.readonly Ver emojis personalizados no Chat.
https://www.googleapis.com/auth/chat.users.spacesettings Ver e atualizar as configurações de espaço do usuário do Chat.
https://www.googleapis.com/auth/chat.users.sections Ver, criar, atualizar e excluir suas seções no Chat, além de mover e listar seus itens de seção no Chat.
https://www.googleapis.com/auth/chat.users.sections.readonly Ver suas seções e os itens delas no Chat.

Escopos restritos

Código do escopo Descrição
https://www.googleapis.com/auth/chat.delete Excluir conversas e espaços e remover o acesso aos 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 Ver, escrever, enviar, atualizar e excluir mensagens e adicionar, ver e excluir reações a elas.
https://www.googleapis.com/auth/chat.messages.readonly Ver mensagens e reações no Chat.
https://www.googleapis.com/auth/chat.app.messages.readonly

Ver mensagens e reações no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

https://www.googleapis.com/auth/chat.admin.delete Excluir conversas e espaços do domínio do administrador e remover o acesso a arquivos associados no Chat.
https://www.googleapis.com/auth/chat.app.delete

Excluir conversas e espaços e remover o acesso aos arquivos associados no Chat como um app do Chat. Requer aprovação do administrador.

Esse escopo só aceita a autenticação de apps com 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.

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

Se o app precisar de acesso a outras APIs do Google, você também poderá 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 necessária

Há duas maneiras de os apps do Chat se autenticarem e autorizarem com a API Chat:

Autenticação de usuários
A
autenticação do usuário permite que um app do Chat acesse dados do usuário e conclua ações em nome dele. Os escopos do OAuth especificam os dados e as ações autorizados. A menos que o app do Chat tenha sido instalado pelo administrador ou tenha recebido delegação em todo o domínio, na primeira vez que o app do Chat realizar uma ação em nome de um usuário, o usuário precisará autorizar o app do Chat usando a tela de permissão do OAuth.
Autenticação de apps

A autenticação de apps permite que um app do Chat use credenciais da conta de serviço, acesse dados e conclua ações como ele mesmo. Como o app do Chat usa as próprias credenciais para acessar e trabalhar com recursos, os usuários finais não precisam aprovar as chamadas de API do app do Chat, e não é possível adicionar escopos de autorização OAuth que oferecem suporte à autorização de apps à tela de permissão OAuth.

Dois tipos de escopos de autorização do OAuth são compatíveis com a autenticação de apps:

  • https://www.googleapis.com/auth/chat.bot: seu app do Chat pode chamar métodos da API Google Chat que oferecem suporte a esse escopo de autorização para criar, atualizar, receber, listar ou excluir recursos a que ele tem acesso, como mensagens em espaços em que os usuários finais adicionam seu app do Chat. Seu app do Chat pode conceder esse escopo de autorização a si mesmo, sem precisar da autorização de um administrador ou usuário final.
  • https://www.googleapis.com/auth/chat.app.*: o uso desses escopos requer uma aprovação única do administrador. Para receber a aprovação do administrador, prepare a conta de serviço do app do Chat para receber a aprovação do administrador criando um cliente OAuth compatível com o Google Workspace Marketplace e configurando o app no SDK do Google Workspace Marketplace. Esses escopos permitem que o app do Chat chame métodos específicos da API Google Chat. Por exemplo, chat.app.spaces.create permite que os apps criem espaços do Chat.

Se um método for compatível com a autenticação de usuário ou de app, a API Chat vai retornar resultados diferentes com base no tipo de autenticação usado:

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

Por exemplo, chamar o método spaces.list() com autorização do app retorna a lista de espaços em que o app do Chat é participante. Chamar spaces.list() com a autorização do usuário retorna a lista de espaços em que o usuário é membro. Na prática, é possível usar os dois tipos de autenticação ao chamar a API Chat, dependendo do design e dos recursos do app do Chat.

Para chamadas de API Chat assíncronas

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 Suporte à autenticação de apps Escopos de autorização aceitos
Espaços  
Criar um espaço Com a autenticação do usuário:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.spaces.create
  • chat.app.spaces
Configurar um espaço — Com a Autenticação do usuário:
  • chat.spaces.create
  • chat.spaces
Acessar os detalhes de um espaço Com a autenticação do usuário:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.spaces.readonly
Com a autenticação de apps:
  • chat.bot
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.spaces
Listar espaços Com a autenticação do usuário:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de apps:
  • chat.bot
Pesquisar espaços — Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.spaces.readonly
Atualizar um espaço Com a autenticação do usuário:
  • chat.spaces
  • chat.import
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.spaces
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.spaces
Excluir um espaço Com a autenticação do usuário:
  • chat.delete
  • chat.import
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.delete
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.delete
Concluir o processo de importação de um espaço — Com a autenticação do usuário:
  • chat.import
Encontrar uma mensagem direta Com a autenticação do usuário:
  • chat.spaces.readonly
  • chat.spaces
Com a autenticação de apps:
  • chat.bot
Membros  
Criar um membro Com a autenticação do usuário:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.memberships
Acessar um membro Com a autenticação do usuário:
  • chat.memberships.readonly
  • chat.memberships
Com a autenticação de apps:
  • chat.bot
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships.readonly
Listar participantes Com a autenticação do usuário:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Com a autenticação de apps:
  • chat.bot
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships.readonly
Excluir um participante Com a autenticação do usuário:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.memberships
Atualizar um participante Com a autenticação do usuário:
  • chat.memberships
  • chat.import
Com a autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.memberships
Mensagens  
Criar uma mensagem Com a autenticação do usuário:
  • chat.messages.create
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Acessar os detalhes de uma mensagem Com a autenticação do usuário:
  • chat.messages.readonly
  • chat.messages
Com a autenticação de apps:
  • chat.bot
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.messages.readonly
Listar mensagens Com a autenticação do usuário:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Com a autenticação de apps e a aprovação do administrador:
  • chat.app.messages.readonly
Pesquise mensagens — Com a autenticação do usuário:
  • chat.messages.readonly
  • chat.messages
Atualizar uma mensagem Com a autenticação do usuário:
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Excluir uma mensagem Com a Autenticação do usuário:
  • chat.messages
  • chat.import
Com a autenticação de apps:
  • chat.bot
Fixar uma mensagem — Com a Autenticação do usuário:
  • chat.spaces.pins
  • chat.spaces
Liberar uma mensagem — Com a Autenticação do usuário:
  • chat.spaces.pins
  • chat.spaces
Listar mensagens fixadas — Com a Autenticação do usuário:
  • chat.spaces.pins.readonly
  • chat.spaces.readonly
  • chat.spaces.pins
  • chat.spaces
Atualizar cards em uma mensagem — Com a autenticação de apps:
  • chat.bot
Reações  
Criar uma reação — Com a autenticação do usuário:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Listar reações — Com a Autenticação do usuário:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Excluir uma reação — Com a autenticação do usuário:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Emojis personalizados  
Criar um emoji personalizado — Com a autenticação do usuário:
  • chat.customemojis
Excluir um emoji personalizado — Com a autenticação do usuário:
  • chat.customemojis
Criar um emoji personalizado — Com a autenticação do usuário:
  • chat.customemojis
  • chat.customemojis.readonly
Listar emojis personalizados — Com a autenticação do usuário:
  • chat.customemojis
  • chat.customemojis.readonly
Mídia e anexos  
Fazer upload de mídia como um anexo de arquivo — Com a autenticação do usuário:
  • chat.messages.create
  • chat.messages
  • chat.import
Fazer o download de mídia Com a autenticação do usuário:
  • chat.messages.readonly
  • chat.messages
Com a autenticação de apps:
  • chat.bot
Acessar um anexo de mensagem — Com a autenticação de apps:
  • chat.bot
Estados de leitura do usuário
Ver o estado de leitura do espaço de um usuário — Com a autenticação do usuário:
  • chat.users.readstate
  • chat.users.readstate.readonly
Atualizar o estado de leitura do espaço de um usuário — Com a autenticação do usuário:
  • chat.users.readstate
Receber o estado de leitura da conversa de um usuário — Com a autenticação do usuário:
  • chat.users.readstate
  • chat.users.readstate.readonly
Configurações de espaço do usuário
Receber a configuração de notificação de espaço de um usuário — Com a autenticação do usuário:
  • chat.users.spacesettings
Atualizar a configuração de notificação de espaço de um usuário — Com a autenticação do usuário:
  • chat.users.spacesettings
Eventos do espaço
Receber eventos de espaço — Com a autenticação do usuário, é preciso usar um escopo com base no tipo de evento:
  • Para eventos sobre mensagens:
    • chat.messages
    • chat.messages.readonly
  • Para eventos sobre reações:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Para eventos sobre assinaturas:
    • chat.memberships
    • chat.memberships.readonly
  • Para eventos sobre o espaço:
    • chat.spaces
    • chat.spaces.readonly
Listar eventos de espaço — Com a autenticação do usuário, é necessário usar um escopo para cada tipo de evento incluído na solicitação:
  • Para eventos sobre mensagens:
    • chat.messages
    • chat.messages.readonly
  • Para eventos sobre reações:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Para eventos sobre assinaturas:
    • chat.memberships
    • chat.memberships.readonly
  • Para eventos sobre o espaço:
    • chat.spaces
    • chat.spaces.readonly
Seções  
Criar uma seção — Com a Autenticação do usuário:
  • chat.users.sections
Excluir uma seção — Com a Autenticação do usuário:
  • chat.users.sections
Listar seções — Com a Autenticação do usuário:
  • chat.users.sections
  • chat.users.sections.readonly
Atualizar uma seção — Com a autenticação do usuário:
  • chat.users.sections
Posicionar uma seção — Com a autenticação do usuário:
  • chat.users.sections
Itens da seção  
Mover um item de seção — Com a autenticação do usuário:
  • chat.users.sections
Listar itens da seção — Com a autenticação do usuário:
  • chat.users.sections
  • chat.users.sections.readonly

Para eventos de interação do 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 aceita:

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