Fluxo de usuários de autenticação

Informações gerais

O objetivo do fluxo de autenticação é identificar e autenticar o usuário no integrador de pagamentos (integrador).

A autenticação é uma entrada para outros métodos. Especialmente para associateAccount e capture. Isso significa que o comprovante de autenticação é usado como uma entrada (parâmetro) para esses dois métodos.

O Google também pode usar o fluxo de autenticação no modo independente para verificar um usuário. Nesse caso, ele não é usado como uma entrada para nenhum outro fluxo, mas apenas para verificar se um usuário pode autenticar essa identidade.

Lembre-se de que, durante a integração, o Google vai trabalhar com você para escolher o mecanismo de autenticação mais adequado ao seu produto.

Como o fluxo funciona

Há duas maneiras de autenticar um usuário, cada uma com o próprio fluxo. No momento da integração, o integrador precisa determinar qual usar.

  1. Autenticação de redirecionamento
  2. Autenticação da OTP por SMS-MT

Autenticação de redirecionamento

Um usuário do Google que precisa de autenticação pode ser redirecionado ao app ou ao site do integrador para verificar a identidade. Aqui está uma breve visão geral das etapas deste fluxo:

  1. O Google redireciona o usuário para o app Android ou da Web do integrador em que ele pode ser autenticado.
  2. Para autenticar, o requestId de autenticação (de AuthenticationRequest) é usado como prova de autenticação.
  3. Isso resulta em uma resposta assinada, chamada AuthenticationResponse.
  4. Depois, o app ou site redireciona o usuário para o Google.

A autenticação de redirecionamento usa um método HTTP GET, com parâmetros codificados no URL de um aplicativo da Web. Ele usa uma intent do Android para uma autenticação de app Android. Para mais detalhes sobre codificação, consulte Autenticação na Web e, para parâmetros de intent do Android, consulte Autenticação do Android.

O resultado de cada um desses mecanismos de autenticação é uma resposta assinada chamada AuthenticationResponse. Essa intent precisa incluir a resposta de autenticação de pagamentos padrão do Google (gspAuthenticationResponse) criptografada e codificada para comunicar uma autenticação. Se usado no modo autônomo, o gspResult e a assinatura são usados para determinar a autenticação bem-sucedida.

O diagrama de sequência a seguir mostra a interação entre o navegador do usuário, o Google e o aplicativo da Web do integrador:

Fluxo de autenticação de redirecionamento na Web

Fluxo de autenticação da Web

Veja a seguir uma lista dos objetos e do que eles representam:

  • Usuário: o usuário quer adicionar uma forma de pagamento à Conta do Google.
  • IU do Google: neste caso, a interface da Web no Google, em que o cliente começa a configurar uma forma de pagamento.
  • Servidor do Google: o servidor de back-end no Google que faz a verificação de autenticação, além de outras tarefas.
  • Web do integrador de pagamentos: o site do integrador em que o usuário tem uma conta.

Para esse fluxo de autenticação, já presumimos que o usuário está no site do Google (interface do Google) e está tentando adicionar uma forma de pagamento. É aqui que tudo começa.

  1. A interface do Google cria um URL de autenticação que é enviado ao servidor do Google (back-end). É isso que aciona o processo de autenticação.
  2. O servidor do Google cria uma solicitação de autenticação (AuthenticationRequest).
  3. A solicitação de autenticação enviada para a interface do Google.
  4. O usuário recebe uma solicitação para autenticar o ID com o integrador.
  5. O usuário responde que quer fazer a autenticação, que envia essa mensagem para o site do integrador.
  6. O site do integrador de pagamentos solicita a verificação da identidade do usuário.
  7. O usuário fornece um comprovante de identidade, que é enviado ao site do integrador de pagamentos.
  8. O integrador cria uma resposta (authenticationResponse) para a evidência recebida (com o authenticationResponse codificado na mensagem).
  9. Esse URL de resposta é enviado ao usuário.
  10. O URL da resposta é enviado imediatamente do usuário para a interface do Google.
  11. A interface do Google envia a resposta ao servidor do Google.
  12. O servidor do Google interpreta a resposta como verificada.

O próximo diagrama de sequência mostra a interação entre o smartphone do usuário, o Google e o app Android do integrador:

Fluxo de autenticação de redirecionamento para apps Android

Fluxo de autenticação de apps Android

