Guia explicativo da vinculação do Login do Google "simplificada" com base em OAuth

O tipo de vinculação "Simplificado" do Login do Google baseado em OAuth adiciona o Login do Google à vinculação de contas baseada em OAuth. Se você usar esse tipo de vinculação na sua Ação, o fluxo vai começar com o Login do Google, que permite verificar se as informações do perfil do Google do usuário existem no seu sistema. Caso contrário, será iniciado um fluxo padrão do OAuth. Ao fornecer uma combinação desses dois tipos de vinculação, seus usuários podem vincular a identidade na sua Ação a uma conta do Google ou de terceiros. Se quiser, também é possível criar uma nova conta com as informações do perfil do Google.

A vinculação simplificada é a solução recomendada se alguma das seguintes condições se aplicar:

• Você tem uma ação que abrange várias plataformas (por exemplo, se ela funciona com um app Android).
• Você tem um sistema de autenticação e quer permitir que os usuários vinculem as identidades a contas que não são do Google. Por exemplo, se você oferece um programa de fidelidade e quer garantir que o usuário não perca os pontos acumulados na conta atual.

Para verificar se a vinculação simplificada é 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 a vinculação simplificada funciona, conheça os seguintes termos:

• Token de ID do Google:uma declaração assinada da identidade de um usuário que contém as informações básicas do perfil dele no Google (nome, endereço de e-mail e foto do perfil). Um token de ID do Google é um JSON Web Token (JWT). Confira a seguir um exemplo de token decodificado:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

• 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:um fluxo do OAuth 2.0 que pode ser implementado com a vinculação simplificada. Este fluxo requer dois endpoints:

  • Endpoint de autorização:o endpoint que apresenta a interface de login aos usuários que ainda não fizeram login. Ela 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 é 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:um fluxo do OAuth 2.0 que pode ser implementado com a vinculação simplificada. Este fluxo requer apenas um endpoint de autorização. Durante esse fluxo, 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 agora está incluído em todas as solicitações enviadas do Google Assistente para sua açã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.

• 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.

Pré-requisitos

Para usar o tipo de vinculação simplificada, você precisa do seguinte:

• Um servidor OAuth 2.0

• Um endpoint de troca de token

  O endpoint de troca de token precisa ser estendido para adicionar suporte aos protocolos do Google para vinculação automática e criação de conta com base em um token de ID (ou seja, adicione os parâmetros intent=get e intent=create em solicitações a esse endpoint).

Como funciona

Nesta seção, descrevemos o fluxo geral da vinculação simplificada. A seção a seguir, Fluxos de vinculação simplificados, descreve os vários fluxos que podem ocorrer com base: a) se você ativa ou desativa a criação de contas por voz e b) usa o fluxo de código implícito ou de autorização.

O fluxo fundamental é o seguinte:

1. Sua Ação pede consentimento ao usuário para acessar o perfil do Google.
2. Depois que o usuário dá o consentimento, sua Ação recebe um token de ID do Google que contém as informações do perfil do Google do usuário.
3. É necessário validar e decodificar o token para ler o conteúdo do perfil.
4. A Ação usa esse token para verificar se as informações do perfil do Google do usuário existem no sistema.
   1. Se for o caso, isso significa que o usuário já fez login no sistema com a Conta do Google, e o Google Assistente vincula a identidade do usuário à Conta do Google. O usuário pode continuar a conversa com o Google Assistente com a conta vinculada.
   2. Caso contrário, consulte a etapa 5.
5. O usuário pode a) criar uma nova conta com as informações do perfil do Google dele ou b) fazer login no seu sistema com uma conta diferente. As opções apresentadas ao usuário variam dependendo de você ativar ou desativar a criação de contas por voz. Se o usuário fizer login no sistema com uma conta diferente, será iniciado o fluxo padrão do OAuth.
6. Depois que o usuário cria uma nova conta ou faz login com um provedor diferente, seu serviço retorna um token de acesso ao Google. Se você estiver usando o fluxo do código de autorização, seu serviço também retornará um token de atualização.
7. Agora, o usuário pode continuar a conversa com o Google Assistente com a conta vinculada.

Fluxos de vinculação simplificados

Esta seção aborda os vários fluxos que podem ocorrer com a vinculação simplificada. Esses diagramas percorrem os fluxos que ocorrem com o fluxo de código de autorização, em vez do fluxo de código implícito, e presumem que você está usando o Actions Builder.

Observação: os fluxos a seguir pressupõem que o usuário consente que a Ação acesse as informações do perfil do Google. Se um usuário não der consentimento, forneç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:

No fluxo acima, você faz a transição para a cena do sistema de vinculação de contas e fornece uma lógica personalizada. A cena pede permissão ao usuário para acessar as informações do perfil do Google. Depois que o usuário consente, o Google Assistente envia uma solicitação com as informações do perfil de [e-mail].

Os fluxos depois desse ponto são diferentes dependendo da configuração da vinculação de conta com voz e da existência das informações do usuário no seu sistema. Cada um desses fluxos é descrito nas seções a seguir.

Fluxos com a criação de conta do Voice ativada

Esta seção detalha os fluxos de vinculação de contas que podem ocorrer se você ativar a criação de contas por voz.

