Valider des numéros de téléphone sur le Web avec l'API WebOTP

Aider les utilisateurs avec les codes secrets uniques reçus par SMS

Eiji Kitamura

Qu'est-ce que l'API WebOTP ?

Aujourd'hui, la plupart des personnes dans le monde possèdent un appareil mobile, et les développeurs utilisent souvent les numéros de téléphone comme identifiant pour les utilisateurs de leurs services.

Il existe différentes façons de valider un numéro de téléphone, mais l'une des plus courantes consiste à envoyer un mot de passe à usage unique (OTP) généré de manière aléatoire par SMS. Le renvoi de ce code au serveur du développeur prouve que vous contrôlez le numéro de téléphone.

Cette idée est déjà déployée dans de nombreux scénarios pour atteindre les objectifs suivants :

  • Numéro de téléphone de l'utilisateur. Lors de l'inscription à un nouveau service, certains sites Web demandent un numéro de téléphone au lieu d'une adresse e-mail et l'utilisent comme identifiant de compte.
  • Validation en deux étapes : Lors de la connexion, un site Web demande un code à usage unique envoyé par SMS en plus d'un mot de passe ou d'un autre facteur de connaissance pour plus de sécurité.
  • Confirmation de paiement : Lorsqu'un utilisateur effectue un paiement, demander un code unique envoyé par SMS peut aider à vérifier l'intention de la personne.

Le processus actuel crée des frictions pour les utilisateurs. Il est fastidieux de trouver un code OTP dans un message SMS, puis de le copier et de le coller dans le formulaire. Cela réduit les taux de conversion dans les parcours utilisateur critiques. De nombreux développeurs mondiaux majeurs demandent depuis longtemps à ce que cette opération soit simplifiée pour le Web. Android dispose d'une API qui fait exactement cela. C'est également le cas d'iOS et de Safari.

L'API WebOTP permet à votre application de recevoir des messages au format spécial liés au domaine de votre application. Vous pouvez ainsi obtenir un code secret à partir d'un message SMS et valider plus facilement le numéro de téléphone de l'utilisateur de manière programmatique.

Démonstration

Supposons qu'un utilisateur souhaite valider son numéro de téléphone sur un site Web. Le site Web envoie un message texte à l'utilisateur par SMS, et l'utilisateur saisit le code secret unique du message pour valider la propriété du numéro de téléphone.

Avec l'API WebOTP, ces étapes sont aussi simples qu'un clic pour l'utilisateur, comme le montre la vidéo. Lorsqu'il reçoit le message, une feuille inférieure s'affiche et invite l'utilisateur à valider son numéro de téléphone. Après avoir cliqué sur le bouton Valider dans la feuille inférieure, le navigateur colle le code OTP dans le formulaire, qui est ensuite envoyé sans que l'utilisateur ait besoin d'appuyer sur Continuer.

L'ensemble du processus est illustré dans l'image ci-dessous.

Diagramme de l'API WebOTP

Essayez la démo. Il ne vous demande pas votre numéro de téléphone et n'envoie pas de SMS à votre appareil, mais vous pouvez en envoyer un depuis un autre appareil en copiant le texte affiché dans la démo. Cela fonctionne, car l'identité de l'expéditeur n'a pas d'importance lorsque vous utilisez l'API WebOTP.

  1. Accédez à https://chrome.dev/web-otp-demo dans Chrome 84 ou version ultérieure sur un appareil Android.
  2. Envoyez le SMS suivant à votre téléphone depuis un autre téléphone.
Your OTP is: 123456.  @chrome.dev #123456

Avez-vous reçu le SMS et vu l'invite à saisir le code dans la zone de saisie ? C'est ainsi que l'API WebOTP fonctionne pour les utilisateurs.

L'utilisation de l'API WebOTP se compose de trois parties :

  • Balise <input> correctement annotée
  • JavaScript dans votre application Web
  • Texte du message mis en forme envoyé par SMS.

Je vais d'abord aborder la balise <input>.

Annoter un tag <input>

WebOTP fonctionne sans annotation HTML, mais pour la compatibilité entre navigateurs, je vous recommande vivement d'ajouter autocomplete="one-time-code" à la balise <input> où vous attendez que l'utilisateur saisisse un OTP.

Cela permet à Safari 14 ou version ultérieure de suggérer à l'utilisateur de remplir automatiquement le champ <input> avec un code OTP lorsqu'il reçoit un SMS au format décrit dans Mettre en forme le message SMS, même s'il n'est pas compatible avec WebOTP.

HTML

<form>   <input autocomplete="one-time-code" required/>   <input type="submit"> </form>

Utiliser l'API WebOTP

WebOTP étant simple, il vous suffit de copier et coller le code suivant. Je vais quand même vous expliquer ce qui se passe.

JavaScript