Confira os objetos e o que eles representam:

  • Usuário: o usuário quer adicionar uma forma de pagamento à Conta do Google.
  • IU do Google: neste caso, a interface do app em que o cliente começa a configurar uma forma de pagamento.
  • Servidor do Google: o servidor de back-end no Google que faz a verificação de autenticação, além de outras tarefas.
  • APK do integrador de pagamentos: o app do integrador em que o usuário tem acesso à conta do integrador.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador em que as informações do usuário são armazenadas.

Como esse é um fluxo de autenticação, já presumimos que o usuário esteja usando um app (interface do Google) e tentando adicionar uma forma de pagamento. É aqui que a inicialização começa.

  1. A interface do Google cria uma chamada de autenticação que é enviada ao servidor do Google (back-end).
  2. O servidor do Google cria uma solicitação de autenticação (AuthenticationRequest).
  3. O servidor do Google envia um APK de chamadas para a interface (app) do Google solicitando autenticação.
  4. A IU do Google envia as informações do usuário para o APK do integrador de pagamentos (AUTHENTICATE_V1(authReq)).
  5. O APK do integrador de pagamentos envia a solicitação (authReq) ao servidor do integrador de pagamentos.
  6. O servidor do integrador de pagamentos envia um desafio de volta ao APK do integrador de pagamentos.
  7. O APK do integrador de pagamentos envia o desafio de volta ao usuário.
  8. O usuário fornece um comprovante de identidade, que é enviado ao APK do integrador de pagamentos.
  9. Essa prova é enviada ao servidor do integrador de pagamentos.
  10. O servidor cria um authenticationResponse assinado.
  11. A resposta de autenticação é bem-sucedida, e uma mensagem authResp é enviada ao APK do integrador de pagamentos.
  12. A mensagem de sucesso (authResp) é enviada do APK do integrador de pagamentos para a IU do Google.
  13. A interface do Google envia a resposta para o servidor do Google.
  14. O servidor do Google interpreta a resposta bem-sucedida.

Autenticação de OTP por SMS-MT

Outros métodos de autenticação são o serviço de mensagens curtas, o dispositivo móvel encerrado e a senha única (SMS-MT OTP). Esse mecanismo usa o número de telefone do usuário para enviar uma senha única para autenticação. O Google pede que o integrador envie uma OTP para o número de telefone do usuário. Depois que o usuário a receber e inserir na interface do Google, o usuário será verificado.

Isso inclui as seguintes etapas:

  1. A interface do usuário (IU) do Google solicita que o usuário digite o número de telefone, que já está registrado no integrador.
  2. O usuário digita um número de telefone na interface do Google.
  3. O Google aciona o integrador (chama o método sendOtp) para enviar uma senha única (OTP) ao usuário.
  4. O usuário recebe a mensagem SMS com a OTP.
  5. Em seguida, o usuário digita a OTP (usada como entrada para capture, associateAccount e verifyOtp) que recebeu na interface do Google, autenticando o usuário. Esse é um comprovante da autenticação.

No modo independente, somente o método verifyOtp é chamado para verificar o valor da OTP.

O diagrama de sequência a seguir mostra a interação entre o smartphone do usuário, o Google e o integrador ao enviar uma OTP:

Fluxo de autenticação por telefone (OTP de envio)

Fluxo de autenticação de telefone (OTP)

Veja uma lista dos objetos no diagrama e o que eles representam:

  • Usuário: o usuário quer adicionar uma forma de pagamento à Conta do Google.
  • IU do Google: neste caso, um site ou app para smartphones do Google em que o cliente começa a configurar uma forma de pagamento. Observação: se a interface do Google for um app para smartphone, as primeiras etapas serão ignoradas, porque o smartphone já sabe o número de telefone do usuário.
  • Servidor do Google: o servidor de back-end no Google que faz a verificação de autenticação, além de outras tarefas.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador em que as informações do usuário são armazenadas.

Como esse é um fluxo de autenticação de OTP, já presumimos que o usuário está em um app para smartphone ou site do Google (interface do Google) e está tentando adicionar uma forma de pagamento. É aqui que a inicialização começa.

  1. A interface do Google (telefone ou site) solicita o número de telefone do usuário.
  2. O usuário digita o número de telefone na interface do Google.
  3. A interface do Google envia o número (sendChallenge(phoneNum)) ao servidor do Google.
  4. O servidor do Google envia uma solicitação ao servidor do integrador de pagamentos (SendOtp(phoneNum)) para enviar uma senha única.
  5. O servidor do integrador de pagamentos envia uma senha única (OTP, na sigla em inglês) ao usuário.
  6. O servidor do integrador de pagamentos responde à solicitação do Google no item 5, sinalizando que a OTP foi enviada com sucesso.
  7. O usuário insere essa OTP na IU do Google (telefone ou site).
  8. A IU do Google envia a OTP ao servidor do Google, onde ela é enviada ao integrador de pagamentos para verificação. Isso verifica a identidade do usuário e o autentica.

