Authentification silencieuse Mise en œuvre asynchrone

Introduction

Une implémentation asynchrone est très similaire à la méthode synchrone au lieu d'utiliser le client de l'appareil pour effectuer une série d'appels, chaque partie du flux de travail est incluse dans la méthode rappels de webhook envoyé à une URL que vous définissez.

Ce guide explique comment mettre en œuvre l'authentification silencieuse en utilisant l'approche asynchrone, où votre backend met en place un callback pour recevoir le résultat de l'authentification.

Créer une application

Pour commencer, rendez-vous sur le site tableau de bord du développeur pour créer votre application :

  • Assurez-vous que l'option Verify est activée sous "Capacités".
  • Configurez l'URL d'état pour qu'elle reçoive les événements de rappel.
  • Générer un JWT en utilisant l'identifiant de l'application et la clé privée de l'application.

Vérification du déclenchement

Pour lancer la procédure d'authentification silencieuse, adressez une demande à /verify. Dans l'exemple suivant, le flux de travail spécifie que Verify tentera d'abord d'utiliser l'authentification silencieuse. Si la demande échoue pour quelque raison que ce soit, il passera au SMS, puis à l'OTP par appel vocal.

Pour exécuter l'exemple, remplacez les variables suivantes dans le code d'exemple par vos propres valeurs :

Variable Description
JWT Authentifie la demande d'API à l'aide de JWT.
VERIFY_BRAND_NAME Le nom de votre entreprise ou de votre service, indiqué à l'utilisateur dans le message de vérification.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Chemin d'accès à la clé privée de votre application.
VONAGE_APPLICATION_ID ID de l'application de votre demande.
VERIFY_NUMBER Le numéro de téléphone auquel envoyer l'OTP, au format E.164 (par ex, +441112233447).

Rédiger le code

Ajouter ce qui suit à 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'"
      }
   ]
}'

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

sh request.sh

Conditions préalables

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

Créez un fichier nommé send-request-with-fallback.js et ajoutez le code suivant :

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,
});

Voir la source complète

Rédiger le code

Ajouter ce qui suit à 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));

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

node send-request-with-fallback.js

Conditions préalables

Ajouter ce qui suit à build.gradle:

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

Créez un fichier nommé SendVerificationRequestWithFallback et ajoutez le code suivant à la méthode main:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier SendVerificationRequestWithFallback:

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

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin application pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

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

Lancez la commande suivante gradle pour exécuter votre application, en remplaçant com.vonage.quickstart.kt.verify par le paquet contenant SendVerificationRequestWithFallback:

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

Conditions préalables

Ajouter ce qui suit à build.gradle:

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

Créez un fichier nommé SendRequestWithFallback et ajoutez le code suivant à la méthode main:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier 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()
);

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin application pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

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

Lancez la commande suivante gradle pour exécuter votre application, en remplaçant com.vonage.quickstart.verify2 par le paquet contenant SendRequestWithFallback:

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

Conditions préalables

Install-Package Vonage

Créez un fichier nommé StartVerificationRequestWithFallback.cs et ajoutez le code suivant :

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

Voir la source complète

Ajouter ce qui suit à StartVerificationRequestWithFallback.cs:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à 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);

Voir la source complète

Conditions préalables

composer require vonage/client

Créez un fichier nommé request.php et ajoutez le code suivant :

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à 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);

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

php request.php

Conditions préalables

pip install vonage python-dotenv

Rédiger le code

Ajouter ce qui suit à 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)

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

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

Conditions préalables

gem install vonage

Créez un fichier nommé request.rb et ajoutez le code suivant :

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à 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
    }
  ]
)

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

ruby request.rb

Réponse

Si la demande aboutit, la réponse renverra HTTP 200 avec le check_url dans le corps, dont nous aurons besoin à l'étape suivante :

HTTP/1.1 200 Ok 
{
  "request_id": "470b478f-334c-4f6f-b90d-b44e77ed24bf",
  "check_url": "https://api-eu-4.vonage.com/v2/verify/470b478f-334c-4f6f-aaab-b4a342aed24bf/silent-auth/redirect"
}

