Paramètres de vérification

L’onglet General de la page Configure définit le comportement de chaque vérification de votre espace de travail. Il détermine la durée de validité d’un code, le nombre de tentatives erronées qui mettent fin à une vérification, le délai avant l’envoi d’un nouveau code, ainsi que le site web ou l’application Android auquel le code est associé.

Chaque champ affiche la valeur effective : votre valeur personnalisée si vous en avez défini une, sinon la valeur par défaut de la plateforme Bird. Un champ est enregistré dès que vous le quittez. Duration, Maximum Retries, Website et Android app hash sont figés à la création d’une vérification : leur modification s’applique donc aux nouvelles vérifications. Une modification de Retry Delay s’applique au prochain appel de création, y compris pour une vérification déjà en cours.

Pour modifier un paramètre, vous avez besoin de l’autorisation verify_management au niveau write, incluse dans les rôles admin et developer. Le rôle analyst peut consulter la page. Consultez Utilisateurs, équipes et rôles.

Cycle de vérification

• Duration démarre à la création de la vérification. Un renvoi ou un passage à un autre canal envoie un nouveau code, mais conserve l’expiration d’origine : un renvoi tardif ne prolonge donc pas la fenêtre. Pour les parcours d’authentification, gardez une valeur de 10 minutes ou moins ; Bonnes pratiques explique pourquoi.
• Maximum Retries compte les codes erronés sur l’ensemble des codes envoyés pour la vérification : un renvoi ne le remet donc pas à zéro. Lorsqu’un contrôle avec un code erroné laisse la vérification en attente, la réponse indique le nombre de tentatives restantes dans attempts_remaining.
• Retry Delay s’applique lorsque vous appelez à nouveau la création pour le même destinataire. Pendant le délai d’attente, l’appel renvoie la vérification en cours sans envoyer de nouveau code. Envoyer le code sur un autre canal n’est pas concerné, car un changement de canal est une requête différente d’une nouvelle demande sur le même canal. Définissez-le sur 0 pour envoyer un nouveau code à chaque appel de création, dans les limites par destinataire décrites dans Garde-fous contre les abus.

La longueur du code ne se règle pas sur cette page. Par défaut, les codes comportent six chiffres, et options.code_length définit de 4 à 8 chiffres pour une vérification ; consultez Options.

Saisie automatique

Website indique le site sur lequel vos utilisateurs saisissent leurs codes, par exemple https://login.example.com. Lorsqu’un site web est défini, les navigateurs peuvent proposer le code sur ce site et sur aucun autre, ce qui évite à l’utilisateur de le copier. Laissez le champ vide pour envoyer des codes qui ne mentionnent aucun site web.

Écrivez le site web sous la forme https:// suivi de son domaine en minuscules, sans port, chemin ni barre oblique finale. Un domaine internationalisé utilise sa forme xn--, par exemple https://xn--bcher-kva.example pour bücher.example. Toute autre forme est refusée, et le message indique la forme à saisir lorsqu’elle existe. Utilisez exactement le site qui affiche le champ du code : un formulaire sur login.example.com nécessite https://login.example.com, et non https://example.com.

Lorsqu’une vérification a un site web, Verify l’ajoute aux messages contenant le code :

• SMS : le message se termine par une ligne telle que @login.example.com #123456, sauf si un hachage d’application Android est défini, auquel cas il la remplace. Ajoutez autocomplete="one-time-code" à votre champ de saisie du code pour que Safari et les autres navigateurs proposent le code, et appelez l’API WebOTP depuis la page si vous voulez que le navigateur le remplisse sans action de l’utilisateur. Cette ligne supplémentaire peut ajouter un segment SMS : dans de nombreuses langues qui nécessitent l’encodage Unicode, comme l’arabe, le grec ou le russe, un code lié occupe deux segments au lieu d’un, ce qui double son coût SMS. Un domaine long peut avoir le même effet dans d’autres langues.
• E-mail : le message contient un en-tête OTP-Token avec le code et le site web, tel que défini par l’Internet-Draft OTP-Token, révision 01. Les applications de messagerie commencent seulement à lire cet en-tête : considérez-le comme un complément au code présent dans le message.

Le site web est fixé à la création de la vérification. Un renvoi, un basculement vers un autre canal ou un nouvel appel de création pour le même destinataire le conserve.

Hachage d’application Android

Android app hash identifie votre application Android, afin qu’elle puisse lire le code du SMS grâce à l’API SMS Retriever de Google, sans autorisation SMS ni action de l’utilisateur. La valeur est le hachage de 11 caractères que Google calcule à partir du nom de package et du certificat de signature de votre application, par exemple FA+9qCX9VSu. Laissez le champ vide pour envoyer des codes qui ne mentionnent aucune application.

Lorsqu’un hachage est défini, le SMS est un message court qui se termine par le hachage sur une ligne distincte. Il ne dépasse pas les 140 octets que lit SMS Retriever, quelles que soient la langue et la longueur du code :

12345678 is your verification code.
FA+9qCX9VSu

