Autenticación silenciosa Implementación sincrónica

Introducción

Esta guía explica cómo implementar la autenticación silenciosa utilizando el enfoque síncrono, en el que su backend espera una respuesta directa después de redirigir al usuario.

Nota: si se utiliza una implementación síncrona, activar la opción «Verify capacidades» en el panel de control de la aplicación es opcional, ya que esto solo activa la posibilidad de recibir webhooks de estado (que no son necesarios para una implementación sincrónica).

El siguiente diagrama muestra los pasos necesarios para implementar la versión síncrona de la autenticación silenciosa:

Solicitar código de verificación

Para iniciar el proceso de autenticación silenciosa, envía una solicitud a /verify punto final. En el siguiente ejemplo, el flujo de trabajo especifica que Verify intentará utilizar primero la autenticación silenciosa. Si por alguna razón la solicitud falla, se recurrirá a SMS, seguido de una llamada de voz OTP.

Nota: si se utilizan varios canales, autenticación silenciosa debe ser el primer canal del flujo de trabajo.

Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:

Variable Descripción
JWT Autentica la solicitud de API utilizando JWT.
VERIFY_BRAND_NAME El nombre de tu empresa o servicio, que se muestra al usuario en el mensaje de verificación.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Clave privada de su aplicación.
VONAGE_APPLICATION_ID ID de su solicitud.
VERIFY_NUMBER El número de teléfono al que se debe enviar la contraseña de un solo uso (OTP), en formato E.164 (p. ej., +44111223344).

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

sh request.sh

Requisitos previos

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

Crea un archivo llamado send-request-with-fallback.js y añade el siguiente 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 fuente completa

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

node send-request-with-fallback.js

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado SendVerificationRequestWithFallback y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo SendVerificationRequestWithFallback:

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

Ver fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.kt.verify por el paquete que contiene SendVerificationRequestWithFallback:

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

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado SendRequestWithFallback y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo 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 fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.verify2 por el paquete que contiene SendRequestWithFallback:

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

Requisitos previos

Install-Package Vonage

Crea un archivo llamado StartVerificationRequestWithFallback.cs y añade el siguiente 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 fuente completa

Añada lo siguiente a StartVerificationRequestWithFallback.cs:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a 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 fuente completa

Requisitos previos

composer require vonage/client

Crea un archivo llamado request.php y añade el siguiente código:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

php request.php

Requisitos previos

pip install vonage python-dotenv

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

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

Requisitos previos

gem install vonage

Crea un archivo llamado request.rb y añade el siguiente código:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

ruby request.rb

Si la solicitud tiene éxito y el número es compatibleRecibirá un 200 Ok que contiene una respuesta request_id y un check_url en el cuerpo:

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

Hasta que la solicitud caduque o se anule, check_url se puede utilizar para realizar una comprobación de autenticación silenciosa. Al recibir esta respuesta, debe realizar una solicitud GET a la carpeta check_url del dispositivo móvil que está intentando autenticar.

Importante: En check_url debe ejecutarse a través de una conexión de datos móviles (no Wi-Fi). La forma recomendada de asegurar esto es usar el Vonage Client SDK (iOS o Android), que enruta automáticamente la solicitud a través de la red celular del dispositivo. Consulta la Guía para la autenticación silenciosa sin pasar por la red Wi-Fi Para más información.

Una vez que hayas realizado la solicitud GET, recibirás una serie de respuestas HTTP 302 redirige en función del territorio y del operador que utilice el dispositivo de destino:

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

Siguiendo los redireccionamientos se producirá un HTTP 200 o HTTP 409 La respuesta dependerá de si la solicitud es válida. Si hay algún problema con la red, verás una respuesta 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."
}

En el siguiente documento se puede consultar una lista completa de los posibles códigos de error: Especificación API.

Si la solicitud es válida, recibirá un HTTP 200 respuesta que contenga tu request_id y un code:

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

Nota: Para garantizar una verificación de autenticación segura y mitigar el riesgo de un posible ataque de «hombre en medio», guarda el original request_id y compárelo con el request_id devuelta en la respuesta. Si los ID no coinciden, la comprobación de autenticación silenciosa debe interrumpirse. Consulta nuestra ejemplo de solicitud para ver un ejemplo de implementación de cómo mitigar el ataque.

Comprobar el código de verificación suministrado

Una vez que el usuario final recibe el código, debe enviar una solicitud POST a la dirección /v2/verify/{request_id} punto final, sustituyendo {request_id} con el ID que recibió en la llamada anterior.

Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:

Variable Descripción
JWT Autentica la solicitud de API utilizando JWT.
VERIFY_REQUEST_ID El request_id recibido en el paso anterior.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Clave privada de su aplicación.
VONAGE_APPLICATION_ID ID de su solicitud.
VERIFY_CODE El código de verificación recibido por el usuario final

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

sh check-verification-code.sh

Requisitos previos

npm install @vonage/server-sdk

Crea un archivo llamado check-verification-code.js y añade el siguiente código:

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

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

Ver fuente completa

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

node check-verification-code.js

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado CheckVerificationCode y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo CheckVerificationCode:

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

Ver fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.kt.verify por el paquete que contiene CheckVerificationCode:

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

Requisitos previos

Añada lo siguiente a build.gradle:

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

Crea un archivo llamado CheckVerificationCode y añade el siguiente código al método main:

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

Ver fuente completa

Escriba el código

Añada lo siguiente al método main del archivo 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 fuente completa

Ejecute su código

Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:

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

Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.verify2 por el paquete que contiene CheckVerificationCode:

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

Requisitos previos

Install-Package Vonage

Crea un archivo llamado VerifyCodeRequest.cs y añade el siguiente código:

using Vonage;
using Vonage.Request;

Ver fuente completa

Añada lo siguiente a VerifyCodeRequest.cs:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a VerifyCodeRequest.cs:

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

Ver fuente completa

Requisitos previos

composer require vonage/client

Crea un archivo llamado send_code.php y añade el siguiente código:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a send_code.php:

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

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

php send_code.php

Requisitos previos

pip install vonage python-dotenv

Escriba el código

Añada lo siguiente a 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 fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

python verify/check-verification-code.py

Requisitos previos

gem install vonage

Crea un archivo llamado check.rb y añade el siguiente código:

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

Ver fuente completa

Escriba el código

Añada lo siguiente a check.rb:

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

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

ruby check.rb

Nota: un código para un flujo de trabajo de autenticación silenciosa sólo puede comprobarse una vez.

Si el código es válido, recibirás una respuesta final con el estado completed:

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

O, si hay un error, verá "Código no vá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"
}

En este momento, la verificación de la autenticación silenciosa ha finalizado.

Recursos relacionados