Implementação síncrona de autenticação silenciosa

Introdução

Este guia explica como implementar a autenticação silenciosa usando a abordagem síncrona, na qual seu backend aguarda uma resposta direta após redirecionar o usuário.

Observação: se estiver usando uma implementação síncrona, ativar os recursos Verify no painel do aplicativo é opcional, já que isso apenas altera a capacidade de receber webhooks de status (que não são necessários para uma implementação síncrona).

O diagrama a seguir mostra as etapas necessárias para implementar a versão síncrona da Autenticação Silenciosa:

Solicitar código de verificação

Para iniciar o processo de autenticação silenciosa, envie uma solicitação para /verify ponto final. No exemplo a seguir, o fluxo de trabalho especifica que o Verify tentará, em primeiro lugar, utilizar a autenticação silenciosa. Se, por qualquer motivo, a solicitação falhar, ele recorrerá ao SMS e, em seguida, a uma senha de uso único (OTP) por chamada de voz.

Observação: ao usar vários canais, autenticação silenciosa deve ser o primeiro canal no fluxo de trabalho.

Para executar o exemplo, substitua as seguintes variáveis no código de exemplo pelos seus próprios valores:

Variável Descrição
JWT Autentica a solicitação da API usando JWT.
VERIFY_BRAND_NAME O nome da sua empresa ou serviço, exibido ao usuário na mensagem de verificação.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Chave privada do seu aplicativo.
VONAGE_APPLICATION_ID ID do seu aplicativo.
VERIFY_NUMBER O número de telefone para o qual a OTP deve ser enviada, no formato E.164 (por exemplo, +44111223344).

Escreva o código

Adicione o seguinte ao arquivo ` request.sh`:

curl -X POST "https://api.nexmo.com/v2/verify" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
	 "brand": "'$VERIFY_BRAND_NAME'",
   "workflow": [
      {
         "channel": "silent_auth",
         "to": "'$VERIFY_NUMBER'"
      },
      {
         "channel": "sms",
         "to": "'$VERIFY_NUMBER'"
      },
      {
         "channel": "voice",
         "to": "'$VERIFY_NUMBER'"
      }
   ]
}'

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

sh request.sh

Pré-requisitos

npm install @vonage/server-sdk @vonage/verify2

Crie um arquivo chamado ` send-request-with-fallback.js ` e insira o seguinte código:

const { Vonage } = require('@vonage/server-sdk');
const { Channels, SilentAuthChannel } = require('@vonage/verify2');