Autenticação e reautenticação

Há dois momentos em que a autenticação pode ocorrer:

  1. Autenticação inicial: usada para identificar e autenticar um usuário. A autenticação inicial é usada como entrada para o método associateAccount.
  2. Reautenticação: usada em todos os outros contextos, como independente ou como entrada para capture.

A reautenticação é diferente da autenticação inicial. A intenção nunca é reidentificar um usuário, simplesmente uma nova autenticação. A reautenticação é usada pelo Google para desafiar o usuário a provar que é o proprietário de uma conta específica, e isso acontece a critério do Google.

Nesse processo, uma referência, chamada associationId, é fornecida à associação original (do fluxo de associação). Isso é fornecido pela chamada para o método associateAccount durante o fluxo de associação. O associationId identifica a conta a ser contestada. Por motivos de segurança, o usuário não deve ser capaz de alterar a conta que está sendo contestada.

Para a reautenticação da OTP por SMS-MT, o Google retém o número de telefone fixo informado durante a ligação original para sendOtp. Por motivos de segurança, isso não pode ser alterado.

Confira um exemplo de fluxo em que o Google decide contestar (reautenticar) antes de fazer uma compra:

Fluxo de reautenticação

Fluxo de reautenticação

A lista de objetos e o que eles representam são os seguintes:

  • Usuário: é a pessoa que quer fazer uma compra.
  • IU do Google: nesse caso, um site ou app para smartphones do Google em que o cliente começa a fazer a compra.
  • IU do integrador de pagamentos: o site ou app voltado para o cliente em que o usuário pode acessar as informações da conta com o integrador.
  • Servidor do Google: o servidor de back-end do Google que faz a verificação da reautenticação, além de outras tarefas.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador em que as informações do usuário são armazenadas.

O fluxo de reautenticação começa quando um cliente começa a fazer uma compra. Isso inicializa um fluxo para reautenticar o usuário.

  1. O usuário decide comprar um item ou serviço.
  2. A solicitação é enviada da interface do Google para o servidor do Google.
  3. O servidor do Google envia de volta uma solicitação de autenticação (authenticationRequest) para a interface do Google.
  4. A interface do Google envia uma solicitação à interface do integrador de pagamentos para autenticar (associationId, authenticationRequest) o usuário.
  5. A interface do integrador de pagamentos procura o usuário para verificar a identidade dele (LookupIdentity(associationId)).
  6. A interface do integrador de pagamentos solicita credenciais ao usuário (no site ou app do integrador).
  7. A resposta de autenticação é enviada ao servidor do integrador de pagamentos.
  8. A resposta de autenticação assinada (authenticationResponse) é enviada de volta à interface do integrador de pagamentos.
  9. A resposta de autenticação (authenticationResponse) é enviada da interface do integrador de pagamentos para a interface do Google.
  10. A interface do Google envia a resposta com as informações de compra para o servidor do Google.
  11. O servidor do Google envia uma mensagem capture (para encontrar os fundos disponíveis) ao servidor do integrador de pagamentos (authenticationRequestId, GPT, valor).
  12. O servidor do integrador de pagamentos envia uma mensagem de sucesso de volta para o servidor do Google.
  13. O servidor do Google envia uma mensagem de êxito para a interface do Google.
  14. A interface do Google entrega os itens ao cliente ou notifica que eles serão entregues em breve.

Autenticação por SMS-MO

O fluxo de autenticação do serviço de mensagens curtas do dispositivo móvel usa um SMS com um ID de solicitação de autenticação enviado do smartphone do usuário ao integrador de pagamentos para autenticar o usuário.

Fluxo de autenticação de SMS-MO

Veja uma lista dos objetos no diagrama e o que eles representam:

  • Usuário: o usuário quer adicionar uma forma de pagamento à Conta do Google.
  • IU/dispositivo do Google: neste caso, um app do Google para smartphones em que o cliente começa a configurar uma forma de pagamento.
  • Servidor do Google: o servidor de back-end do Google que gera as instruções de SMS com um ID de solicitação de autenticação (ARID) e recebe o resultado da autenticação do integrador.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador que recebe o SMS de autenticação e retorna o ID da solicitação de autenticação ao Google.

