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
eintent=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:
- Apresenta a IU de login aos seus usuários que ainda não se conectaram.
- 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:
- 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.
- 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.
- 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:
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:
- Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
- 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.
- 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).
- 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.
- 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.
- 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:
- Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
- Depois que o usuário concordar em vincular contas, o Google abrirá o endpoint de autorização no navegador do usuário.
- 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).
- 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.
- 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:
- Seu Action pergunta ao usuário se ele quer vincular a conta ao serviço.
- 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.
- 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).
- 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.
- 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.
- 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.