const vonage = new Vonage({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` send-request-with-fallback.js`:

vonage.verify2.newRequest({
  brand: VERIFY_BRAND_NAME,
  workflow: [
    {
      channel: SilentAuthChannel.SILENT_AUTH,
      to: VERIFY_NUMBER,
    },
    {
      channel: Channels.SMS,
      to: VERIFY_NUMBER,
    },
    {
      channel: Channels.VOICE,
      to: VERIFY_NUMBER,
    },
  ],
})
  .then(({requestId}) => console.log(requestId))
  .catch((err) => console.error(err));

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

node send-request-with-fallback.js

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

Crie um arquivo chamado ` SendVerificationRequestWithFallback ` e adicione o código a seguir ao método ` main `:

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` SendVerificationRequestWithFallback `:

val response = client.verify.sendVerification(VERIFY_BRAND_NAME) {
    silentAuth(VERIFY_NUMBER)
    sms(VERIFY_NUMBER)
    voice(VERIFY_NUMBER)
}

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.kt.verify ` pelo pacote que contém ` SendVerificationRequestWithFallback`:

gradle run -Pmain=com.vonage.quickstart.kt.verify.SendVerificationRequestWithFallback

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

implementation 'com.vonage:server-sdk:9.3.1'

Crie um arquivo chamado ` SendRequestWithFallback ` e adicione o código a seguir ao método ` main `:

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` SendRequestWithFallback `:

VerificationResponse response = client.getVerify2Client().sendVerification(
		VerificationRequest.builder()
			.addWorkflow(new SilentAuthWorkflow(VERIFY_NUMBER))
			.addWorkflow(new SmsWorkflow(VERIFY_NUMBER))
			.addWorkflow(new VoiceWorkflow(VERIFY_NUMBER))
			.brand(VERIFY_BRAND_NAME).build()
);

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.verify2 ` pelo pacote que contém ` SendRequestWithFallback`:

gradle run -Pmain=com.vonage.quickstart.verify2.SendRequestWithFallback

Pré-requisitos

Install-Package Vonage

Crie um arquivo chamado ` StartVerificationRequestWithFallback.cs ` e insira o seguinte código:

using Vonage;
using Vonage.Request;
using Vonage.VerifyV2.StartVerification;
using Vonage.VerifyV2.StartVerification.Sms;
using Vonage.VerifyV2.StartVerification.Voice;
using Vonage.VerifyV2.StartVerification.SilentAuth;

Ver código-fonte completo

Adicione o seguinte ao arquivo ` StartVerificationRequestWithFallback.cs`:

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` StartVerificationRequestWithFallback.cs`:

var request = StartVerificationRequest.Build()
    .WithBrand(BRAND_NAME)
    .WithWorkflow(SilentAuthWorkflow.Parse(TO_NUMBER))
    .WithFallbackWorkflow(SmsWorkflow.Parse(TO_NUMBER))
    .WithFallbackWorkflow(VoiceWorkflow.Parse(TO_NUMBER))
    .Create();
var response = await client.VerifyV2Client.StartVerificationAsync(request);

Ver código-fonte completo

Pré-requisitos

composer require vonage/client

Crie um arquivo chamado ` request.php ` e insira o seguinte código:

$client = new Vonage\Client(
    new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` request.php`:

$newRequest = new \Vonage\Verify2\Request\SilentAuthRequest(VERIFY_NUMBER, VERIFY_BRAND_NAME);
$smsWorkflow = new \Vonage\Verify2\VerifyObjects\VerificationWorkflow(\Vonage\Verify2\VerifyObjects\VerificationWorkflow::WORKFLOW_SMS, VERIFY_NUMBER);
$newRequest->addWorkflow($smsWorkflow);
$voiceWorkflow = new \Vonage\Verify2\VerifyObjects\VerificationWorkflow(\Vonage\Verify2\VerifyObjects\VerificationWorkflow::WORKFLOW_VOICE, VERIFY_NUMBER);
$newRequest->addWorkflow($voiceWorkflow);

$client->verify2()->startVerification($newRequest);

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

php request.php

Pré-requisitos

pip install vonage python-dotenv

Escreva o código

Adicione o seguinte ao arquivo ` send-request-with-fallback.py`:

from vonage import Auth, Vonage
from vonage_verify import (SmsChannel, VoiceChannel, SilentAuthChannel,
                           StartVerificationResponse, VerifyRequest)

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

verify_request = VerifyRequest(
    brand=VERIFY_BRAND_NAME,
    workflow=[
        SilentAuthChannel(to=VERIFY_NUMBER),
        SmsChannel(to=VERIFY_NUMBER),
        VoiceChannel(to=VERIFY_NUMBER),
    ],
)

response: StartVerificationResponse = client.verify.start_verification(verify_request)
pprint(response)

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

python verify/send-request-with-fallback.py

Pré-requisitos

gem install vonage

Crie um arquivo chamado ` request.rb ` e insira o seguinte código:

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` request.rb`:

client.verify2.start_verification(
  brand: VERIFY_BRAND_NAME,
  workflow: [
    {
      channel: 'silent_auth',
      to: VERIFY_NUMBER
    },
    {
      channel: 'sms',
      to: VERIFY_NUMBER
    },
    {
      channel: 'voice',
      to: VERIFY_NUMBER
    }
  ]
)

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

ruby request.rb

Se a solicitação for bem-sucedida e o número for compatível, você receberá um 200 Ok resposta contendo um request_id e um check_url no corpo:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "check_url": "https://api.nexmo.com/v2/verify/31eaf23d-b2db-4c42-9d1d-e847e75ab330/silent-auth/redirect"
}

Até que a solicitação expire ou seja cancelada, check_url pode ser usado para realizar uma verificação de autenticação silenciosa. Ao receber essa resposta, é necessário enviar uma solicitação GET para o check_url a partir do dispositivo móvel no qual você está tentando se autenticar.

Importante: O check_url A solicitação deve ser executada por meio de uma conexão de dados móveis (não por Wi-Fi). A maneira recomendada de garantir isso é usar o Vonage Client SDK (iOS ou Android), que encaminha automaticamente a solicitação pela rede celular do dispositivo. Consulte o Guia para autenticação silenciosa sem Wi-Fi para mais detalhes.

Depois de enviar a solicitação GET, você receberá uma série de respostas HTTP 302 redireciona dependendo do território e da operadora que o dispositivo de destino está utilizando:

HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect

Seguir os redirecionamentos resultará em: HTTP 200 ou HTTP 409 resposta, dependendo se a solicitação é válida. Se houver algum problema com a rede, você verá uma resposta como esta:

HTTP/1.1 409 CONFLICT
Content-Type: application/json

{
  "title": "Network error",
  "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."
}

Uma lista completa dos possíveis códigos de erro pode ser encontrada no Especificação da API.

Se a solicitação for válida, você receberá um HTTP 200 resposta contendo o seu request_id e um code:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "code": "si9sfG"
}

Observação: Para garantir uma verificação de autenticação segura e mitigar o risco de um possível ataque do tipo “man-in-the-middle”, armazene o original request_id e comparar com o request_id retornados na resposta. Se os IDs não corresponderem, a verificação de autenticação silenciosa deve ser interrompida. Consulte nosso exemplo de inscrição para ver um exemplo de implementação de como mitigar esse ataque.

Verifique o código de verificação fornecido

Assim que o usuário final receber o código, você deve enviar uma solicitação POST para o /v2/verify/{request_id} ponto final, substituindo {request_id} com o número de identificação que você recebeu na ligação anterior.

Para executar o exemplo, substitua as seguintes variáveis no código de exemplo pelos seus próprios valores:

Variável Descrição
JWT Autentica a solicitação da API usando JWT.
VERIFY_REQUEST_ID O request_id recebido na etapa anterior.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Chave privada do seu aplicativo.
VONAGE_APPLICATION_ID ID do seu aplicativo.
VERIFY_CODE O código de verificação recebido pelo usuário final

Escreva o código

Adicione o seguinte ao arquivo ` check-verification-code.sh`:

curl -X POST "https://api.nexmo.com/v2/verify/$VERIFY_REQUEST_ID" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "'$VERIFY_CODE'"
  }'

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

