Autenticar e autorizar usuários

Neste guia, explicamos como usar o OAuth 2.0 com as credenciais do Google dos usuários para acessar a API Chat. Com a autenticação e autorização com credenciais de usuário, os apps de chat podem acessar dados do usuário e realizar operações em nome dele. Ao se autenticar em nome de um usuário, o app tem as mesmas permissões desse usuário e pode realizar ações como se fosse executado por ele. No entanto, esses apps não podem ser publicados publicamente. Para mais informações, consulte Publicar apps do Google Chat.

Depois de autenticar e autorizar uma chamada de API com credenciais de usuário, os apps de chat podem fazer o seguinte:

• Crie espaços do Chat.
• Adicione usuários a espaços do Chat e conversas em grupo.
• Trabalhe com dados de usuários em outras APIs do Workspace, como estas:
  • Crie eventos no Google Agenda.
  • Registre itens no Planilhas Google.
  • Envie um e-mail com o Gmail.

Quando um app executa uma ação com a autenticação do usuário (como criar um espaço), o Google Chat exibe uma mensagem de atribuição que informa aos usuários o nome do app que executou a ação para o usuário que o autorizou.

Para saber mais sobre quando os apps de chat exigem autenticação e que tipo de autenticação usar, consulte Tipos de autenticação necessária na visão geral de autenticação e autorização da API Chat.

Se você for um administrador de domínio, poderá conceder 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 exigir que cada usuário autorize. Depois de configurar a delegação em todo o domínio, a conta de serviço pode representar uma conta de usuário. Embora uma conta de serviço seja usada para autenticação, a delegação em todo o domínio personifica um usuário e, portanto, é considerada autenticação de usuário. Qualquer funcionalidade que exija autenticação do usuário pode ser usada com a delegação em todo o domínio.

Para usar a API Google Chat para acessar ou modificar recursos de uma organização do Google Workspace, o usuário precisa ser membro dessa organização. Os usuários externos ou sem uma conta do Google Workspace com acesso ao Google Chat não são compatíveis.

Pré-requisitos

Etapa 1: instalar a biblioteca de cliente do Google

Se você ainda não tiver instalado as bibliotecas de cliente do Google para sua linguagem preferida, execute o seguinte comando na interface de linha de comando:

pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client

É possível usar qualquer linguagem compatível com nossas bibliotecas de cliente.

Etapa 2: configurar a tela de consentimento OAuth, especificar escopos e registrar o app

Quando você usa o OAuth 2.0 para autorização, o Google exibe uma tela de consentimento para o usuário, incluindo um resumo do projeto, as políticas e os escopos de autorização solicitados. A configuração da tela de consentimento OAuth do app define o que o Google exibirá aos usuários e revisores do app e registrará o app para que você possa publicá-lo mais tarde.

Todos os apps que usam o OAuth 2.0 exigem uma configuração de tela de consentimento, mas você só precisa listar os escopos de apps usados por pessoas fora da sua organização do Google Workspace.

1. No Console do Google Cloud, acesse Menu menu > APIs e serviços > Tela de consentimento OAuth.

   Acessar a tela de permissão OAuth

2. Selecione o tipo de usuário do seu app e clique em Criar.

3. Preencha o formulário de registro do app e clique em Save and Continue.

4. Clique em Adicionar ou remover escopos. Adicione e verifique os escopos de autorização exigidos pelo app, clique em Atualizar e em Salvar e continuar.

5. Analise o resumo do registro do seu aplicativo. Clique em Editar para fazer alterações ou em Voltar para o painel.

Etapa 3: criar credenciais de ID do cliente OAuth no Console do Google Cloud

Para autenticar como usuário final e acessar dados do usuário no aplicativo, você precisa criar um ou mais IDs do cliente OAuth 2.0. Um ID do cliente é usado para identificar um único app para os servidores OAuth do Google. Se o aplicativo for executado em várias plataformas, como Android, iOS e Web, será necessário criar um ID do cliente separado para cada plataforma.

Criar credenciais de ID do cliente OAuth

Escolha o tipo de aplicativo para receber instruções específicas sobre como criar um ID do cliente OAuth:

Fazer o download do arquivo JSON da chave secreta do cliente

O arquivo de chave secreta do cliente é uma representação JSON das credenciais do ID do cliente OAuth que o app de chat pode consultar para fornecer credenciais.

1. No Console do Google Cloud, acesse Menu menu > APIs e serviços > Credenciais.

   Ir para Credenciais

2. Em IDs do cliente OAuth 2.0, clique no ID do cliente que você criou.

3. Clique em Fazer o download do JSON.

4. Salve o arquivo como client_secrets.json.

Etapa 4: escrever um script que chame a API Chat

O código a seguir usa uma biblioteca de cliente para chamar a API Chat. Ele se autentica usando a API Chat usando credenciais de ID do cliente OAuth e cria um espaço.

Salve o seguinte código em um arquivo chamado chat_space_create_named.py no mesmo diretório que contém client_secrets.json:

from __future__ import print_function

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.create"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then creates a Chat space.
    '''

    flow = InstalledAppFlow.from_client_secrets_file(
                      'client_secrets.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    service = build('chat', 'v1', credentials=creds)

    # Use the service endpoint to call Chat API.
    result = service.spaces().create(

      # Details about the space to create.
      body = {

        # To create a named space, set spaceType to SPACE.
        'spaceType': 'SPACE',

        # The user-visible name of the space.
        'displayName': 'API-made'
      }

      ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

Etapa 5: executar o script de exemplo

Para executar o exemplo, na linha de comando, navegue até o diretório que contém chat_space_create_named.py e client_secrets.json e execute o seguinte comando:

python3 chat_space_create_named.py

Um navegador é aberto e solicita que você faça login na sua Conta do Google:

Depois de fazer login, a tela de consentimento do OAuth aparece e solicita que você conceda permissão ao app.

Depois que você concede a permissão, o script chama a API Chat, que responde adicionando o app Chat a um espaço do Chat. O console imprime detalhes da chamada de API.

Resolver problemas do exemplo

Ao executar chat_space_create_named.py, talvez você receba um erro que diz:

Expected a JSON object with a single property for a "web" or "installed" application

Essa mensagem de erro significa que o arquivo client_secrets.json que você baixou do Console do Google Cloud não começa com a propriedade "web" ou "installed". Depois de autenticar com o arquivo transferido por download, se o código não salvar o token de acesso em um novo arquivo, como token.json, o token de acesso será gravado em client_secrets.json, o que pode causar esse erro durante tentativas de autorização subsequentes.

Para resolver o erro, faça o download do arquivo de chave secreta do cliente do Console do Google Cloud novamente e salve o novo arquivo no lugar do arquivo atual.

Temas relacionados

Para saber o que mais a API Chat pode fazer, consulte a documentação de referência da API Chat.