Observação :os diagramas a seguir são baseados no diagrama de Etapas comuns acima.

Fluxo 1: há informações do usuário no seu sistema

Observação :uma linha de Webhook para User representa uma resposta simples que você cria e personaliza. As linhas mostradas de Assistente para 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, os dois tipos de resposta são enviados pelo Google Assistente.

Nesse caso, o usuário representado por [e-mail] existe no seu back-end. Portanto, o endpoint de troca de token retorna um token para o usuário. A identidade do usuário na Ação agora está vinculada à Conta do Google. A solicitação original do usuário ("Pedir meu de sempre") corresponde à intent do usuário order_drink. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para o pedido normal de [e-mail]. O usuário pode continuar a conversa com o Google Assistente.

Fluxo 2: as informações do usuário não existem e o usuário cria uma conta

Como você ativou a criação de conta por voz e o [e-mail] não existe no seu back-end, o Google Assistente pergunta ao usuário se ele quer fazer uma destas ações:

a) Criar uma nova conta no seu sistema usando as informações do perfil do Google do cliente, o que é feito por voz.

b) Fazer login no sistema com uma conta diferente

Observação :também é possível permitir que o usuário crie uma nova conta com outro provedor. Você disponibiliza esses provedores na sua página de autorização.

Nesse caso, o usuário opta por criar uma nova conta usando a voz. O Google chama o endpoint de troca de token do seu serviço com uma solicitação para criar uma conta. Essa solicitação contém o token de ID do Google, que inclui os componentes necessários para criar uma nova conta. Em seguida, use as informações desse token (nome e endereço de e-mail do usuário) para criar uma conta para o usuário.

Depois que a conta é criada, seu serviço retorna um token de acesso e de atualização para a conta recém-criada. A identidade do usuário na Ação agora está vinculada à Conta do Google. A solicitação original do usuário ("Pedir de sempre") corresponde à intent do usuário order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta o banco de dados para a ordem comum de [e-mail], que ainda não existe porque o usuário é novo. Sua Ação pode perguntar ao usuário o que ele quer pedir.

Observação :normalmente, as novas contas não têm uma senha definida. Recomendamos que você adicione o Login do Google a outras plataformas para permitir que os usuários façam login pelo Google em todas as plataformas do seu aplicativo. Outra opção é enviar um e-mail ao usuário com um link que inicia o fluxo de recuperação de senha, permitindo que ele defina uma senha para fazer login em outras plataformas.

Fluxo 3: as informações do usuário não existem e o usuário faz login com uma conta diferente

Você ativou a criação de conta por voz, então o Google Assistente perguntará ao usuário se ele quer fazer uma destas ações:

a) Criar uma nova conta no seu sistema usando as informações do perfil do Google do cliente, o que é feito por voz.

b) Fazer login no sistema com uma conta diferente

Observação: também é possível permitir que o usuário crie uma nova conta com um provedor diferente. Você disponibiliza esses provedores na sua página de autorização.

Nesse caso, o usuário opta por fazer login com uma conta diferente, que inicia o fluxo padrão do OAuth. Se o fluxo começar em um dispositivo somente de voz, o Google transferirá a execução para um smartphone. Em seguida, o Google abre o endpoint de autorização no navegador do usuário e, dependendo da configuração, o usuário pode escolher se quer a) fazer login no serviço com uma conta atual que não use o Login do Google ou b) criar uma nova conta usando outro provedor. Para mais informações sobre o fluxo do OAuth, consulte o guia do conceito de vinculação do OAuth.

Depois de verificar as credenciais do usuário, o serviço retorna um token de acesso e um de atualização para o Google. A identidade do usuário na Ação agora está vinculada a uma conta de terceiros. A solicitação original do usuário ("Pedir meu de sempre") corresponde à intent do usuário order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para a ordem normal de [e-mail], que ainda não existe porque o usuário é novo. Sua Ação pode perguntar ao usuário o que ele quer pedir ou configurar o pedido habitual.

Fluxo com a criação de conta do Voice desativada

Esta seção detalha o fluxo de vinculação de contas que pode ocorrer se você desativar a criação de contas por voz.

Observação :os diagramas a seguir são baseados no diagrama de Etapas comuns acima.

Fluxo 4: as informações do usuário não existem

Você não ativou a criação de conta por voz, e o usuário não existe no seu back-end. Portanto, o fluxo de OAuth padrão é iniciado. O Google Assistente abre o endpoint de autorização no navegador do usuário. Se o fluxo começar em um dispositivo somente de voz, o Google transferirá a execução para um dispositivo com uma tela. O usuário pode optar por a) fazer login com um provedor diferente, se ele estiver registrado no seu serviço com uma conta diferente, ou b) criar uma nova conta com um provedor diferente. Para mais informações sobre o fluxo do OAuth, consulte o guia do conceito de vinculação do OAuth.

Depois de verificar as credenciais do usuário, o serviço retorna um token de acesso e um de atualização para o Google. A identidade do usuário na Ação agora está vinculada a uma conta de terceiros. A solicitação original do usuário ("Pedir meu de sempre") corresponde à intent do usuário order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para a ordem normal de [e-mail], que ainda não existe porque o usuário é novo. A Ação pode pedir que o usuário configure a ordem habitual.