As ações de conversa serão descontinuadas em 13 de junho de 2023. Para mais informações, consulte Desativação do Ações de conversa.

Guia do conceito de vinculação do OAuth

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O tipo de vinculação do OAuth é compatível com dois fluxos padrão do OAuth 2.0 do setor: fluxos implícito e de código de autorização. No fluxo de código implícito, o Google abre o endpoint de autorização no navegador do usuário. Após o login, você retorna um token de acesso de longa duração para o Google. Esse token de acesso é incluído em todas as solicitações enviadas do Google Assistente para a ação.

A vinculação do OAuth é a solução de vinculação de contas recomendada se:

  • Você tem uma implementação existente de um servidor OAuth 2.0 e não é possível estender o endpoint da troca de tokens para adicionar suporte aos protocolos do Google para vinculação automática e criação de contas com um token de ID (ou seja, adicionar os parâmetros intent=get e intent=create às solicitações para esse endpoint).

Para verificar se a vinculação OAuth é a solução certa para você, consulte a página Escolha seu tipo de vinculação de conta.

Termos-chave

Antes de ler mais sobre como a vinculação do OAuth funciona, leia os seguintes termos:

  • user.verificationStatus:uma propriedade definida pelo sistema para indicar se a sessão atual tem um usuário verificado.

  • user.accountLinkingStatus: uma propriedade definida pelo sistema para indicar se o usuário na sessão atual tem uma identidade vinculada.

  • Cenário do sistema de vinculação de contas: é uma cena predefinida que implementa o fluxo de confirmação para vinculação da conta e pode ser personalizada para atender a casos de uso específicos.

  • Fluxo do código de autorização: durante esse fluxo do OAuth 2.0, o Google abre o endpoint de autorização no navegador do usuário. Se o login for bem-sucedido, seu serviço criará um código de autorização e o retornará ao Google. O Google envia esse código de autorização para o endpoint de troca de token, que verifica a autenticidade do código e retorna um token de acesso e de atualização.

    Esse fluxo requer dois endpoints:

    • Endpoint de autorização:o endpoint responsável por encontrar ou solicitar o consentimento dos usuários para acesso aos dados. Esse endpoint faz o seguinte:
      1. Apresenta a IU de login aos seus usuários que ainda não se conectaram.
      2. Registra o consentimento no acesso solicitado na forma de um código de autorização de curta duração.
    • Endpoint de troca de tokens:esse endpoint é usado para receber strings criptografadas chamadas tokens que autorizam o usuário da ação a acessar o serviço. Esse endpoint é responsável por dois tipos de trocas:
      1. Troca um código de autorização por um token de atualização de longa duração e um token de acesso de curta duração. Essa troca acontece quando o usuário passa pelo fluxo de vinculação da conta.
      2. Troca um token de atualização de longa duração por um de acesso de curta duração. Essa troca acontece quando o Google precisa de um novo token de acesso porque ele expirou.

  • Fluxo de código implícito:durante esse fluxo do OAuth 2.0, o Google abre o endpoint de autorização no navegador do usuário. Se o login for bem-sucedido, você retornará um token de acesso de longa duração para o Google. Esse token de acesso é incluído em todas as solicitações enviadas do Google Assistente para a ação. Esse fluxo requer apenas um endpoint de autorização.

  • Token de acesso: um token que autoriza o serviço a acessar partes dos dados de um usuário. Os tokens de acesso são associados a cada usuário e não podem ser adivinhados.

  • Token de atualização:é trocado por um novo depois que o token de acesso de curta duração expirar.

Como funciona

Nesta seção, descrevemos o fluxo geral do código de autorização OAuth e os fluxos implícitos. A seção a seguir, Fluxos de vinculação do OAuth, descreve os vários fluxos que podem ocorrer com o OAuth.