Como esse é um fluxo de autenticação, já presumimos que o usuário esteja usando um app (interface do Google) e tentando adicionar uma forma de pagamento. É aqui que a inicialização começa.

  1. O usuário seleciona um instrumento tokenizado para adicionar.
  2. A interface do Google chama o servidor do Google para iniciar o desafio SMS-MO.
  3. O servidor do Google retorna instruções por SMS, que consistem em um destino e um corpo que contém o ID de solicitação de autenticação.
  4. A IU do Google envia o SMS para o integrador de pagamentos.
  5. O servidor do integrador de pagamentos chama o endpoint AuthenticationResultNotification no servidor do Google com o ID da solicitação de autenticação.
  6. O ID da solicitação de autenticação é validado pelo servidor do Google, que responde com SUCCESS.
  7. A interface do Google chama o servidor do Google para obter o resultado da tentativa de autenticação.
  8. A resposta do servidor do Google com SUCESSO.

Autenticação simulada de SMS-MO

Para realizar testes de diagnóstico do fluxo de autenticação por SMS-MO, o Google define um endpoint Simular SMS. Isso elimina a necessidade de um SMS real ser enviado e validado ao realizar associações de teste no ambiente de sandbox.

Fluxo de autenticação de SMS-MO simulado

Veja uma lista dos objetos no diagrama e o que eles representam:

  • Testador: é a pessoa que inicia um teste de diagnóstico de associação por SMS-MO.
  • IU do Google: uma IU do Google em que o testador começa e monitora o status do teste de diagnóstico por SMS-MO.
  • Servidor do Google: o servidor de back-end do Google que gera as instruções SMS com um ID de solicitação de autenticação (ARID), envia a mensagem SMS simulada e recebe o resultado da autenticação do integrador.
  • Servidor do integrador de pagamentos: o servidor de back-end do integrador que recebe o SMS de autenticação simulada e retorna o ID da solicitação de autenticação ao Google.

As etapas desse fluxo são:

  1. O testador inicia o teste de diagnóstico por SMS-MO fornecendo um ID de assinante de teste (SID, na sigla em inglês) para usar no teste. Esse SID vai ser incluído na chamada simulateSms para o integrador de pagamentos.
  2. A interface do Google chama o servidor do Google para iniciar o desafio SMS-MO.
  3. O servidor do Google retorna instruções por SMS, que consistem em um destino e um corpo que contém o ID de solicitação de autenticação. Para os fins deste teste, o destino será substituído pela conexão HTTPS do sandbox do integrador de pagamentos.
  4. A interface do Google chama o servidor do Google para enviar a mensagem SMS simulada.
  5. A chamada simulateSms é feita do servidor do Google para o servidor do integrador de pagamentos. O ID da solicitação de autenticação e o ID do assinante (conforme fornecido na etapa 1) estão incluídos na chamada de API.
  6. O servidor do integrador de pagamentos responde ACKNOWLEDGED.
  7. O servidor do Google responde com SUCESSO à IU do Google.
  8. O servidor do integrador de pagamentos chama o endpoint AuthenticationResultNotification no servidor do Google com o ID da solicitação de autenticação.
  9. O servidor do Google responde com SUCESSO.
  10. A interface do Google chama o servidor do Google para obter o resultado da tentativa de autenticação.
  11. O servidor do Google responde COMPLETED.
  12. A interface do Google chama o servidor do Google para executar uma tentativa de associação.
  13. A chamada associateAccount é feita do servidor do Google para o servidor do integrador de pagamentos.
  14. O servidor do integrador de pagamentos responde com SUCESSO.
  15. O servidor do Google responde com SUCESSO.
  16. A interface do Google é atualizada para indicar ao testador que o teste de diagnóstico por SMS-MO foi concluído.

Práticas recomendadas e outras considerações

Opções de plataformas

Fornecer um fluxo de autenticação da Web para computadores e apps para dispositivos móveis permite que o integrador alcance o maior número de usuários. O Google recomenda que os integradores ofereçam suporte ao aplicativo Android, porque ele oferece a melhor experiência do usuário e gera a maior taxa de conversão. Os parâmetros transmitidos nas APIs de autenticação para os aplicativos para Web e Android são os mesmos.