Verify as melhores práticas de segurança da API

A API Vonage Verify é um serviço seguro e confiável para verificação de números de telefone e autenticação multifatorial (MFA). No entanto, como qualquer sistema de autenticação, sua segurança geral depende igualmente de como sua aplicação de back-end se integra a ela. Este guia explica as considerações de segurança mais importantes que você deve levar em conta em sua própria implementação para proteger seus usuários.

Observação: As melhores práticas apresentadas neste guia se aplicam a todos os canais da API do Verify, incluindo SMS, voz, WhatsApp, autenticação silenciosa e qualquer outro canal compatível. Embora alguns exemplos façam referência aos fluxos de autenticação silenciosa, os princípios subjacentes são universais.

Entenda o modelo de confiança

A API Vonage Verify desempenha uma função específica: ela verifica se um determinado request_id e code O par está correto. O que o sistema não consegue fazer é determinar se a pessoa que enviou esse par é a mesma que originariamente solicitou a verificação.

Essa é uma distinção fundamental. A API Verify opera no nível da rede — ela não tem conhecimento algum sobre suas sessões de usuário, estado de login ou contexto do aplicativo. Seu backend é responsável por associar uma solicitação de verificação a um usuário e a uma sessão específicos. Se o seu backend não impor essa restrição, um invasor que obtenha um request_id e code par (proveniente de uma sessão diferente, de uma solicitação anterior ou por meio da interceptação de um fluxo do lado do cliente) pode usá-lo para se autenticar como qualquer número de telefone que desejar.

O modelo de segurança deve, portanto, ser entendido como duas camadas complementares:

  • Responsabilidade da Vonage: Gerando um valor criptograficamente correto code, entregá-lo com segurança e verificar o request_id/code par.
  • Sua responsabilidade: Garantir que o request_id e code os que são enviados para verificação são aqueles que seu backend iniciou para o usuário autenticado na sessão atual.

Sempre inicie a verificação no lado do servidor

Nunca permita que seu aplicativo cliente (aplicativo móvel, navegador ou front-end) inicie uma solicitação de verificação diretamente na API do Vonage Verify. Todas as chamadas para POST /v2/verify deve ser feita a partir do seu servidor de back-end.

Isso garante que:

  • Suas credenciais de API nunca são expostas ao cliente.
  • O número de telefone utilizado na verificação é aquele armazenado no seu sistema para esse usuário — e não um valor fornecido pelo cliente durante a execução.
  • Seu backend mantém controle total sobre o ciclo de vida da verificação.

Padrão incorreto (não faça isso):

Client → POST /v2/verify (directly to Vonage, with phone number from user input)

Padrão correto:

Client → POST /your-backend/start-verification
Backend → POST /v2/verify (to Vonage, using phone number from your database)
Backend stores request_id in session/database
Backend → returns request_id (or nothing) to client

Armazene o request_id no lado do servidor e vincule-o à sessão do usuário

Quando a API do Vonage Verify responde a uma solicitação de início de verificação, ela retorna um request_id. Esse valor deve ser armazenado com segurança no seu backend — por exemplo, em uma sessão do lado do servidor ou em um registro no banco de dados — e vinculado explicitamente a:

  • O usuário ou a Account específica que está iniciando a verificação.
  • O número de telefone está sendo verificado.
  • A sessão ou transação de autenticação atual.

Quando o cliente enviar posteriormente um código para verificação, seu backend deve:

  1. Recuperar o request_id a partir de sua própria sessão/banco de dados (não do cliente).
  2. Ligar POST /v2/verify/{request_id} utilizando apenas os dados armazenados no servidor request_id.

Nunca aceite o request_id como informação fornecida pelo cliente. Se o seu backend aceita o request_id a partir de uma solicitação do cliente e a encaminha diretamente para a Vonage, um invasor pode fornecer um request_id de qualquer verificação válida anterior — incluindo uma referente a um número de telefone diferente ou a um usuário diferente — e a API retornará uma validação bem-sucedida.

Exemplo de implementação correta (Node.js/Express):

// Start verification — called from your app backend only
app.post('/start-verification', async (req, res) => {
  const user = await getUserFromSession(req.session.userId);

  // Phone number comes from YOUR database, not the client request
  const { request_id } = await vonage.verify.start({
    brand: 'YourApp',
    workflow: [{ channel: 'sms', to: user.phoneNumber }]
  });

  // Store request_id server-side, bound to the user session
  req.session.pendingVerification = {
    request_id,
    phoneNumber: user.phoneNumber,
    userId: user.id,
    createdAt: Date.now()
  };

  res.json({ status: 'verification_started' });
});