if ('OTPCredential' in window) {   window.addEventListener('DOMContentLoaded', e => {     const input = document.querySelector('input[autocomplete="one-time-code"]');     if (!input) return;     const ac = new AbortController();     const form = input.closest('form');     if (form) {       form.addEventListener('submit', e => {         ac.abort();       });     }     navigator.credentials.get({       otp: { transport:['sms'] },       signal: ac.signal     }).then(otp => {       input.value = otp.code;       if (form) form.submit();     }).catch(err => {       console.log(err);     });   }); }

Détection de caractéristiques

La détection de fonctionnalités est la même que pour de nombreuses autres API. L'écoute de l'événement DOMContentLoaded attend que l'arborescence DOM soit prête à être interrogée.

JavaScript

if ('OTPCredential' in window) {   window.addEventListener('DOMContentLoaded', e => {     const input = document.querySelector('input[autocomplete="one-time-code"]');     if (!input) return;     …     const form = input.closest('form');     …   }); }

Traiter l'OTP

L'API WebOTP est assez simple. Utilisez navigator.credentials.get() pour obtenir le code OTP. WebOTP ajoute une nouvelle option otp à cette méthode. Il ne comporte qu'une seule propriété : transport, dont la valeur doit être un tableau avec la chaîne 'sms'.

