Esta página foi traduzida pela API Cloud Translation.

Guia de conceitos de vinculação "Simplificado" do Login do Google com base em OAuth

O tipo de vinculação "Login simplificado" do Login do Google baseado em OAuth adiciona o Login do Google, além da vinculação de conta baseada em OAuth. Se você usar esse tipo de vinculação na sua ação, o fluxo começará com o Login do Google, que permite verificar se as informações do perfil do Google do usuário existem no sistema. Caso contrário, um fluxo OAuth padrão será iniciado. Ao fornecer uma combinação desses dois tipos de vinculação, os usuários podem vincular a identidade deles na sua ação a uma Conta do Google ou não. Se quiserem, eles também poderão criar uma nova conta com as informações do perfil do Google.

A vinculação otimizada é a solução recomendada para vinculação de contas se uma das seguintes condições se aplicar:

Você tem uma ação que abrange várias plataformas (por exemplo, se a ação funciona com um app Android).
Você tem um sistema de autenticação existente e quer permitir que os usuários vinculem as identidades a contas que não sejam 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 existente.

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

Termos-chave

Antes de ler sobre como a vinculação simplificada funciona, familiarize-se com os seguintes termos:

Token de ID do Google:uma declaração assinada de identidade de um usuário que contém informações básicas do perfil do Google (nome, endereço de e-mail e foto do perfil) do usuário. Um token de código do Google é um JSON Web Token (JWT). Veja 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": "jan@gmail.com", // 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: 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 de contas e pode ser personalizada para 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. Esse fluxo requer dois endpoints:
- Endpoint de autorização: o endpoint que apresenta a IU de login aos usuários que ainda não fizeram login. Ele 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 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 token 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: um fluxo do OAuth 2.0 que pode ser implementado com a vinculação simplificada. Esse fluxo requer apenas um endpoint de autorização. Durante esse fluxo, 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 agora está incluído em todas as solicitações enviadas do Google Assistente à 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 assim que um token de acesso de curta duração expirar.

Pré-requisitos

Para usar o tipo de vinculação "Simplificado", 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 para os protocolos do Google para vinculação automática e criação de conta a partir de um token de ID (ou seja, adicionar os parâmetros intent=get e intent=create em solicitações para esse endpoint).

Como funciona

Esta seção descreve 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 em a) se você ativa ou desativa a criação de conta por voz e b) se usa o fluxo de código implícito ou de autorização.

O fluxo básico é o seguinte:

Seu Action solicita ao usuário permissão para acessar o perfil do Google dele.
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 usuário.
Você deve validar e decodificar o token para ler o conteúdo do perfil.
Seu Action usa esse token para verificar se as informações do perfil do Google do usuário existem no sistema.
1. Em caso afirmativo, o usuário já fez login no seu sistema com a Conta do Google, e o Assistente vinculou 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, veja a etapa 5.
O usuário pode a) criar uma nova conta com as informações do perfil do Google ou b) fazer login no seu sistema com uma conta diferente. As opções exibidas ao usuário são diferentes com base na ativação ou desativação da criação de conta por voz. Se o usuário optar por fazer login no sistema com uma conta diferente, o fluxo OAuth padrão será iniciado.
Depois que o usuário cria uma nova conta ou faz login com um provedor diferente, o serviço retorna um token de acesso ao Google. Se você estiver usando o fluxo do código de autorização, o serviço também retornará um token de atualização.
O usuário agora 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 analisam os fluxos que ocorrem com o fluxo do código de autorização em vez do fluxo de código implícito e pressupõem que você está usando o Actions Builder.

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

No fluxo acima, você faz a transição para a cena do sistema de vinculação de contas e fornece uma justificativa personalizada. A cena pede ao usuário permissão 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 para user@gmail.com.

Os fluxos após esse ponto serão diferentes se você configurar a vinculação de conta com voz e se as informações do usuário já existirem no seu sistema. Cada um desses fluxos é descrito nas seções a seguir.

Fluxos com criação de conta de voz 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.

Fluxo 1: As informações do usuário existem em seu sistema

Nesse caso, o usuário representado por user@gmail.com existe no back-end. Portanto, o endpoint de troca de token retorna um token para o usuário. A identidade do usuário na sua ação agora está vinculada à Conta do Google. A solicitação original do usuário (“Fazer o pedido”) corresponde à intent do usuário order_drink. Seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados quanto à ordem normal de user@gmail.com. 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 a conta

Como você ativou a criação de conta por voz e user@gmail.com não existe no back-end, o Google Assistente pergunta ao usuário se ele quer fazer o seguinte:

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

b) Faça login em seu sistema com uma conta diferente

Nesse caso, o usuário decide criar uma nova conta por voz. O Google chama o endpoint de troca de token do serviço com uma solicitação para criar uma conta. Essa solicitação contém o token de código do Google, que inclui os componentes necessários para criar uma nova conta. Você pode usar 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, o serviço retorna um token de acesso e um token de atualização para a conta recém-criada. A identidade do usuário na sua ação agora está vinculada à Conta do Google dele. A solicitação original do usuário (“Fazer o pedido”) corresponde à intent do usuário order_drink.. O webhook processa o fulfillment da intent correspondente e consulta o banco de dados em busca da ordem normal de user@gmail.com, que ainda não existe porque o usuário é novo. Sua ação pode perguntar ao usuário o que ele quer pedir.

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

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

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

b) Faça login em seu sistema com uma conta diferente

Nesse caso, o usuário escolhe fazer login com uma conta diferente, que inicia o fluxo OAuth padrão. Se o fluxo começou em um dispositivo somente de voz, o Google transfere a execução para um smartphone. Em seguida, o Google abre seu endpoint de autorização no navegador do usuário e, dependendo da sua configuração, o usuário pode escolher a) fazer login no seu serviço com uma conta existente que não use o Login do Google ou b) criar uma nova conta usando um provedor diferente. Para mais informações sobre o fluxo de 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 token de atualização para o Google. A identidade do usuário na sua ação agora está vinculada a uma conta que não é do Google. A solicitação original do usuário (“Fazer o pedido”) corresponde à intent do usuário order_drink.. Seu webhook processa o fulfillment da intent correspondente e consulta o banco de dados quanto à ordem normal de user@gmail.com, 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 criação de conta de voz desativada

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

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

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