Autenticação Silenciosa Avançada – Implementação Assíncrona [Alfa]

Nota: O Silent Authentication Advanced está atualmente em fase alfa. A integração da oferta em produção está em andamento, o que significa que ainda não é possível realizar testes de ponta a ponta. A recuperação do token do dispositivo não funcionará até que sua operadora seja compatível. Nesta fase, toda a documentação do Silent Authentication Advanced serve principalmente como recurso informativo. Você pode usar o Operadora virtual para fins de desenvolvimento e teste.

Este guia explica como implementar a Autenticação Silenciosa Avançada no Android usando a API Vonage Verify. Para obter mais informações sobre a Autenticação Silenciosa Avançada, consulte o guia conceitual em Autenticação Silenciosa Avançada.

Atualmente, a Autenticação Silenciosa Avançada é compatível apenas com o Android, estando a compatibilidade com o iOS prevista para uma versão futura. Para a implementação em navegadores da web, consulte o guia em Autenticação Silenciosa Avançada para Navegadores da Web, que aborda o fluxo para computadores de mesa/laptops (código QR + proximidade via Bluetooth) e menciona a variante para navegadores móveis.

Atualmente, a Autenticação Silenciosa Avançada suporta apenas uma implementação assíncrona. É necessário configurar pontos de conexão de webhooks para receber os resultados da autenticação. O suporte à implementação síncrona está previsto para uma versão futura.

Pré-requisitos

Criar um aplicativo

Para começar, acesse o painel do desenvolvedor Para criar seu aplicativo:

  • Certifique-se de que a opção “Verify” esteja ativada na seção “Recursos”.
  • Configure a URL de status para receber eventos de retorno de chamada.
  • Gerar um JWT utilizando o ID do aplicativo e a chave privada do aplicativo.

Iniciar uma solicitação de verificação

Para iniciar o processo de verificação avançada da Autenticação Silenciosa, adicione o mode parâmetro para o fluxo de trabalho na sua solicitação de Verify.

O exemplo a seguir ilustra a estrutura da solicitação. Para obter uma implementação completa e executável, consulte o Verificar as especificações da API.

{
   "client_ref": "myPersonalRef",
   "brand": "ACME",
   "workflow": [
      {
         "channel": "silent_auth",
         "to": "'$VERIFY_NUMBER'",
         "mode": "advanced"
      },
      {
         "channel": "sms",
         "to": "'$VERIFY_NUMBER'"
      }
   ]
}

Nota: Se você estiver usando vários canais, o canal “Autenticação Silenciosa Avançada” deve ser o primeiro da lista no fluxo de trabalho. Atualmente, só é possível ter um único canal de Autenticação Silenciosa em um fluxo de trabalho.

Se a verificação avançada de autenticação silenciosa falhar, como em casos de falta de cobertura de rede, o Vonage Verify mudará automaticamente para canais de reserva se estiver definido no fluxo de trabalho, incluindo SMS ou chamada de voz.

Obter o token TS.43

É possível obter o token de autenticação TS.43 do chip de duas maneiras:

Como usar o Vonage Client SDK para Android

Você pode usar o nosso Client SDK do Android para obter o token de autenticação TS.43 do cartão SIM ou implementar diretamente o fluxo de desafio-resposta usando a API de telefonia.

Utilizando diretamente a API do Gerenciador de Credenciais do Android

  1. O backend do seu aplicativo cria uma solicitação OpenID4VP com DCQL para TS.43 (nonce, JWT do agregador, hints).
  2. Em seguida, o aplicativo envia uma solicitação à API do Gerenciador de Credenciais do Android. Nessa etapa, o usuário dá seu consentimento por meio da interface do usuário do sistema.
  3. O sistema de telefonia do Android gera uma credencial SD-JWT TS.43 criptografada a partir do servidor de autorizações da operadora, utilizando o cartão SIM.

Verifique o token

O exemplo a seguir ilustra a estrutura da solicitação:

{
   "token": "$TOKEN"
}

Nota: O parâmetro “token” é mutuamente exclusivo do parâmetro “code” e se aplica apenas à Autenticação Silenciosa Avançada.

Para concluir o processo de verificação, envie o token para o /v2/verify/:request_id ponto final. Consulte o Verificar as especificações da API para obter mais detalhes sobre solicitações e respostas.

Testes com o Operador Virtual

Nota: O Operador Virtual suporta apenas chamadas de API de back-end. Ele não simula o fluxo completo de troca de tokens de ponta a ponta com o dispositivo.

Durante a integração, utilize números +990 para garantir respostas determinísticas do Operador Virtual: números pares indicam sucesso, enquanto números ímpares indicam falha. Isso permitirá testar com segurança o retorno de chamada e o tratamento de erros. Para mais detalhes, consulte o Operadora virtual guia.

Leitura complementar