JavaScript

    …     navigator.credentials.get({       otp: { transport:['sms'] }       …     }).then(otp => {     …

Cela déclenche le flux d'autorisation du navigateur lorsqu'un message SMS arrive. Si l'autorisation est accordée, la promesse renvoyée est résolue avec un objet OTPCredential.

Contenu de l'objet OTPCredential obtenu

{   code: "123456" // Obtained OTP   type: "otp"  // `type` is always "otp" }

Transmettez ensuite la valeur OTP au champ <input>. En envoyant le formulaire directement, vous n'aurez plus besoin d'appuyer sur un bouton.

JavaScript

    …     navigator.credentials.get({       otp: { transport:['sms'] }       …     }).then(otp => {       input.value = otp.code;       if (form) form.submit();     }).catch(err => {       console.error(err);     });     …

Abandonner le message

Si l'utilisateur saisit manuellement un code OTP et envoie le formulaire, vous pouvez annuler l'appel get() à l'aide d'une instance AbortController dans l'objet options.

JavaScript 

    …     const ac = new AbortController();     …     if (form) {       form.addEventListener('submit', e => {         ac.abort();       });     }     …     navigator.credentials.get({       otp: { transport:['sms'] },       signal: ac.signal     }).then(otp => {     …

Mettre en forme le message SMS

L'API elle-même devrait paraître assez simple, mais il y a quelques points à connaître avant de l'utiliser. Le message doit être envoyé après l'appel de navigator.credentials.get() et reçu sur l'appareil sur lequel get() a été appelé. Enfin, le message doit respecter le format suivant :

  • Le message commence par un texte lisible par un humain qui contient une chaîne alphanumérique de quatre à dix caractères avec au moins un chiffre, la dernière ligne étant réservée à l'URL et au code OTP.
  • La partie domaine de l'URL du site Web qui a appelé l'API doit être précédée de @.
  • L'URL doit contenir un signe dièse (#) suivi du code secret à usage unique.

Exemple :

Your OTP is: 123456.  @www.example.com #123456

Voici quelques exemples de mauvaise qualité :

Exemple de SMS mal formé Pourquoi cela ne fonctionnera pas
Here is your code for @example.com #123456 @ doit être le premier caractère de la dernière ligne.
Your code for @example.com is #123456 @ doit être le premier caractère de la dernière ligne.
Your verification code is 123456

@example.com\t#123456		 Un seul espace est attendu entre @host et #code.
Your verification code is 123456

@example.com  #123456		 Un seul espace est attendu entre @host et #code.
Your verification code is 123456

@ftp://example.com #123456		 Le schéma d'URL ne peut pas être inclus.
Your verification code is 123456

@https://example.com #123456		 Le schéma d'URL ne peut pas être inclus.
Your verification code is 123456

@example.com:8080 #123456		 Le port ne peut pas être inclus.
Your verification code is 123456

@example.com/foobar #123456		 Le chemin ne peut pas être inclus.
Your verification code is 123456

@example .com #123456		 Le domaine ne doit pas contenir d'espace blanc.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 Le domaine ne doit pas contenir de caractères interdits.
@example.com #123456

Mambo Jumbo		 @host et #code doivent être la dernière ligne.
@example.com #123456

App hash #oudf08lkjsdf834		 @host et #code doivent être la dernière ligne.
Your verification code is 123456

@example.com 123456		 # manquant.
Your verification code is 123456

example.com #123456		 @ manquant.
Hi mom, did you receive my last text @ et # manquants.

Démonstrations

Essayez différents messages avec la démo : https://chrome.dev/web-otp-demo

Le code source est disponible ici : https://github.com/GoogleChromeLabs/web-identity-demos/tree/main/web-otp-demo.

Utiliser WebOTP depuis un iFrame d'origine différente

La saisie d'un code secret à usage unique par SMS dans un iframe inter-origine est généralement utilisée pour confirmer un paiement, en particulier avec 3D Secure. L'API WebOTP, qui utilise un format commun pour prendre en charge les iFrames inter-origines, fournit des OTP liés à des origines imbriquées. Exemple :

  • Un utilisateur se rend sur shop.example pour acheter une paire de chaussures avec une carte de crédit.
  • Après avoir saisi le numéro de carte de crédit, le fournisseur de services de paiement intégré affiche un formulaire bank.example dans un iFrame, demandant à l'utilisateur de valider son numéro de téléphone pour un paiement rapide.
  • bank.example envoie un SMS contenant un code OTP à l'utilisateur afin qu'il puisse le saisir pour valider son identité.

Pour utiliser l'API WebOTP à partir d'un iFrame d'origine croisée, vous devez effectuer deux opérations :

  • Ajoutez une annotation à l'origine du frame supérieur et à l'origine de l'iFrame dans le message SMS.
  • Configurez la règle d'autorisation pour permettre à l'iFrame d'origine croisée de recevoir directement le code OTP de l'utilisateur.
API WebOTP dans un iFrame en action.

Vous pouvez essayer la démo sur https://web-otp-iframe-demo.stackblitz.io.

Annoter les origines liées au message SMS

Lorsque l'API WebOTP est appelée depuis un iFrame, le message SMS doit inclure l'origine du frame supérieur précédée de @, suivie du code OTP précédé de # et de l'origine de l'iFrame précédée de @ sur la dernière ligne.

Your verification code is 123456  @shop.example #123456 @bank.exmple

Configurer la règle relative aux autorisations

Pour utiliser WebOTP dans un iFrame cross-origin, l'intégrateur doit accorder l'accès à cette API via la règle d'autorisation otp-credentials pour éviter tout comportement indésirable. En général, il existe deux façons d'atteindre cet objectif :

via un en-tête HTTP :

Permissions-Policy: otp-credentials=(self "https://bank.example")

via l'attribut iframe allow :

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

Consultez d'autres exemples sur la façon de spécifier une règle d'autorisation .

Utiliser WebOTP sur un ordinateur

Dans Chrome, WebOTP permet d'écouter les SMS reçus sur d'autres appareils pour aider les utilisateurs à valider leur numéro de téléphone sur ordinateur.

API WebOTP sur ordinateur.

Pour cela, l'utilisateur doit se connecter au même compte Google sur Chrome pour ordinateur et Chrome pour Android.

Il suffit aux développeurs d'implémenter l'API WebOTP sur leur site Web pour ordinateur, de la même manière que sur leur site Web mobile. Aucune astuce particulière n'est requise.

Pour en savoir plus, consultez Valider un numéro de téléphone sur ordinateur à l'aide de l'API WebOTP.

Questions fréquentes

La boîte de dialogue ne s'affiche pas, même si j'envoie un message correctement formaté. Que se passe-t-il ?

Il existe quelques mises en garde concernant le test de l'API :

  • Si le numéro de téléphone de l'expéditeur figure dans la liste de contacts du destinataire, cette API ne sera pas déclenchée en raison de la conception de l'API de consentement de l'utilisateur pour les SMS sous-jacente.
  • Si vous utilisez un profil professionnel sur votre appareil Android et que WebOTP ne fonctionne pas, essayez d'installer et d'utiliser Chrome sur votre profil personnel (c'est-à-dire le profil dans lequel vous recevez les messages SMS).

Vérifiez le format pour voir si votre SMS est correctement mis en forme.

Cette API est-elle compatible avec différents navigateurs ?

Chromium et WebKit se sont mis d'accord sur le format des messages SMS, et Apple a annoncé que Safari le prendrait en charge à partir d'iOS 14 et de macOS Big Sur. Bien que Safari ne soit pas compatible avec l'API JavaScript WebOTP, en annotant l'élément input avec autocomplete=["one-time-code"], le clavier par défaut suggère automatiquement de saisir le code OTP si le message SMS respecte le format.

Est-il sûr d'utiliser les SMS pour l'authentification ?

Bien que l'OTP par SMS soit utile pour valider un numéro de téléphone lors de sa première saisie, la validation du numéro de téléphone par SMS doit être utilisée avec précaution pour la réauthentification, car les numéros de téléphone peuvent être piratés et réattribués par les opérateurs. WebOTP est un mécanisme pratique de réauthentification et de récupération, mais les services doivent le combiner avec des facteurs supplémentaires, tels qu'un défi de connaissances, ou utiliser l'API Web Authentication pour une authentification renforcée.

Où puis-je signaler les bugs liés à l'implémentation de Chrome ?

Avez-vous trouvé un bug dans l'implémentation de Chrome ?

  • Signalez un bug sur crbug.com. Incluez autant de détails que possible, des instructions simples pour reproduire le problème et définissez Composants sur Blink>WebOTP.

Comment puis-je aider à améliorer cette fonctionnalité ?

Prévoyez-vous d'utiliser l'API WebOTP ? Votre soutien public nous aide à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge. Envoyez un tweet à @ChromiumDev avec le hashtag #WebOTP pour nous indiquer où et comment vous l'utilisez.

Ressources