O tipo de vinculação de conta do OAuth oferece suporte a dois fluxos do 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.
O OAuth é a solução de vinculação de contas 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=geteintent=createnas solicitações a esse endpoint).
Para verificar se o 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 o OAuth funciona, conheça estes termos:
- Intent auxiliar de login da conta:uma intent auxiliar que você chama para solicitar
um fluxo de vinculação de conta do Google Assistente. Para mais informações, consulte
Login na conta.
- String de contexto:uma string personalizada que você adiciona à intent auxiliar de login na conta que informa ao usuário por que você precisa que ele vincule a conta.
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:
- Apresenta a interface de login aos usuários que ainda não estão conectados.
- 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:
- 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.
- 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.
- 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:
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 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:
- Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
- 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.
- 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.
- 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.
- 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.
- 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:
- Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
- Depois que o usuário concorda em vincular as contas, o Google abre seu endpoint de autorização no navegador do usuário.
- 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.
- 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.
- 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:
- Sua Ação pergunta ao usuário se ele quer vincular a conta ao seu serviço.
- 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.
- 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.
- 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 é 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.
- 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 OAuth
Esta seção aborda os vários fluxos que podem ocorrer com o OAuth.
Cada fluxo contém estas etapas comuns depois que o usuário invoca sua ação:
No fluxo acima, você chama a intent auxiliar actions.intent.SIGN_IN para iniciar
o fluxo de vinculação da conta. 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
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
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.