En cas d'erreur dans la demande, par exemple un numéro de téléphone mal formaté, la réponse contiendra un message de type HTTP 422 erreur comme celle-ci :

HTTP/1.1 422 Unprocessable Entity 
{
  "title": "Invalid params",
  "detail": "The value of one or more parameters is invalid",
  "instance": "b30db5a7-338e-402e-aa5a-40073a9aa07c",
  "type": "https://developer.vonage.com/en/api-errors#invalid-params",
  "invalid_parameters": [
    {
      "name": "workflow[0]",
      "reason": "`to` Phone number is invalid"
    }
  ]
}

Comme nous utilisons la mise en œuvre asynchrone, vous recevrez, parallèlement à la réponse de l'API, un message de type rappel (ou webhook) à l'URL spécifiée dans les paramètres de votre application de tableau de bord, vous informant de la progression de la demande.

Lors de l'appel de l'API à /verifyL'API Verify effectue des vérifications préalables internes. Si tout est en ordre, le rappel contiendra le corps suivant :

HTTP/1.1 200 Ok 
{
  "request_id": "21a425df-04b2-43f2-990e-b19ee22e18a0",
  "triggered_at": "2025-07-14T17:01:47.032Z",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://api-eu-4.vonage.com/v2/verify/21a425df-04b2-43f2-990e-b19ee22e18a0/silent-auth/redirect"
  },
  "type": "event"
}

Jusqu'à ce que la demande expire ou soit annulée, check_url sera utilisé pour effectuer une vérification de l'authentification silencieuse par envoi de l'URL d'authentification. Après avoir reçu ce rappel, vous devez adresser une demande GET à l'adresse suivante check_url de l'appareil mobile que vous essayez d'authentifier.

Important : Les check_url doit être exécutée via une connexion de données mobiles (et non Wi-Fi). La façon recommandée de s'en assurer est d'utiliser le Client SDK de Vonage (iOS ou Android), qui achemine automatiquement la demande par le réseau cellulaire de l'appareil. Voir la page Guide de contournement du Wi-Fi pour l'authentification silencieuse pour plus de détails.

Si l'un de ces contrôles préalables échoue, par exemple en raison d'une erreur de réseau ou d'un opérateur non pris en charge, le rappel se présentera comme suit :

HTTP/1.1 200 Ok 
{
  request_id: "470b478f-334c-4f6f-b90d-b44e77ed24bf",
  triggered_at: "2025-07-14T16:53:16.965Z",
  channel: "silent_auth",
  status: "failed",
  type: "event"
}

Si votre /verify comprend un canal de secours, Verify continuera à utiliser ce canal comme indiqué dans le diagramme de séquence suivant :

Envoyer l'URL d'authentification

Une fois que vous avez effectué la demande GET, vous recevrez une ou plusieurs HTTP 302 redirige en fonction du territoire et du transporteur de l'appareil cible :

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

En suivant les redirections, vous obtiendrez soit un HTTP 200 ou HTTP 4xx en fonction du résultat. S'il y a un problème avec le réseau, vous pouvez obtenir une réponse comme celle-ci :

HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{
  "title": "Network not supported",
  "detail": "Device number does not resolve to a supported Mobile Network Operator.",
  "instance": "78e23b55-1633-465e-9325-6abcf186dd00",
  "type": "https://developer.vonage.com/en/api-errors/verify-v2#precondition-failed"
}

Une liste complète des codes d'erreur potentiels est disponible dans la rubrique Spécification de l'API.

Les Gestion des délais du guide des meilleures pratiques contient des informations utiles pour gérer des situations telles que des problèmes de signal réseau ou de couverture au cours de cette étape.

Si la demande est valide, vous recevrez un HTTP 200 réponse contenant votre request_id et un code:

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

