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. Este documento descreve como a autenticação e de autorização para apps do Chat e solicitações da API Chat.

Visão geral do processo

O diagrama a seguir mostra as etapas avançadas de autenticação e autorização para o 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 seu App do Chat:durante o desenvolvimento, você cria uma projeto do Google Cloud. No projeto do Google Cloud, você ativa a API Chat, configurar o app do Chat e a autenticação. Para mais informações, consulte Desenvolver no Google Workspace e Criar um app do Chat.

  2. API Call Chat:quando o app chama o método Chat, ela envia credenciais de autenticação ao API Chat. Se seu app é autenticado com uma conta de serviço, as credenciais são enviadas como parte do código do seu app. Se o app exigir a chamada da API Chat usando uma autenticação do usuário que ainda não foi concedida, ele solicita 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 usuário, o Google exibirá Uma tela de permissão OAuth para que o usuário possa decidir se quer conceder acesso ao app acesso aos dados solicitados. A autenticação com uma conta de serviço exigem o consentimento do usuário.

  5. Enviar solicitação aprovada de recursos:se o usuário consentir com o escopos de autorização, o app agrupa as credenciais e os escopos 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:esse token contém uma lista de aos escopos concedidos. Se a lista de escopos retornada for mais restritiva do que escopos solicitados, o aplicativo desativa 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. Receba um token de atualização (opcional): se o app precisar acessar o além do ciclo de vida de um token de acesso único, ela pode receber 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 solicitará que o usuário para conceder novos escopos, resultando em uma nova solicitação para obter um token de acesso (etapas 3 a 6).

Quando os apps do Chat exigem autenticação

Os apps de chat podem enviar mensagens em resposta a uma interação do usuário. 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 das 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 o API Chat ou outra API do Google enquanto para processar uma resposta.

Para enviar mensagens assíncronas ou realizar tarefas em nome de um usuário, Os apps de chat fazem solicitações RESTful para 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 ser autenticados como usuários ou App do Chat para receber e responder de forma síncrona eventos de interação.

Os apps do Google Chat recebem eventos de interação sempre que alguém interage ou invoca um app do Chat, incluindo o seguinte:

  • 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.

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

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

  1. O usuário envia uma mensagem para o app do Chat em Google Chat
  2. O Google Chat encaminha a mensagem para o app.
  3. O aplicativo 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 app do Chat evento.

Mensagens assíncronas exigem autenticação

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

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

  • Criar um espaço do Chat dedicado a investigar e corrigir o problema a interrupção do serviço.
  • Adicionar participantes ao espaço do Chat.
  • Poste uma mensagem no espaço do Chat para dar detalhes sobre a a interrupção do serviço.

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

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

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

Escopos da API Chat

Configurar a tela de permissão OAuth e escolher escopos para definir quais informações são exibidas aos usuários e revisores do app e registrar seu app para poder publicá-lo mais tarde.

Para definir o nível de acesso concedido ao app, você precisa identificar e declarar escopos de autorização. Um escopo de autorização é um URI do OAuth 2.0 string que contém o nome do app do Google Workspace, que tipo de dados ele acessos e 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. Você não consegue autenticar com credenciais de usuário delegação em todo o domínio usando esse escopo.

Permite que os apps de chat vejam os chats e enviem mensagens. Oferece acesso a todos os recursos disponíveis nos apps do Chat.

Escopos confidenciais

Código do escopo Descrição
https://www.googleapis.com/auth/chat.spaces Crie conversas e espaços e confira ou edite metadados (incluindo 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 Acessar o chat e os espaços no Chat.
https://www.googleapis.com/auth/chat.memberships Ver, adicionar, atualizar e remover participantes em 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 Confira, adicione e exclua reações a 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 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 última leitura das conversas do Chat.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Acessar o chat e os espaços do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.spaces Acessar ou editar o chat e os espaços do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Veja os participantes e gerentes em conversas do domínio do administrador no Chat.
https://www.googleapis.com/auth/chat.admin.memberships Acessar, adicionar, atualizar e remover participantes e gerentes em conversas do domínio do administrador 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 a arquivos associados no Chat.
https://www.googleapis.com/auth/chat.import Importe 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, visualizar e excluir reações a mensagens.
https://www.googleapis.com/auth/chat.messages.readonly Confira mensagens e reações no Chat.
https://www.googleapis.com/auth/chat.admin.delete Excluir conversas e espaços do domínio do administrador e remover o acesso aos arquivos associados no Chat.

Os escopos nas tabelas anteriores indicam sua sensibilidade, de acordo com a definições a seguir:

Caso seu app exija acesso a outras APIs do Google, adicione esses escopos . Para mais informações sobre os escopos da API do Google, consulte 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 os escopos

Tipos de autenticação exigida

Os apps do Chat podem autenticar e autorizar de duas maneiras: API Chat: credenciais de usuário ou contas de serviço.

Com a autorização de credenciais do usuário, um app do Chat pode: acessar dados do usuário e concluir ações em nome dele. Os escopos do OAuth especificam as ações e os dados autorizados.

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

Ao decidir que tipo de credencial usar para uma solicitação de API específica, tenha em mente que alguns métodos de API suportam apenas um tipo específico de credencial. Se um método de API oferecer suporte às duas credenciais, o tipo de credencial usada na chamada afeta o resultado retornado:

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

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

Para chamadas assíncronas da API Chat

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

Método Compatível com autenticação de usuários Autenticação de apps 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
Acessar os detalhes de um espaço Com a autenticação de usuários:
  • chat.spaces.readonly
  • chat.spaces
. Com a autenticação de apps:
  • chat.bot
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.spaces.readonly
Listar espaços Com a autenticação de usuários:
  • 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 de usuários:
  • chat.spaces
  • chat.import
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.spaces
Excluir um espaço Com a autenticação de usuários:
  • chat.delete
  • chat.import
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.delete
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 membro Com a autenticação de usuários:
  • chat.memberships
  • chat.memberships.app
  • chat.import
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
Receber um membro Com a autenticação de usuários:
  • 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 de usuários:
  • 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 membro Com a autenticação de usuários:
  • chat.memberships
  • chat.memberships.app
  • chat.import
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
Atualizar um participante Com a autenticação de usuários:
  • chat.memberships
  • chat.import
. Com a Autenticação de usuário usando privilégios de administrador:
  • chat.admin.memberships
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 anexo de arquivo 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
Receber um anexo de mensagem Com a Autenticação de apps:
  • chat.bot
Estados de leitura do usuário
Conferir 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 linha de execução de um usuário Com a autenticação de usuários:
  • chat.users.readstate
  • chat.users.readstate.readonly
Eventos do espaço
Receber eventos espaciais Com a Autenticação de usuário, é preciso usar um escopo baseado 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 do espaço Com a Autenticação de 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

Para eventos de interação com o 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 é necessária ou compatível:

Cenário Nenhuma autenticação necessária Compatível com autenticação de usuários Autenticação de apps compatível
Receber mensagens de:
Eventos de interação com o app do 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 maneira síncrona, usando um valor de retorno de callback do Apps Script
Para enviar novas mensagens:
Com webhooks de entrada