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.
Informações gerais do processo
O diagrama a seguir mostra as etapas gerais de autenticação e autorização do Google Chat:
Configurar um projeto do Google Cloud, ativar a API Chat e configurar 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.
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 chamar a 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.
Solicitar recursos: seu app solicita acesso com escopos especificados durante a configuração da autenticação.
Peça consentimento:caso seu app esteja 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.
Enviar solicitação aprovada de recursos:se o usuário consentir com os escopos de autorização, seu 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: o token de acesso contém uma lista de escopos concedidos. Se a lista retornada de escopos for mais restritiva do que os escopos solicitados, o app vai desativar todos os recursos limitados pelo token.
Acesso aos recursos solicitados:seu app usa o token de acesso do Google para invocar a API Chat e acessar os recursos dela.
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 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 que estão 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 o app do Chat chame 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.
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 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 os seguintes:
- 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/resposta entre um usuário e um 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, processa e retorna uma resposta ao 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 com o app do Chat.
Mensagens assíncronas requerem 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 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 do Chat pode chamar a API Chat para:
- Crie um espaço do Chat dedicado a investigar e corrigir falhas temporárias.
- Adicionar pessoas ao espaço do Chat.
- Poste uma mensagem no espaço do Chat para fornecer detalhes sobre a falha temporária.
O diagrama a seguir mostra uma sequência de mensagens assíncronas entre um app do Chat e um espaço do Chat:
- Um app do Chat cria uma mensagem chamando a
API Chat usando o
método
spaces.messages.createe inclui as credenciais do usuário na solicitação HTTP. - O Google Chat autentica o app do Chat com a conta de serviço ou credenciais de usuário.
- 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 do seu app e escolha escopos para definir quais informações serão exibidas aos usuários e revisores e registre seu app para publicação posterior.
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 chats e enviem mensagens. Concede acesso a todos os recursos disponíveis para os apps de chat. |
Escopos confidenciais
| Código do escopo | Descrição |
|---|---|
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 Chat. |
https://www.googleapis.com/auth/chat.spaces.create
|
Crie conversas no Chat. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Ver o chat e os espaços no Chat. |
https://www.googleapis.com/auth/chat.memberships
|
Ver, adicionar e remover participantes de conversas no Chat |
https://www.googleapis.com/auth/chat.memberships.app
|
adicionar e se remover das 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
|
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
|
Veja as reações a uma mensagem no 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 aos arquivos associados no Chat. |
https://www.googleapis.com/auth/chat.messages
|
Ver, escrever, enviar, atualizar e excluir mensagens e adicionar, mostrar e excluir reações a elas. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Veja mensagens e reações no Chat. |
Os escopos nas tabelas anteriores indicam a confidencialidade deles, de acordo com as seguintes definições:
Não confidencial: esses escopos fornecem a menor esfera de acesso de autorização e exigem apenas uma verificação básica de apps. Saiba mais sobre esse requisito em Etapas de preparação para a verificação.
Confidencial: esses escopos fornecem ao seu app acesso aos dados do Google de um usuário específico após receber a autorização dele. É necessário que você passe por uma verificação adicional de apps. Para mais informações sobre esse requisito, consulte Etapas para apps que solicitam escopos confidenciais.
Restrito: esses escopos fornecem 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, também é possível 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 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: credenciais de usuário ou contas de serviço.
Com a autorização de credencial, um app do Chat pode acessar 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 disponibilizados publicamente. Para saber mais, consulte Publicar apps do Google Chat.
Com a autorização, um app do Chat acessa
a API como um app usando as credenciais da conta de serviço. A autorização do app sempre
usa o escopo de autorização chat.bot.
Se você é um administrador de domínio, é possível 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 usuários sem exigir o consentimento de cada um. Depois de configurar a delegação em todo o domínio, é possível fazer chamadas de API usando a conta de serviço para representar uma conta de usuário. A conta de serviço é usada para autenticação, mas a delegação em todo o domínio representa um usuário e, por isso, é considerada 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 são compatíveis apenas com 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 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 IU do Chat.
Por exemplo, chamar o método ListSpaces com autorização do app retorna a
lista de espaços de que ele faz parte. Chamar o 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 de API do Chat assíncronas
A tabela a seguir lista os métodos da API Chat e os escopos de autorização compatíveis:
| Método | Compatível com a autenticação do usuário | Compatível com a autenticação de apps | Escopos de autorização compatíveis | |
|---|---|---|---|---|
| Espaços | ||||
| Criar um espaço | — |
|
||
| Configurar um espaço | — |
|
||
| Comprar um espaço |
Com a autenticação do usuário:
|
|||
| Listar espaços |
Com a autenticação do usuário:
|
|||
| Atualizar um espaço | — |
|
||
| Excluir um espaço | — |
|
||
| Encontrar uma mensagem direta |
Com a autenticação do usuário:
|
|||
| Membros | ||||
| Criar um participante | — |
|
||
| Assinar |
Com a autenticação do usuário:
|
|||
| Participantes da lista |
Com a autenticação do usuário:
|
|||
| Excluir um participante | — |
|
||
| Mensagens | ||||
| Criar uma mensagem |
Com a autenticação do usuário:
|
|||
| Receber uma mensagem |
Com a autenticação do usuário:
|
|||
| Listar mensagens | — |
|
||
| 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 | — |
|
||
| Listar reações | — |
|
||
| Excluir uma reação | — |
|
||
| Mídia e anexos | ||||
| Fazer upload de mídia como um arquivo anexo | — |
|
||
| Fazer o download de mídia |
Com a autenticação do usuário:
|
|||
| Receber anexo de uma mensagem | — |
|
||
Para eventos de interação com o app do Chat
A tabela a seguir lista as formas mais comuns de interação dos usuários com apps do Chat e se a autenticação é obrigatória ou compatível:
| Cenário | Nenhuma autenticação necessária | Compatível com a autenticação do usuário | Compatível com 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 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 de usuário ou uma conta de serviço.