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 e solicitações da API 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 o 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 o app chama a API Chat, ele envia credenciais de autenticação para ela. 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 a chamada da 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.
Solicitar recursos: seu app solicita acesso com escopos especificados durante a configuração da autenticação.
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 decida se concede ou não ao app 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:contém uma lista de escopos concedidos. Se a lista de escopos retornada for mais restritiva que os escopos solicitados, o app 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.
Receba um token de atualização (opcional): se o app precisar acessar a API Google Chat depois do período de duração 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 do 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 das 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 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.
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 para receber e responder de forma síncrona aos 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 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 do Chat 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 a mensagem, a 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 é repetida para cada evento de interação 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, após detectar uma interrupção do 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.
- Adicionar participantes 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 assíncrona de mensagens entre um app e um espaço do Chat:
- Um app do Chat cria uma mensagem chamando a
API Chat usando o
método
spaces.messages.create
e 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
Configure a tela de permissão OAuth e escolha os escopos para definir quais informações serão exibidas aos usuários e revisores, além de registrar o app para que você possa publicá-lo 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 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
|
O escopo Permite que os apps de chat vejam os chats e enviem mensagens. Dá acesso a todos os recursos disponíveis para os 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 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
|
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
|
Confira, escreva, envie, atualize e exclua mensagens e adicione, visualize e exclua 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 a sensibilidade, de acordo com as seguintes definições:
Não confidencial: esses escopos fornecem 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 de preparação para a verificação.
Sensível: esses escopos fornecem ao app acesso aos dados do Google de um usuário específico após receber a autorização dele. Isso requer que você passe por uma verificação adicional de apps. Para saber mais sobre esse requisito, consulte as Etapas para apps que solicitam escopos confidenciais.
Restrito: esses escopos dão amplo acesso aos dados do usuário do Google e exigem que você passe pelo processo de verificação de escopo restrito. Para informações sobre esse requisito, consulte Serviços da API do Google: política de dados do usuário e Outros requisitos para escopos específicos da API. Consulte também Etapas para apps que solicitam escopos restritos.
Caso seu app precise de 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 exigida
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 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 credenciais de conta de serviço. A autorização do app sempre
usa o escopo chat.bot
.
Ao decidir que tipo de credencial usar para uma solicitação de API específica, lembre-se de que alguns métodos de API aceitam apenas um tipo específico de credencial. Se um método de API for compatível com as duas credenciais, o tipo de credencial usado na chamada afetará o resultado retornado:
- Com a autorização do app, os métodos retornam apenas os recursos que o app pode acessar.
- Com a autorização do usuário, os métodos retornam apenas os recursos que o usuário pode acessar na interface do Chat.
Por exemplo, chamar o método ListSpaces
com a autorização do app retorna a
lista de espaços de que o app participa. Chamar ListSpaces
com a 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 assíncronas da API Chat
A tabela a seguir lista os métodos da API Chat e os escopos de autorização compatíveis:
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:
|
||
Configurar um espaço | — |
Com a autenticação de usuários:
|
||
Acessar os detalhes de um espaço |
Com a autenticação de usuários:
|
|||
Listar espaços |
Com a autenticação de usuários:
|
|||
Pesquisar espaços |
Com a Autenticação de usuário usando privilégios de administrador:
|
|||
Atualizar um espaço | — |
Com a autenticação de usuários:
|
||
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 de usuários:
|
||
Encontrar uma mensagem direta |
Com a autenticação de usuários:
|
|||
Membros | ||||
Criar um membro | — |
Com a autenticação de usuários:
|
||
Receber um membro |
Com a autenticação de usuários:
|
|||
Listar participantes |
Com a autenticação de usuários:
|
|||
Excluir um membro | — |
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 de usuários:
|
|||
Receber uma mensagem |
Com a autenticação de usuários:
|
|||
Listar mensagens | — |
Com a autenticação de usuários:
|
||
Atualizar uma mensagem |
Com a autenticação de usuários:
|
|||
Excluir uma mensagem |
Com a autenticação de usuários:
|
|||
Reações | ||||
Criar uma reação | — |
Com a autenticação de usuários:
|
||
Listar reações | — |
Com a autenticação de usuários:
|
||
Excluir uma reação | — |
Com a autenticação de usuários:
|
||
Mídia e anexos | ||||
Fazer upload de mídia como um anexo de arquivo | — |
Com a autenticação de usuários:
|
||
Fazer o download de mídia |
Com a autenticação de usuários:
|
|||
Receber um anexo de mensagem | — |
Com a Autenticação de apps:
|
||
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:
|
||
Atualizar o estado de leitura do espaço de um usuário | — |
Com a autenticação de usuários:
|
||
Ver o estado de leitura da linha de execução de um usuário | — |
Com a autenticação de usuários:
|
||
Eventos do espaço | ||||
Receba eventos do espaço | — |
Com a autenticação de usuários:
|
||
Listar eventos do espaço | — |
Com a autenticação de usuários:
|
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: |
|
|||||||||||||||
Responder a mensagens: |
|
|||||||||||||||
Para enviar novas mensagens: |
|
Temas relacionados
- Para 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.