En bref
Le code nécessaire pour vérifier une identité dans une application web tient en peu de lignes. Votre serveur crée une session, la personne suit un parcours hébergé, et votre serveur lit le résultat. La plupart des bugs d'intégration viennent des décisions autour de ce code : à quel signal faire confiance, que se passe-t-il quand une requête est rejouée, et que fait l'application pendant qu'un dossier attend un examen manuel.
Ce guide suit l'intégration dans l'ordre où vous la construiriez, avec l'API de secuveri et les applications d'exemple open source. Pour voir d'abord le résultat final, essayez la démo bancaire ou la démo de boutique 18+. Les deux tournent en sandbox.
Il y a trois parties :
- Votre backend crée une session pour une personne et un workflow. Un workflow est l'ensemble des contrôles que vous avez configurés, par exemple document d'identité, détection du vivant et comparaison faciale, ou un âge minimum.
- La personne suit le parcours sur une page hébergée ou dans un cadre intégré à votre application. Sur ordinateur, le parcours affiche un code QR pour qu'elle continue sur son téléphone, là où se trouvent la caméra et le NFC.
- Votre backend apprend le résultat, par un webhook signé et un résultat signé qu'il récupère auprès de l'API.
Le navigateur n'intervient qu'à l'étape 2. C'est voulu, et cela détermine le reste de l'intégration.
Commencer en sandbox
Créez une clé API sandbox dans le tableau de bord, sous Settings, API keys. Les clés sandbox commencent par sk_test_, les clés de production par sk_live_. Les unes comme les autres restent uniquement sur votre serveur.
Créez et publiez ensuite un workflow sandbox avec les contrôles dont vous avez besoin. Si vous intégrez le parcours dans votre page, ajoutez votre origine locale, par exemple http://localhost:3030, sous Settings, Branding, dans la liste des sites autorisés à intégrer le parcours.
Le sandbox exécute les vrais contrôles : vous pouvez donc vous vérifier avec votre propre document pendant le développement. Il propose aussi des scénarios gratuits qui terminent immédiatement une session avec le résultat de votre choix, accepté, refusé ou envoyé en examen, sans document. Servez-vous-en pour tester vos chemins de code. Vous voudrez rejouer les cas de refus et d'examen bien plus souvent que quiconque n'a envie de prendre un selfie.
Créer la session sur votre serveur
Une session, c'est un seul appel d'API : POST /v1/sessions avec votre clé API dans l'en-tête x-api-key, l'identifiant du workflow et votre propre référence dans vendor_data. La réponse contient un identifiant de vérification et le lien vers le parcours. Avec le paquet Node.js @secuveri/node, le même appel s'appelle createSession.
Deux détails vous éviteront des ennuis plus tard :
- Mettez votre propre identifiant dans vendor_data. Utilisez l'identifiant du compte ou de la commande à laquelle se rattache la vérification. Vous le contrôlerez à nouveau au retour du résultat.
- Envoyez une Idempotency-Key. Dérivez-la du même identifiant, par exemple celui de la commande. Si votre requête est relancée après un délai dépassé, vous récupérez la même session au lieu d'en créer une seconde.
Ne renvoyez au navigateur que le lien ou le jeton de session. La clé API ne quitte jamais votre serveur.
Ouvrir le parcours
Vous pouvez rediriger la personne vers le lien, l'afficher sous forme de code QR, ou le faire envoyer par secuveri par e-mail ou SMS. Pour garder les gens dans votre application, utilisez le paquet navigateur @secuveri/web et appelez Secuveri.start avec l'URL de la session. Il ouvre le parcours dans une fenêtre modale ou un cadre intégré et signale la progression par des callbacks comme onComplete, onCancel et onError.
Ne pas se fier au callback du navigateur
onComplete signifie que la personne est arrivée au bout du parcours. Cela ne veut pas dire qu'elle l'a réussi, et n'importe qui peut l'appeler depuis la console développeur. Traitez-le comme un signal pour demander le résultat à votre propre serveur, jamais comme le résultat lui-même.
L'exemple de boutique le montre bien. Le checkout ne passe la commande que lorsque le serveur détient un résultat accepté pour cette commande précise. Appeler onComplete à la main ne change rien, car le serveur ne trouve toujours aucun résultat accepté.
Traiter correctement le webhook
Lorsqu'une vérification est terminée ou examinée, secuveri envoie un webhook au point de terminaison défini sous Settings, Webhooks. L'exemple de récepteur de webhooks fait cela en un seul fichier, en suivant ces règles :
- Vérifier la signature sur le corps brut. L'en-tête secuveri-signature est un HMAC-SHA256 calculé sur les octets exacts reçus. Si votre framework analyse puis resérialise le JSON avant, la signature ne correspondra plus.
- Répondre vite. Renvoyez un statut 2xx dans les 10 secondes et faites le travail lent ensuite. Toute autre réponse entraîne une nouvelle tentative, 7 fois sur environ 21 heures.
- Dédoublonner sur l'identifiant de l'événement. Il reste identique d'une tentative à l'autre ; conservez donc les identifiants déjà traités.
- Utiliser le webhook comme déclencheur. Fondez la décision sur le résultat signé, pas sur le seul contenu du webhook.
Le point de terminaison doit être une URL https publique. En développement local, utilisez un tunnel, ou appuyez-vous jusqu'au déploiement sur le callback du navigateur suivi d'une vérification du résultat côté serveur.
Lire et contrôler le résultat signé
Récupérez le résultat avec l'identifiant de vérification (getResult dans @secuveri/node). Il se présente sous forme de résultat signé : un JWS ES256 que vous vérifiez avec les clés publiques disponibles sous /.well-known/jwks.json. Il ne contient aucune donnée personnelle. Vous pouvez donc le conserver comme preuve de la décision sans stocker d'images de documents ni de dates de naissance.
Avant d'agir, vérifiez :
- Qu'il concerne bien ce dossier. vendor_data correspond à votre identifiant de compte ou de commande, et l'identifiant du workflow est celui attendu. Sinon, un résultat valide issu d'un autre workflow, moins exigeant, pourrait être réutilisé contre votre checkout.
- Le statut. COMPLETE avec le verdict APPROVED laisse passer la personne. REVIEW_REQUIRED signifie qu'une personne de votre équipe doit encore trancher : laissez alors le dossier en attente plutôt que de le refuser. Tout le reste n'est pas une réussite.
- Les contrôles spécifiques, quand ils comptent. Une boutique soumise à une limite d'âge vérifie par exemple aussi que le contrôle d'âge du résultat respecte son propre âge minimum.
Exécutez la même logique de clôture depuis le chemin du navigateur et depuis celui du webhook, et faites en sorte qu'elle puisse tourner deux fois sans dommage. Le premier arrivé clôt le dossier, le second ne trouve plus rien à faire.
Tester ce qui peut mal tourner
Avant la mise en production, assurez-vous que votre application réagit correctement quand :
- la personne ferme le parcours en cours de route ;
- le résultat est un refus, ou part en examen et est accepté le lendemain ;
- le webhook arrive avant le callback du navigateur, ou l'inverse ;
- le même webhook arrive deux fois ;
- votre requête de session dépasse le délai et est relancée ;
- quelqu'un appelle votre point de clôture pour une commande sans vérification.
Les scénarios du sandbox couvrent les résultats. Le reste relève des tests habituels de votre propre code.
Passer en production
Le passage en production est un changement de configuration : une clé sk_live_, un workflow de production publié, votre origine de production dans la liste d'intégration, et un point de terminaison de webhook avec son secret de signature. Le code ne change pas.
La référence complète de l'API, y compris les codes d'erreur et le filtrage AML, se trouve dans le tableau de bord sous app.secuveri.com/docs, après connexion. Pour une vue d'ensemble de l'API, consultez la page développeurs.
Cet article fournit des informations générales et ne constitue pas un conseil juridique ou de conformité. Vos obligations dépendent de votre secteur, de votre autorisation et de vos marchés.