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 para apps do Chat e solicitações da API do 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:
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 do Google Cloud, você ativa a API Chat, configura o app do Chat e configura a autenticação. Para mais informações, consulte Desenvolver no Google Workspace e Criar um app do Chat.
Chamar a API Chat: quando seu 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 uma autenticação do usuário que ainda não foi concedida, ele vai solicitar que o usuário faça login.
Solicitar recursos: o app solicita acesso com escopos especificados ao configurar a autenticação.
Pedir consentimento:se o app estiver autenticado como usuário, o Google exibirá uma tela de permissão OAuth para que o usuário decida se concede ou não ao app acesso aos dados solicitados. A autenticação com uma conta de serviço não exige consentimento do usuário.
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.
O Google retorna um token de acesso:contém uma lista de escopos concedidos. Se a lista de escopos retornada for mais restritiva do que os solicitados, o app vai desativar todos os recursos limitados pelo token.
Acessar os recursos solicitados: o app usa o token de acesso do Google para invocar a API Chat e acessar os recursos da API Chat.
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.
Solicitar mais recursos: se o app precisar de mais acesso, ele pedirá ao usuário para conceder 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 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 um usuário ou um app do Chat para receber e responder de forma 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 o seguinte:
- Um usuário envia uma mensagem para um app de chat.
- Um usuário menciona um app do Chat.
- Um usuário invoca um dos comandos de barra do app Chat.
O diagrama a seguir mostra uma sequência de solicitação-resposta entre um usuário do Chat e o app do Chat:
- O usuário envia uma mensagem para o app do Chat no Google Chat.
- O Google Chat encaminha a mensagem para o app.
- O app recebe a mensagem, a processa e retorna uma resposta para o Google Chat.
- O Google Chat renderiza a resposta para o usuário ou em um espaço.
Essa sequência se repete para cada evento de interação no app 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 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 de chat pode chamar a API Chat para:
- Crie um espaço do Chat dedicado a investigar e corrigir a interrupção.
- Adicionar 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 de chat e um espaço de chat:
- Um app do Chat cria uma mensagem chamando a
API Chat usando o
método
spaces.messages.createe inclui credenciais do usuário na solicitação HTTP. - O Google Chat autentica o app do Chat com as credenciais da conta de serviço ou do usuário.
- O Google Chat renderiza a mensagem do app em um espaço especificado do Chat.
Escopos da API Chat
Configurar a tela de consentimento do OAuth e escolher escopos para definir quais informações são exibidas para usuários e revisores de apps e registrar seu app para poder publicá-lo mais tarde.
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 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 de chat vejam os chats e enviem mensagens. Esse escopo só oferece suporte à autenticação de apps com contas de serviço. Não é possível autenticar com credenciais de usuário ou com a 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
|
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
|
Visualizar, 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
|
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
|
Acessar, adicionar e excluir 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 leitura mais recente das conversas do Chat. |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
Acessar as conversas 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
|
Acessar 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. |
https://www.googleapis.com/auth/chat.app.spaces
|
Crie conversas e espaços e confira ou atualize metadados (incluindo configurações do histórico e de acesso) no Chat. Exige aprovação do administrador. Este escopo só oferece suporte à autenticação de apps com contas de serviço. Não é possível autenticar com credenciais do usuário ou com a 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. Exige aprovação do administrador. Esse escopo só oferece suporte à autenticação de apps com contas de serviço. Não é possível autenticar com credenciais do usuário ou com a delegação em todo o domínio usando esse escopo. |
https://www.googleapis.com/auth/chat.app.memberships
|
Ver, adicionar, atualizar e remover participantes de conversas e espaços no Chat. Exige a aprovação do administrador. Esse escopo só oferece suporte à autenticação de apps com contas de serviço. Não é possível autenticar com credenciais do usuário ou com a delegação em todo o domínio usando esse escopo. |
https://www.googleapis.com/auth/chat.customemojis
|
Acesse, crie e exclua emojis personalizados no Chat. |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
Confira os emojis personalizados no Chat. |
https://www.googleapis.com/auth/chat.users.spacesettings
|
Acessar e atualizar as configurações do espaço do usuário no Chat.
Consulte as APIs de configurações de usuário do espaço: getSpaceNotificationSetting, updateSpaceNotificationSetting. |
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
|
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
|
Confira, escreva, envie, atualize e exclua mensagens e adicione, visualize e exclua reações a mensagens. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Acessar 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. |
https://www.googleapis.com/auth/chat.app.delete
|
Excluir conversas e espaços e remover o acesso aos arquivos associados no Chat. Exige aprovação do administrador. Esse escopo só oferece suporte à autenticação de apps com contas de serviço. Não é possível autenticar com credenciais de usuário ou com a 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:
Não sensível: esses escopos oferecem a menor esfera de acesso de autorização e exigem apenas a verificação básica do app. Para informações sobre esse requisito, consulte Etapas para se preparar para a verificação.
Confidenciais: esses escopos oferecem ao app acesso aos dados do Google de um usuário específico depois de receber autorização do usuário. É necessário fazer outra verificação do app. Para saber mais sobre esse requisito, consulte Etapas para apps que solicitam escopos sensíveis.
Restrito: esses escopos oferecem amplo acesso aos dados de usuários do Google e exigem que você passe pelo processo de verificação de escopo restrito. Para informações sobre esse requisito, consulte Serviços de API do Google: política de dados do usuário e Requisitos adicionais para escopos específicos da API. Consulte também Etapas para apps que solicitam escopos restritos.
Se o app exigir acesso a outras APIs do Google, você também poderá adicionar esses escopos. Para mais informações sobre os escopos das APIs 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 consentimento OAuth e escolher escopos.
Tipos de autenticação obrigatória
Há duas maneiras de os apps do Chat fazerem a autenticação e autorização com a API Chat:
- Autenticação do usuário A
- autenticação do usuário permite que um app de chat acesse dados do usuário e realize ações em nome dele. Os escopos do OAuth especificam os dados e ações autorizados. A menos que o app Chat tenha sido instalado pelo administrador ou tenha recebido delegação em todo o domínio, na primeira vez que o app Chat realizar uma ação em nome de um usuário, o usuário precisará autorizar o app Chat usando a tela de consentimento do OAuth.
- Autenticação de apps
A autenticação de app permite que um app de chat use credenciais de conta de serviço e acesse dados e realize ações como se fosse 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 compatíveis com a autorização do app à tela de permissão OAuth.
Dois tipos de escopos de autorização do OAuth oferecem suporte à autenticação de apps:
https://www.googleapis.com/auth/chat.bot: o app do Chat pode chamar métodos da API Google Chat que oferecem suporte a esse escopo de autorização para criar, atualizar, acessar, listar ou excluir recursos a que ele tem acesso, como mensagens em espaços a que os usuários finais adicionam o app do Chat. Seu app de chat pode conceder esse escopo de autorização por conta própria, sem a necessidade de autorização do administrador ou do usuário final.https://www.googleapis.com/auth/chat.app.*(Prévia para desenvolvedores): o uso desses escopos exige a aprovação única do administrador. Para receber a aprovação de 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.createpermite que os apps criem espaços do Chat.
Se um método oferece suporte à autenticação do usuário ou do app, a API Chat retorna resultados diferentes com base no tipo de autenticação usado:
- Com a autenticação de apps, os métodos só retornam recursos que o app de chat pode acessar.
- Com a autenticação do usuário, os métodos retornam apenas recursos que o usuário pode acessar.
Por exemplo, chamar o método spaces.list() com a autorização do app retorna
a lista de espaços em que o app do Chat é membro.
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 Chat.
Para chamadas assíncronas da API Chat
A tabela a seguir lista os métodos da API Chat e os escopos de autorização com suporte:
| Método | Compatível com autenticação de usuários | Suporte a autenticação de apps | Escopos de autorização com suporte | |
|---|---|---|---|---|
| Espaços | ||||
| Criar um espaço |
Com a autenticação do usuário:
|
|||
| Configurar um espaço | — |
Com a autenticação do usuário:
|
||
| Acessar os detalhes de um espaço |
Com a autenticação do usuário:
|
|||
| Listar espaços |
Com a autenticação do usuário:
|
|||
| Espaços de pesquisa | — |
Com a autenticação de usuários usando privilégios de administrador:
|
||
| Atualizar um espaço |
Com a autenticação do usuário:
|
|||
| Excluir um espaço |
Com a autenticação de usuários:
|
|||
| Concluir o processo de importação de um espaço | — |
Com a autenticação do usuário:
|
||
| Encontrar uma mensagem direta |
Com a autenticação do usuário:
|
|||
| Membros | ||||
| Criar um membro |
Com a autenticação do usuário:
|
|||
| Acessar os detalhes de uma associação |
Com a autenticação do usuário:
|
|||
| Listar participantes |
Com a autenticação do usuário:
|
|||
| Excluir um participante |
Com a autenticação de usuários:
|
|||
| Atualizar um participante |
Com a autenticação de usuários:
|
|||
| Mensagens | ||||
| Criar uma mensagem |
Com a autenticação do usuário:
|
|||
| Receber uma mensagem |
Com a autenticação do usuário:
|
|||
| Listar mensagens | — |
Com a autenticação do usuário:
|
||
| Atualizar uma mensagem |
Com a autenticação do usuário:
|
|||
| Excluir uma mensagem |
Com a autenticação do usuário:
|
|||
| Reações | ||||
| Criar uma reação | — |
Com a autenticação do usuário:
|
||
| Listar reações | — |
Com a autenticação de usuários:
|
||
| Excluir uma reação | — |
Com a autenticação do usuário:
|
||
| Emojis personalizados | ||||
| Criar um emoji personalizado | — |
Com a autenticação do usuário:
|
||
| Excluir um emoji personalizado | — |
Com a autenticação de usuários:
|
||
| Receber um emoji personalizado | — |
Com a autenticação do usuário:
|
||
| Listar emojis personalizados | — |
Com a autenticação do usuário:
|
||
| Mídia e anexos | ||||
| Fazer upload de mídia como um anexo de arquivo | — |
Com a autenticação do usuário:
|
||
| Fazer o download de mídia |
Com a autenticação de usuários:
|
|||
| Receber um anexo de mensagem | — |
Com a Autenticação de app:
|
||
| Estados de leitura do usuário | ||||
| Receber o estado de leitura do espaço de um usuário | — |
Com a autenticação do usuário:
|
||
| Atualizar o estado de leitura do espaço de um usuário | — |
Com a autenticação de usuários:
|
||
| Receber o estado de leitura de linha de um usuário | — |
Com a autenticação de usuários:
|
||
| Configurações do espaço do usuário | ||||
| Receber a configuração de notificação de espaço de um usuário | — |
Com a autenticação de usuários:
|
||
| Atualizar a configuração de notificação do espaço de um usuário | — |
Com a autenticação do usuário:
|
||
| Eventos espaciais | ||||
| Receber eventos de espaço | — |
Com a Autenticação de usuário,
é necessário usar um escopo com base no
tipo de evento:
|
||
| Listar eventos do espaço | — |
Com a autenticação de usuários, é preciso usar um escopo para cada
tipo de evento incluído na solicitação:
|
||
Para eventos de interação com o app do Chat
A tabela a seguir lista maneiras comuns de interação dos usuários com apps de chat e se a autenticação é necessária ou aceita:
| Cenário | Nenhuma autenticação necessária | Compatível com autenticação de usuários | Suporte a autenticação de apps | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Receber mensagens de: |
|
|||||||||||||||
| Responder a mensagens: |
|
|||||||||||||||
| Enviar novas mensagens: |
|
|||||||||||||||
Temas relacionados
- Para ter uma visão geral da autenticação e autorização no Google Workspace, consulte Saiba mais sobre autenticação e autorização.
- Para ter uma visão geral da autenticação e autorização no Google Cloud, consulte Visão geral da autenticação.
- Para saber mais sobre contas de serviço, consulte Contas de serviço.
- Para saber mais sobre como as APIs do Google usam o OAuth 2.0, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
- Configure a autenticação e a autorização com credenciais do usuário ou uma conta de serviço.