// Check code — request_id is retrieved from session, never from client
app.post('/check-code', async (req, res) => {
  const { code } = req.body;
  const pending = req.session.pendingVerification;

  if (!pending || !pending.request_id) {
    return res.status(400).json({ error: 'No active verification for this session' });
  }

  const result = await vonage.verify.check(pending.request_id, code);

  if (result.status === 'completed') {
    // Clear the pending verification after success
    delete req.session.pendingVerification;
    res.json({ verified: true });
  } else {
    res.status(401).json({ verified: false });
  }
});

Nunca confie em parâmetros fornecidos pelo cliente para tomar decisões de segurança

Seu aplicativo cliente pode enviar dados para o seu backend como parte do fluxo de verificação (por exemplo, um request_id devolvidos ao cliente para uso em um redirecionamento de autenticação silenciosa). Trate todos esses valores como entradas não confiáveis:

  • Não utilizar um fornecido pelo cliente request_id para chamar o endpoint de verificação “Verify”.
  • Não utilizar um número de telefone fornecido pelo cliente para determinar qual usuário está sendo verificado.
  • Não depender do estado do lado do cliente para determinar se uma verificação foi bem-sucedida.

O papel do cliente se limita a: acionar ações no seu backend (por meio de chamadas de API autenticadas ao seu próprio servidor) e, no caso da Autenticação Silenciosa, executar o check_url redirecionar pela rede da operadora de celular. Seu backend deve rastrear e verificar o resultado de forma independente.

Implementar o gerenciamento do ciclo de vida da verificação por sessão

Cada tentativa de verificação deve se limitar a uma única sessão e a um único usuário. Implemente os seguintes controles de ciclo de vida em seu backend:

  • Uma solicitação ativa por usuário: Antes de iniciar uma nova verificação, verifique se há alguma pendente request_id já existe para esse usuário. Cancele-a ou deixe-a expirar antes de criar uma nova.
  • Prazo curto para solicitações pendentes: Se o usuário não concluir a verificação dentro de um intervalo de tempo razoável (por exemplo, 5 minutos), invalide o valor armazenado na sessão request_id no seu backend e exigem uma nova verificação para serem iniciados.
  • Consumo de uso único: Assim que a verificação for concluída com sucesso, remova imediatamente o request_id da sua sessão/banco de dados. Um request_id nunca devem ser reutilizáveis dentro do seu aplicativo.
  • Invalidar após tentativas malsucedidas: Após um número configurável de tentativas malsucedidas de envio do código, cancele a solicitação de verificação e exija que o usuário recomece.

Aplicar limitação de taxa no nível do aplicativo

Embora a API do Vonage Verify inclua proteções antifraude integradas, você também deve implementar a limitação de taxa em seu próprio aplicativo para reduzir o risco de ataques de enumeração, inundação ou força bruta:

  • Limitar as solicitações de verificação por número de telefone: Limitar o número de solicitações de verificação que podem ser iniciadas para um determinado número de telefone dentro de um intervalo de tempo (por exemplo, no máximo 3 solicitações por hora).
  • Limitar o número de solicitações por Account de usuário ou endereço IP: Evitar que uma única conta ou origem gere um número excessivo de solicitações de verificação.

Esses controles são distintos — e complementares — ao sistema de limitação de taxa e antifraude da Vonage, implementado no nível da plataforma. Para obter mais detalhes sobre as proteções contra fraudes integradas da Vonage, consulte o Guia do Sistema Antifraude.

Diferenciar o cadastro da verificação

Existem dois momentos distintos em que a verificação de números de telefone é utilizada em applications comuns:

  1. Inscrição (registro de um número de telefone para a autenticação de duas etapas): O usuário está adicionando um novo número de telefone à sua conta. Isso geralmente é feito uma única vez e deve estar associado ao registro da conta do usuário autenticado.
  2. Verificação (usando a autenticação de dois fatores no login): O usuário está comprovando que ainda é o titular do número de telefone cadastrado no momento do registro.

Esses dois fluxos exigem controles de segurança diferentes:

Durante registro, verifique se o número de telefone que está sendo cadastrado ainda não está associado a outra conta e certifique-se de que o usuário esteja autenticado antes de adicionar o número.

Durante verificação no login, certifique-se de que o número de telefone utilizado na solicitação da API Verify corresponda ao número armazenado em seu banco de dados para esse usuário — nunca ao fornecido pelo cliente no momento do login. Um invasor que conheça o número de telefone de um usuário não deve ser capaz de acionar uma solicitação de verificação em nome dele.

