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:
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.
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.
Solicitar recursos: seu app pede acesso com os escopos que você especifica ao configurar a autenticação.
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.
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: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.
Acessar recursos solicitados:o 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.
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 do 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:
- O usuário envia uma mensagem para o app Chat no Google Chat.
- O Google Chat encaminha a mensagem para o app.
- O app recebe, processa e retorna a resposta ao Google Chat.
- 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:
- 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.
- O Google Chat autentica o app de chat com a conta de serviço ou as credenciais do usuário.
- 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
Há duas maneiras de autenticar e autorizar os apps do Chat com a API Chat: credenciais de usuário ou contas de serviço.
Com a autorização de credencial do usuário, um app do Chat pode acessar dados do usuário especificados e concluir ações específicas 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 de chat acessa a API como um app usando as credenciais da conta de serviço.
Se você for um administrador de domínio, poderá 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 seus usuários sem que cada um precise dar consentimento. Depois de configurar a delegação em todo o domínio, é possível fazer chamadas de API usando sua conta de serviço para representar uma conta de usuário. Uma conta de serviço é usada para autenticação, mas a delegação em todo o domínio falsifica a identidade de um usuário. Por isso, ela é considerada uma autenticação de usuário. Qualquer funcionalidade que exija autenticação do usuário pode ser usada na 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: |
|
|||||||||||||||
| Responder a mensagens: |
|
|||||||||||||||
| Enviar novas mensagens: |
|
|||||||||||||||
| Criar um espaço do Chat: |
|
|||||||||||||||
| Adicionar usuários e apps a um espaço do Chat: |
|
|||||||||||||||
Recursos relacionados
- Para uma visão geral da autenticação e autorização no Google Workspace, consulte Saiba mais sobre autenticação e autorização no Google Workspace for Developers.
- Para uma visão geral da autenticação e autorização no Google Cloud, consulte Visão geral da autenticação na documentação do Google Cloud.
- Para saber mais sobre contas de serviço, consulte Contas de serviço na documentação do Google Cloud Identity and Access Management (IAM).
- 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 na documentação do Google Identity.
Próxima etapa
Configure a autenticação e a autorização com as credenciais do usuário ou uma conta de serviço.