O fluxo do código de autorização pode ser resumido da seguinte forma:

  1. Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
  2. Depois que o usuário concordar em vincular contas, o Google abrirá o endpoint de autorização no navegador do usuário. Se o fluxo fosse iniciado em um dispositivo apenas de voz para uma ação, o Google transferiria a execução para um smartphone.
  3. O usuário faz login (se ainda não tiver feito) e concede permissão ao Google para acessar os dados dele com a API (se ainda não tiver concedido permissão).
  4. Seu serviço cria um código de autorização e o retorna ao Google redirecionando o navegador do usuário de volta para o Google com o código de autorização anexado à solicitação.
  5. O Google envia o código de autorização para o endpoint de troca de token, que verifica a autenticidade do código e retorna um token de acesso e um token de atualização. O token de acesso é um token de curta duração aceito pelo serviço como credenciais para acessar as APIs. O token de atualização é um token de longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando expirarem.
  6. Depois que o usuário concluir o fluxo de vinculação da conta, cada solicitação subsequente enviada do Google Assistente para o webhook de fulfillment vai conter um token de acesso.

O fluxo de código implícito pode ser resumido da seguinte forma:

  1. Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
  2. Depois que o usuário concordar em vincular contas, o Google abrirá o endpoint de autorização no navegador do usuário.
  3. O usuário faz login (se ainda não tiver feito) e concede permissão ao Google para acessar os dados dele com a API (se ainda não tiver concedido permissão).
  4. Seu serviço cria um token de acesso e o retorna ao Google redirecionando o navegador do usuário de volta para o Google com o token de acesso anexado à solicitação.
  5. Depois que o usuário concluir o fluxo de vinculação da conta, o Google chamará as APIs do serviço e anexará o token de acesso a cada solicitação. O serviço verifica se o token de acesso concede autorização ao Google para acessar a API e, em seguida, conclui a chamada de API.

O fluxo fundamental do código de autorização é o seguinte:

  1. Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
  2. Depois que o usuário concordar em vincular contas, o Google abrirá o endpoint de autorização no navegador do usuário. Se o fluxo fosse iniciado em um dispositivo apenas de voz para uma ação, o Google transferiria a execução para um smartphone.
  3. O usuário faz login (se ainda não tiver feito) e concede permissão ao Google para acessar os dados dele com a API (se ainda não tiver concedido permissão).
  4. Seu serviço cria um código de autorização e o retorna ao Google redirecionando o navegador do usuário de volta para o Google com o código de autorização de curta duração anexado à solicitação.
  5. O Google envia o código de autorização para o endpoint de troca de token, que verifica a autenticidade do código e retorna um token de acesso e um token de atualização. O token de acesso é um token de curta duração aceito pelo serviço como credenciais para acessar as APIs. O token de atualização é um token de longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando expirarem.
  6. Depois que o usuário concluir o fluxo de vinculação da conta, cada solicitação subsequente enviada do Google Assistente para o webhook de fulfillment vai conter um token de acesso.

Fluxos de vinculação do OAuth

Esta seção aborda os vários fluxos que podem ocorrer com a vinculação do OAuth.

Cada fluxo contém estas etapas comuns após o usuário invocar sua ação:

No fluxo acima, faça a transição para o cenário do sistema de vinculação de contas e forneça uma justificativa personalizada. O Google Assistente pergunta ao usuário se ele quer vincular a conta ao seu serviço e mostra uma tela com as permissões solicitadas. Quando o usuário consente, o Google o redireciona para o endpoint de autorização do seu serviço no navegador. O usuário faz login (ou, dependendo da sua configuração, cria uma nova conta) e concede à sua permissão Ação para acessar os dados dele.

Os fluxos após esse ponto diferem se você implementou o fluxo implícito ou o código de autorização. Esses fluxos são descritos nas seções a seguir.

Fluxo 1: o usuário faz login com o fluxo implícito

Depois que o usuário faz login e as credenciais dele são verificadas, seu serviço cria um token de acesso de longa duração e o retorna ao Google. Neste ponto, a identidade do usuário na sua ação está vinculada à conta em que ele fez login, e o token de acesso está anexado a cada chamada de API que o Google faz para as APIs do seu serviço.

Fluxo 2: o usuário faz login com o fluxo do código de autorização

Depois que o usuário faz login e as credenciais dele são verificadas, o serviço cria um código de autorização e o retorna ao Google.

Esse código de autorização é enviado ao endpoint de troca de token, que retorna um token de acesso e um de atualização. Nesse momento, a identidade do usuário na sua ação está vinculada à conta em que ele fez login, e cada solicitação subsequente enviada do Google Assistente para o fulfillment contém um token de acesso.