Le message court omet l’expiration, l’avertissement et la ligne du site web. L’e-mail ne change pas : il contient l’en-tête OTP-Token exactement comme il le ferait sans hachage. Comme le site web, le hachage est figé à la création d’une vérification.

Si vous préférez ne pas calculer de hachage, l’API SMS User Consent de Google permet à votre application de lire les codes de Verify après une seule action de l’utilisateur, sans rien définir ici.

Calculer le hachage de l’application

Le hachage provient du certificat de signature de votre application : Bird ne peut donc pas le calculer ni le vérifier à votre place. Calculez-le avec la commande du guide de Google, à partir de votre keystore, de l’alias du certificat et du nom de package :

keytool -exportcert -alias KEY_ALIAS -keystore MY_KEYSTORE.keystore | xxd -p | tr -d "[:space:]" | echo -n com.example.myapp `cat` | sha256sum | tr -d "[:space:]-" | xxd -r -p | base64 | cut -c1-11

• Google Play signe votre application : avec Play App Signing, téléchargez le certificat de signature de l’application (deployment_cert.der) dans la section App signing de la Play Console et calculez le hachage à partir de ce certificat, et non de votre clé d’importation. Le guide de Google explique comment l’importer d’abord dans un keystore.
• Vérifiez les erreurs : la commande affiche quand même 11 caractères lorsque keytool échoue. Lisez donc sa sortie avant de copier le hachage.
• Builds de débogage : un build de débogage est signé avec une autre clé et possède donc son propre hachage. La classe d’exemple AppSignatureHelper de Google affiche le hachage du build en cours d’exécution ; retirez-la de votre application une fois la valeur obtenue.

Lier un code par requête

Une requête peut indiquer son propre site web avec options.autofill_origin, qui remplace Website pour cette vérification. Utilisez-le lorsqu’un même espace de travail dessert plusieurs sites.

options.android_app_hash remplace Android app hash de la même manière, par exemple pour envoyer le hachage d’un build de débogage depuis un environnement de test.

Lorsque le champ du code se trouve dans un iframe d’une autre origine, comme un formulaire de paiement intégré à la page de commande d’une boutique, définissez options.autofill_origin sur le site web de l’iframe et options.autofill_top_level_origin sur la page affichée dans l’onglet du navigateur. La ligne SMS indique alors les deux sites, comme dans @shop.example #123456 @pay.example, ce qui peut ajouter un segment dans n’importe quelle langue. Chrome remplit automatiquement ce formulaire lorsque la page intègre directement l’iframe et lui accorde allow="otp-credentials". L’e-mail n’envoie pas d’en-tête OTP-Token pour ces vérifications, car cet en-tête ne peut indiquer qu’un seul site web. La requête est rejetée avec 422 lorsque le site web de premier niveau est mal formé, lorsqu’aucun site web n’est défini dans la requête ni sur cette page, ou lorsqu’il est identique à ce site web.

Expéditeurs SMS enregistrés

Si vous envoyez des SMS depuis votre propre expéditeur enregistré, comme une campagne 10DLC aux États-Unis, ajoutez à la campagne un exemple de message qui se termine par la ligne liée avant de définir un site web, et un exemple du message court avant de définir un hachage d’application Android. Les opérateurs peuvent filtrer un message qui diffère des exemples enregistrés pour la campagne.

Dépannage

• Le site web est rejeté. La valeur n’a pas le format requis. Saisissez le format suggéré par le message, par exemple https://example.com pour https://Example.com/.
• Le navigateur ne propose pas le code. Vérifiez que le site web correspond exactement à l’adresse de la page, sous-domaine compris, et que le champ du code comporte autocomplete="one-time-code". Pour un iframe, vérifiez que la requête définit les deux sites web et que la page qui l’intègre accorde allow="otp-credentials". Le remplissage automatique dépend aussi du navigateur : Chrome lit la ligne SMS via WebOTP et Safari via son remplissage automatique des codes, tandis que Firefox ne prend pas en charge WebOTP (prise en charge par les navigateurs).
• L’application Android ne lit pas le code. Vérifiez que le hachage provient du certificat qui signe le build installé : le certificat Play App Signing pour une application installée depuis Google Play, et la clé de débogage pour un build de débogage. L’application doit démarrer le SMS Retriever avant l’envoi du code.
• Le hachage d’application Android est rejeté. La valeur doit comporter exactement 11 caractères parmi A à Z, a à z, 0 à 9, + et /, telle que la commande ci-dessus l’affiche.
• Un code a expiré avant que l’utilisateur le saisisse. Consultez le minutage des tentatives dans le journal Verify avant d’augmenter Duration. La cause est généralement un acheminement lent, et une fenêtre plus longue affaiblit le code.

Étapes suivantes

• Envoyer des vérifications : créez et contrôlez des vérifications, y compris avec des options propres à chaque requête.
• Destinations : choisissez les canaux et leur ordre pour chaque pays de destination.
• Expéditeurs et image de marque : consultez les messages envoyés par Verify et choisissez l’expéditeur de chaque canal.