Guia conceitual da vinculação OAuth

O tipo de vinculação do OAuth é compatível com dois fluxos de OAuth 2.0 padrão do setor: fluxos implícitos e de código de autorização. No fluxo de código implícito, o Google abre seu 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 OAuth é a solução de vinculação de conta recomendada se as condições a seguir forem aplicáveis:

• Você tem uma implementação de um servidor OAuth 2.0 e não pode estender seu endpoint de troca de token para adicionar suporte aos protocolos do Google para vinculação automática e criação de conta usando um token de ID (ou seja, adicione os parâmetros intent=get e intent=create nas solicitações a esse endpoint).

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

Termos-chave

Antes de ler sobre como funciona a vinculação do OAuth, conheça estes termos:

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

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

• Cena do sistema de vinculação de contas:um cenário predefinido que implementa o fluxo de confirmação para vinculação de contas e pode ser personalizado 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 seu endpoint de autorização no navegador do usuário. Se o login for bem-sucedido, o 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.

  Este fluxo requer dois endpoints:

  • Endpoint de autorização:o endpoint responsável por encontrar ou receber consentimento dos usuários para acessar os dados. Esse endpoint faz o seguinte:
    1. Apresenta a interface de login aos usuários que ainda não estão conectados.
    2. Registra o consentimento para o acesso solicitado na forma de um código de autorização de curta duração.
  • Endpoint de troca de token:esse endpoint é usado para receber strings criptografadas chamadas tokens que autorizam o usuário da ação a acessar seu 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 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 o token expirou.

• Fluxo de código implícito:durante esse fluxo do OAuth 2.0, o Google abre seu 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 ao 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 seu serviço a acessar partes dos dados de um usuário. Os tokens de acesso são associados a cada usuário individual e não podem ser adivinhados.

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

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. Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
2. Depois que o usuário concorda em vincular as contas, o Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo começasse em um dispositivo somente de voz para uma ação, o Google transferiria a execução para um smartphone.
3. O usuário vai fazer login (se ainda não tiver feito isso) e conceder ao Google permissão para acessar os dados com sua API, caso ainda não tenha concedido.
4. O 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 é de curta duração e é aceito pelo seu serviço como credenciais para acessar APIs. O token de atualização é de longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando eles expiram.
6. Depois que o usuário concluir o fluxo de vinculação da conta, todas as solicitações subsequentes enviadas do Google Assistente para o webhook de fulfillment vão conter um token de acesso.

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

1. Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
2. Depois que o usuário concorda em vincular as contas, o Google abre seu endpoint de autorização no navegador do usuário.
3. O usuário vai fazer login (se ainda não tiver feito isso) e conceder ao Google permissão para acessar os dados com sua API, caso ainda não tenha concedido.
4. O 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 ao Google autorização para acessar a API e, em seguida, conclui a chamada.

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

1. Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
2. Depois que o usuário concorda em vincular as contas, o Google abre seu endpoint de autorização no navegador do usuário. Se o fluxo começasse em um dispositivo somente de voz para uma ação, o Google transferiria a execução para um smartphone.
3. O usuário vai fazer login (se ainda não tiver feito isso) e conceder ao Google permissão para acessar os dados com sua API, caso ainda não tenha concedido.
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 é de curta duração e é aceito pelo seu serviço como credenciais para acessar APIs. O token de atualização é de longa duração que o Google pode armazenar e usar para adquirir novos tokens de acesso quando eles expiram.
6. Depois que o usuário concluir o fluxo de vinculação da conta, todas as solicitações subsequentes enviadas do Google Assistente para o webhook de fulfillment vão conter um token de acesso.

Fluxos de vinculação OAuth

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

Observação: os fluxos a seguir presumem que o usuário concorda em vincular a conta dele ao seu serviço e conceder permissão ao Google para acessar os dados dele com sua API. Se um usuário não der consentimento, ofereça a ele uma maneira de continuar a Ação com um fluxo alternativo e limitado. Para mais informações, consulte Práticas recomendadas.

Cada fluxo contém estas etapas comuns depois que o usuário invoca sua ação:

Observação :uma linha de Webhook para User representa uma resposta simples que você cria e personaliza. As linhas mostradas do Assistente para o Usuário representam solicitações que pertencem ao Google Assistente e têm opções limitadas de personalização. As solicitações que exigem permissão sempre são de propriedade do Assistente. Do ponto de vista do usuário, o Google Assistente envia os dois tipos de resposta.

No fluxo acima, você faz a transição para a cena do sistema de vinculação de contas e fornece uma lógica personalizada. O Google Assistente pergunta ao usuário se ele quer vincular a conta ao 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 serviço no navegador. O usuário faz login (ou, dependendo da configuração, cria uma nova conta) e concede à sua Ação permissão para acessar os dados dele.

Os fluxos depois desse ponto diferem com base na implementação ou não do fluxo implícito ou do código de autorização. Esses fluxos são descritos nas seções a seguir.

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

Observação :este diagrama se baseia no diagrama de Etapas comuns acima.

Depois que o usuário fizer login e as credenciais forem verificadas, o serviço criará um token de acesso de longa duração e o retornará ao Google. Nesse momento, a identidade do usuário na sua Ação é vinculada à conta usada para fazer login, e o token de acesso é 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

Observação :este diagrama se baseia no diagrama de Etapas comuns acima.

Depois que o usuário fizer login e as credenciais forem verificadas, o serviço criará um código de autorização e o retornará ao Google.

Esse código de autorização é enviado para o endpoint de troca de token, que retorna um token de acesso e um token de atualização. Nesse momento, a identidade do usuário na sua Ação é vinculada à conta em que ele fez login, e todas as solicitações subsequentes enviadas do Google Assistente para o fulfillment contêm um token de acesso.