sh check-verification-code.sh

Pré-requisitos

npm install @vonage/server-sdk

Crie um arquivo chamado ` check-verification-code.js ` e insira o seguinte código:

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage ({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` check-verification-code.js`:

vonage.verify2.checkCode(VERIFY_REQUEST_ID, VERIFY_CODE)
  .then((status) => console.log(`The status is ${status}`),
  )
  .catch((err) => console.error(err));

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

node check-verification-code.js

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

Crie um arquivo chamado ` CheckVerificationCode ` e adicione o código a seguir ao método ` main `:

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` CheckVerificationCode `:

if (client.verify.request(VERIFY_REQUEST_ID).isValidVerificationCode(VERIFY_CODE)) {
    println("Code matches.")
}

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.kt.verify ` pelo pacote que contém ` CheckVerificationCode`:

gradle run -Pmain=com.vonage.quickstart.kt.verify.CheckVerificationCode

Pré-requisitos

Adicione o seguinte ao arquivo ` build.gradle`:

implementation 'com.vonage:server-sdk:9.3.1'

Crie um arquivo chamado ` CheckVerificationCode ` e adicione o código a seguir ao método ` main `:

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao método ` main ` do arquivo ` CheckVerificationCode `:

try {
	client.getVerify2Client().checkVerificationCode(VERIFY_REQUEST_UUID, VERIFY_CODE);
	System.out.println("SUCCESS - code matches!");
}
catch (VerifyResponseException ex) {
	switch (ex.getStatusCode()) {
		case 400: // Code does not match
		case 404: // Already verified or not found
		case 409: // Workflow does not support code
		case 410: // Incorrect code provided too many times
		case 429: // Rate limit exceeded
		default:  // Unknown or internal server error (500)
			ex.printStackTrace();
	}
}

Ver código-fonte completo

Execute seu código

Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.verify2 ` pelo pacote que contém ` CheckVerificationCode`:

gradle run -Pmain=com.vonage.quickstart.verify2.CheckVerificationCode

Pré-requisitos

Install-Package Vonage

Crie um arquivo chamado ` VerifyCodeRequest.cs ` e insira o seguinte código:

using Vonage;
using Vonage.Request;

Ver código-fonte completo

Adicione o seguinte ao arquivo ` VerifyCodeRequest.cs`:

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` VerifyCodeRequest.cs`:

var request = Vonage.VerifyV2.VerifyCode.VerifyCodeRequest.Build()
    .WithRequestId(REQUEST_ID)
    .WithCode(CODE)
    .Create();
var response = await client.VerifyV2Client.VerifyCodeAsync(request);

Ver código-fonte completo

Pré-requisitos

composer require vonage/client

Crie um arquivo chamado ` send_code.php ` e insira o seguinte código:

$client = new Vonage\Client(
    new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` send_code.php`:

try {
    $client->verify2()->check(REQUEST_ID, CODE);
} catch (\Exception $e) {
    var_dump($e->getMessage());
}

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

php send_code.php

Pré-requisitos

pip install vonage python-dotenv

Escreva o código

Adicione o seguinte ao arquivo ` check-verification-code.py`:

from vonage import Auth, Vonage
from vonage_verify import CheckCodeResponse

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

response: CheckCodeResponse = client.verify.check_code(
    request_id=VERIFY_REQUEST_ID, code=VERIFY_CODE
)
print(response)

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

python verify/check-verification-code.py

Pré-requisitos

gem install vonage

Crie um arquivo chamado ` check.rb ` e insira o seguinte código:

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

Ver código-fonte completo

Escreva o código

Adicione o seguinte ao arquivo ` check.rb`:

client.verify2.check_code(
  request_id: VERIFY_REQUEST_ID,
  code: VERIFY_CODE
)

Ver código-fonte completo

Execute seu código

Salve este arquivo no seu computador e execute-o:

ruby check.rb

Observação: um código para um fluxo de trabalho de autenticação silenciosa só pode ser verificado uma vez.

Se o código for válido, você receberá uma resposta final com o status completed:

{
   "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
   "status": "completed"
}

Ou, se houver um erro, você verá “Código inválido”:

{
   "title": "Invalid Code",
   "type": "https://www.developer.vonage.com/api-errors/verify#invalid-code",
   "detail": "The code you provided does not match the expected value.",
   "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Neste momento, a verificação da autenticação silenciosa está concluída.

Recursos relacionados