Guia do conceito de OAuth e Login do Google (Dialogflow)

O tipo de vinculação OAuth e Login do Google 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.

O OAuth e o Login do Google são a solução recomendada de vinculação de conta 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 o OAuth e o Login do Google são 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 funcionam o OAuth e o Login do Google, conheça estes 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": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}
  • 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ê quer vincular a conta.
  • Fluxo do código de autorização:um fluxo do OAuth 2.0 que pode ser implementado com o OAuth + Login do Google. Esse 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 o OAuth + Login do Google. 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 OAuth e Login do Google, você precisa do seguinte:

  • Um servidor OAuth 2

  • 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

Esta seção descreve o fluxo geral para OAuth e Login do Google. A seção a seguir, Fluxos OAuth e GSI, descreve os vários fluxos que podem ocorrer com base em: 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 OAuth e GSI

Esta seção aborda os vários fluxos que podem ocorrer com OAuth e GSI. 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 pressupõem que você está usando o Dialogflow como a solução de processamento de linguagem natural para sua ação.

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 com uma string de contexto que você personaliza. Essa intent solicita permissão ao usuário para acessar as informações do perfil do Google. Depois que o usuário consente, o Assistente envia uma solicitação com as informações do perfil de user@gmail.com.

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.

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

Nesse caso, o usuário representado por user@gmail.com 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 personalizada order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para conferir o pedido normal de user@gmail.com. Então, o usuário poderá 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 user@gmail.com 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

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 meu de sempre") corresponde à intent personalizada order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para a ordem comum 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 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

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 um provedor diferente. Para mais informações sobre o fluxo do OAuth, consulte o Guia do conceito 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 personalizada order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para a 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 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.

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 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 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 personalizada order_drink.. Em seguida, seu webhook processa o fulfillment da intent correspondente e consulta seu banco de dados para a ordem normal de user@gmail.com, que ainda não existe porque o usuário é novo. A Ação pode pedir que o usuário configure a ordem habitual.