Migration de l'API de vérification des numéros vers Verify Silent Auth

Ce guide explique comment migrer d'un flux d'authentification silencieuse utilisant l'API d'activation du réseau et l'API de vérification des numéros vers l'API de vérification unifiée avec l'authentification silencieuse.

L'API Verify prend en charge à la fois les éléments suivants synchrone et asynchrone les implémentations de l'authentification silencieuse. Ce guide suit les asynchrone qui est la méthode recommandée pour intégrer l'authentification silencieuse.

Comparaison entre l'ancienne et la nouvelle architecture

Avant de commencer la migration, veuillez consulter les sections ci-dessous pour comprendre les différences entre l'ancienne et la nouvelle architecture.

Architecture patrimoniale : Activation du réseau et vérification des numéros

Dans la configuration actuelle, l'authentification silencieuse nécessite la coordination de deux API distinctes. Tout d'abord, l'API d'activation du réseau est appelée pour vérifier si le réseau de l'utilisateur et le contexte de l'appareil prennent en charge l'authentification silencieuse. Si c'est le cas, l'API de vérification du numéro est alors utilisée pour effectuer la vérification silencieuse de l'identité mobile.

Cette approche présente certaines limites :

• Il n'y a pas de solution de repli intégrée si la vérification silencieuse n'est pas prise en charge.
• Les développeurs doivent orchestrer manuellement les deux API.
• La logique d'erreur et de réessai doit être mise en œuvre du côté du client.

Nouvelle architecture : Verify avec l'authentification silencieuse

La nouvelle architecture remplace l'approche en deux étapes par une intégration unique utilisant l'API Verify avec l'authentification silencieuse. Cette approche unifiée réduit la complexité, prend en charge les canaux de repli (comme les SMS, la voix, WhatsApp ou le courrier électronique) lorsque la vérification silencieuse n'est pas possible et gère automatiquement les rappels de webhook.

Principales différences

Le tableau ci-dessous présente les principales différences entre l'ancienne et la nouvelle approche :

Étapes de la migration

Suivez les étapes ci-dessous pour migrer de Network Enablement and Number Verification API vers Verify API with Silent Authentication :

Étape 1 : Mise à jour des paramètres de l'application

Étape 2 : Remplacer l'ancien flux par l'API Verify

Étape 3 : Mise à jour de la méthode d'authentification

Étape 4 : Mise à jour de la structure de la demande

Étape 5 : Transmettre le check_url à l'application mobile

Étape 6 : Gestion de la rétroaction (callback) action_pending

Étape 7 : L'application mobile suit les redirections et reçoit le code

Étape 8 : Valider le code de vérification

Étape 9 : Gestion du rappel du résumé

Mettez à jour les paramètres de votre application

Dans le cadre de la Tableau de bord des applications Vonage, ouvrez les paramètres de votre application. Sous Capacités > Registre du réseaumettez à jour le callback de l'événement Verify avec l'URL où votre backend recevra les données de l'événement Verify. webhook (par exemple, action_pending, completed).

Remplacer l'ancien flux par l'API Verify

Une fois que l'application mobile déclenche l'authentification, votre backend doit lancer le flux d'authentification :

Flux d'héritage:

1. API de mise en œuvre du réseau d'appel.
2. Si le réseau est pris en charge, appelez l'API de vérification des numéros pour une vérification de la couverture.

Nouveau flux:

1. Appelez l'API Verify à l'aide de l'option silent_auth flux de travail.
2. Si la vérification silencieuse échoue, un canal de secours (par exemple, SMS, voix, WhatsApp ou courriel) est déclenché automatiquement s'il a été défini dans le flux de travail (voir Mise à jour de la structure de la demande).

Mise à jour de la méthode d'authentification

L'API Verify prend en charge deux méthodes d'authentification : Authentification de base et JWT (jeton porteur). Se référer au Guide d'authentification Verify pour savoir quand utiliser chaque méthode et comment générer les informations d'identification.

Mise à jour de la structure de la demande

L'API de Verify utilise une méthode de flux de travail pour définir la séquence des canaux de vérification. L'authentification silencieuse doit être la première étape du flux de travail, comme le montre l'exemple suivant :

{
  "brand": "ACME",
  "workflow": [
    {
      "channel": "silent_auth",
      "to": "447700900000",
    },
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}   

Passez le check_url à l'application mobile

Après avoir appelé l'API Verify, vous recevrez une réponse synchrone similaire à cet exemple :

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

La réponse comprend les éléments suivants check_url qui est similaire au paramètre auth_url utilisée dans le cadre de la vérification des numéros. L'application mobile doit effectuer une requête HTTP

Vous pouvez également recevoir la même check_url plus tard dans un rappel d'événement (voir Transmettre le check_url à l'application mobile), de sorte que vous pouvez le transmettre à l'application à partir de l'une ou l'autre source, en fonction de votre implémentation.

Manipuler les action_pending Rappel

Peu après la demande, Vonage envoie un rappel d'événement à l'URL de votre webhook définie dans la section Mise à jour des paramètres de l'application.

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://eu.api.silent.auth/..."
  }
}   

Vous pouvez utiliser le check_url à partir de la réponse initiale de l'API (Mise à jour de la structure de la demande) ou ce callback pour lancer l'authentification silencieuse dans l'application.

L'application mobile suit les redirections et reçoit le code

L'application mobile effectue une GET à l'adresse suivante check_url. Il suivra un ou plusieurs HTTP 302 redirections et recevoir enfin une réponse :

{
  "request_id": "...",
  "code": "si9sfG"
}   

En cas de succès, ce code doit être validé à l'étape suivante.

Valider le code de vérification

Envoyer un POST de l'application mobile à l'API Verify pour valider le code :

POST https://api.nexmo.com/v2/verify/{request_id}
Authorization: Bearer {access_token}
Content-Type: application/json  

Avec le corps suivant :

{
  "code": "si9sfG"
}   

Si tout se passe bien, la réponse du backend sera similaire à cet exemple :

{
  "request_id": "...",
  "status": "completed"
}   

Gérer le rappel du résumé

Une fois la vérification terminée, Vonage envoie un dernier rappel à votre webhook :

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "completed"
}   

Cela confirme que le processus de vérification est terminé.

Prochaines étapes

• Testez votre intégration dans un environnement sandbox. Utilisez les numéros de test et le tableau de bord du développeur pour valider les scénarios silencieux et de repli.
• Consultez notre Guide des meilleures pratiques en matière d'authentification silencieuse.
• Surveillez les événements liés aux webhooks. Assurez-vous que votre backend gère correctement les rappels d'état (par exemple, action_pending, completed, failed).

Pour plus de détails, voir le Verify API documentation.