Remarque : pour garantir un contrôle d'authentification sûr et se prémunir contre une éventuelle attaque de l'homme du milieu, il convient de stocker l'original de la carte d'identité de l'utilisateur. request_id et la comparer avec la request_id renvoyés dans la réponse. Si les identifiants ne correspondent pas, la vérification de l'authentification silencieuse doit être interrompue. Voir notre exemple de demande pour un exemple de mise en œuvre d'une mesure d'atténuation de l'attaque.

Vérifier le code de vérification

Une fois que l'utilisateur final a reçu le code, votre application client doit envoyer une requête POST à l'adresse suivante /v2/verify/{request_id} en remplaçant le point d'arrivée {request_id} avec l'identifiant que vous avez reçu lors de l'appel précédent.

Pour exécuter l'exemple, remplacez les variables suivantes dans le code d'exemple par vos propres valeurs :

Variable Description
JWT Authentifie la demande d'API à l'aide de JWT.
VERIFY_REQUEST_ID Les request_id reçue à l'étape précédente.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Clé privée de votre application.
VONAGE_APPLICATION_ID ID de l'application de votre demande.
VERIFY_CODE Le code de vérification reçu par l'utilisateur final

Rédiger le code

Ajouter ce qui suit à 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'"
  }'

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

sh check-verification-code.sh

Conditions préalables

npm install @vonage/server-sdk

Créez un fichier nommé check-verification-code.js et ajoutez le code suivant :

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

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à 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));

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

node check-verification-code.js

Conditions préalables

Ajouter ce qui suit à build.gradle:

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

Créez un fichier nommé CheckVerificationCode et ajoutez le code suivant à la méthode main:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier CheckVerificationCode:

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

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin application pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

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

Lancez la commande suivante gradle pour exécuter votre application, en remplaçant com.vonage.quickstart.kt.verify par le paquet contenant CheckVerificationCode:

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

Conditions préalables

Ajouter ce qui suit à build.gradle:

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

Créez un fichier nommé CheckVerificationCode et ajoutez le code suivant à la méthode main:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à la méthode main du fichier 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();
	}
}

Voir la source complète

Exécutez votre code

Nous pouvons utiliser le plugin application pour Gradle afin de simplifier l'exécution de notre application. Mettez à jour votre build.gradle avec ce qui suit :

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

Lancez la commande suivante gradle pour exécuter votre application, en remplaçant com.vonage.quickstart.verify2 par le paquet contenant CheckVerificationCode:

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

Conditions préalables

Install-Package Vonage

Créez un fichier nommé VerifyCodeRequest.cs et ajoutez le code suivant :

using Vonage;
using Vonage.Request;

Voir la source complète

Ajouter ce qui suit à VerifyCodeRequest.cs:

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à VerifyCodeRequest.cs:

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

Voir la source complète

Conditions préalables

composer require vonage/client

Créez un fichier nommé send_code.php et ajoutez le code suivant :

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à send_code.php:

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

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

php send_code.php

Conditions préalables

pip install vonage python-dotenv

Rédiger le code

Ajouter ce qui suit à 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)

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

python verify/check-verification-code.py

Conditions préalables

gem install vonage

Créez un fichier nommé check.rb et ajoutez le code suivant :

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

Voir la source complète

Rédiger le code

Ajouter ce qui suit à check.rb:

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

Voir la source complète

Exécutez votre code

Enregistrez ce fichier sur votre machine et exécutez-le :

ruby check.rb

Note : un code pour un flux de travail d'authentification silencieuse ne peut être vérifié que si une fois.

Si le code est valide, vous recevrez un rappel avec le statut completed:

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

Ou, en cas d'erreur, vous verrez apparaître le message "Code invalide" :

{
   "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"
}

Vous recevrez ensuite un dernier rappel indiquant le résultat de la vérification. En cas de succès, vous verrez apparaître un callback avec "status": "completed":

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "completed",
}

En cas d'échec, par exemple si l'utilisateur a été rejeté, cela sera indiqué dans le champ status domaine :

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "user_rejected",
}

À ce stade, la vérification de l'authentification silencieuse est terminée.

Ressources connexes