Orientações adicionais para a autenticação silenciosa

A Autenticação Silenciosa introduz um fluxo específico de redirecionamento em várias etapas, no qual o check_url deve ser seguido pelo dispositivo móvel do usuário pela rede da operadora. É necessário ter um cuidado especial:

  • Guarde o request_id imediatamente depois de ligar /v2/verify e antes de enviar qualquer resposta ao cliente. Vincule-a à sessão do usuário, conforme descrito no Guarde o request_id Do lado do servidor e vincular à sessão do usuário.
  • Não ultrapasse o request_id ao cliente a menos que seja estritamente necessário para o fluxo de redirecionamento da Autenticação Silenciosa. Se for necessário passá-lo (para que o cliente siga o check_url), trate-o como um token de curta duração e de uso único e verifique-o em relação à sua sessão na etapa de verificação do código.
  • Forçar o uso de dados móveis para o redirecionamento: O check_url deve ser realizada pela rede da operadora de celular, e não por Wi-Fi. Se a solicitação for feita por Wi-Fi, ocorrerá um erro e a comprovação de posse do SIM no nível da operadora será perdida. Use o SDK da Vonage para Android ou iOS para garantir isso ao desenvolver aplicativos móveis nativos. Os SDKs também oferecem verificações de conectividade integradas, gerenciamento de tempo limite em redirecionamentos (até 10 redirecionamentos, com tempo limite de 5 segundos cada) e exceções tipadas que permitem que você responda às falhas com precisão. Consulte o Guia de Melhores Práticas para Autenticação Silenciosa para obter detalhes sobre a implementação.
  • Verifique se há conexão de dados móveis antes de iniciar a autenticação silenciosa: Se o dispositivo não tiver uma conexão de dados móveis ativa, não inicie a etapa de Autenticação Silenciosa. Em vez disso, passe diretamente para o próximo canal em seu fluxo de trabalho (SMS, voz etc.). Iniciar uma solicitação de Autenticação Silenciosa sem dados móveis resultará em falha e adicionará latência desnecessária antes que o canal alternativo seja acionado. O SDK da Vonage gera uma sdk_no_data_connectivity exceção quando essa condição for detectada durante a execução — seu aplicativo deve detectar isso e agir imediatamente, em vez de esperar pelo tempo limite padrão de 60 segundos.
  • Lidar com exceções do SDK e acionar o failover do backend imediatamente: Se o SDK lançar uma exceção durante o fluxo de autenticação silenciosa (por exemplo, sdk_no_data_connectivity, sdk_connection_error, ou sdk_redirect_error), seu aplicativo móvel deve notificar seu backend imediatamente. Seu backend deve, então, chamar o POST /v2/verify/{request_id}/next_workflow ponto final para avançar a verificação para o próximo canal sem esperar. Se nenhuma ação for realizada, a plataforma atingirá automaticamente o tempo limite após 60 segundos e passará para o próximo fluxo de trabalho — mas acionar isso a partir do seu backend minimiza imediatamente o tempo de espera do usuário e mantém o ciclo de vida da verificação sob seu controle, em consonância com o Implementar o gerenciamento do ciclo de vida da verificação por sessão. Não confie que o cliente resolva o problema por conta própria: o tratamento de exceções deve resultar em uma transição de estado impulsionada pelo backend.
  • Sempre confirme o resultado no lado do servidor: Não confie na informação de sucesso informada pelo cliente a partir do redirecionamento da Autenticação Silenciosa. Seu backend deve receber o status final da verificação e tomar a decisão de autorização de forma independente.

Lista de verificação resumida

Antes de implantar uma integração da API do Verify em produção, verifique o seguinte:

  • Todas as chamadas para POST /v2/verify são feitas exclusivamente no lado do servidor.
  • O número de telefone na solicitação de verificação vem do seu banco de dados, e não de informações fornecidas pelo cliente.
  • O request_id é armazenado no servidor (em sessão ou no banco de dados) e nunca é aceito pelo cliente.
  • O request_id está vinculado ao usuário específico e à sessão que iniciou a verificação.
  • As verificações pendentes são invalidadas após um determinado prazo.
  • As verificações concluídas ou com falha são removidas imediatamente.
  • A limitação de taxa no nível do aplicativo está em vigor por número de telefone, por usuário e por endereço IP.
  • Os fluxos de cadastro e verificação de login são tratados separadamente, com verificações de segurança distintas.
  • Os fluxos de redirecionamento da autenticação silenciosa são executados por meio de dados de celular, e os resultados são confirmados no lado do servidor.

Recursos relacionados