Découvrez l'API Verify de Twilio pour valider des utilisateurs avec des SMS, la voix, l'e-mail, du Push ou des codes 2FA

La dernière fois que je vous ai parlé de Twilio, c’était pour vous présenter leur service d’envoi de SMS à destination des développeurs. Cela vous avait vraiment intéressé, surtout la partie technique alors aujourd’hui je vous propose de remettre ça avec Verify.

Qu’est-ce que Verify ?

Verify est également un service proposé par Twilio qui permet très simplement de faire de la vérification d’utilisateur via différents canaux comme les SMS, le TOTP, le push, l’email ou même la voix.

En effet quand on développe un service qui nécessite de valider le numéro de téléphone, une adresse email ou tout simplement la connexion d’un utilisateur avec un code 2FA, on n’a pas forcément le temps ou l’envie de développer tout un système de validation d’utilisateurs. Cela prend du temps et c’est beaucoup plus complexe qu’il n’y parait, car il faut être capable de gérer les numéros de téléphone internationaux, l’intégration de cette vérification dans le flux d’inscription/ connexion, la traduction des messages et j’en passe.

Avec Twilio, tout ce process peut se faire hyper facilement avec une simple API.

Grâce à cette API Verify, vous allez pouvoir intégrer très simplement et très rapidement surtout, cette validation d’utilisateur à un projet existant. Ainsi, quand un utilisateur va rentrer son numéro de téléphone pour le valider, l’API Verify enverra un code de vérification par SMS, Whatsapp, email ou via un coup de fil avec synthèse vocale.

L’utilisateur entrera alors ce code sur le site et l’API Verify s’assurera que le code correspond bien à celui qui a été envoyé. Si tout est OK, alors le numéro de téléphone ou l’email pourra être considéré comme valide.

Dans le cas d’une authentification, Verify pourra aussi fonctionner avec un système de push applicatif ou TOTP (application de double authentification comme Authy par exemple).

Mettre en place une validation SMS (ou appel téléphonique)

Pour ajouter une vérification du numéro de téléphone de l’utilisateur avec Verify à votre application, vous devrez d’abord établir avec l’API suivante :

<strong>https://verify.twilio.com/v2/</strong>

En utilisant Python, et le package Twilio (pip install twilio) on va d’abord initier une connexion avec le service Verify en utilisant les clés de l’API comme ceci :

from twilio.rest import Client

account_sid = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

client = Client(account_sid, auth_token)
service = client.verify.services.create(
friendly_name='KORBEN VERIFICATION',
code_length=10,
totp_code_length=6,
totp_time_step=30,
totp_skew=2,
skip_sms_to_landlines=True,
)

Vous remarquerez que je donne un nom à mon service (friendly_name). Je peux également spécifier à ce niveau la longueur du code (code_length), la configuration du TOTP, ou encore préciser que je ne veux pas envoyer de SMS à un numéro de téléphone fixe. Il y a plusieurs paramètres disponibles dans la config du service que je vous invite à consulter dans la doc de l’API ici.

Ensuite, je vais envoyer un SMS au numéro de téléphone de mon utilisateur comme ceci :

verification = client.verify \
.services(service.sid) \
.verifications \
.create(to='+336xxxxxxxx', channel='<strong>sms</strong>')

print(verification.status)
print(verification.sid)

Vous pouvez voir que le canal est “SMS”. Si j’avais voulu mettre en place une vérification avec un appel téléphonique au lieu d’un SMS, j’aurais fait comme ceci :

.create(to='+336xxxxxxxx', channel='<strong>call</strong>')

En fonction du numéro de téléphone entré, le message audio / sms sera traduit dans la langue du pays associé au numéro. Mais vous pouvez également forcer une langue avec le paramètre “locale” comme ceci :

.create(locale='fr', to='+336xxxxxxxx', channel='<strong>call</strong>')

Pour Whatsapp, il suffira de spécifier “whatsapp” dans le channel. Et pour une validation par email, ce sera un peu différent puisque vous devrez configurer un mailer avant, avec un template, une adresse d’expédition… etc.

.create(to='[email protected]', channel='<strong>email</strong>')

Vient maintenant le moment de vérifier que le code rentré par l’utilisateur dans votre application est correcte. Pour cela on va utiliser la fonction “verification_checks” comme ceci :

verification_check = client.verify \
.services('xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx') \
.verification_checks \
.create(to='+336xxxxxxxx', code='<strong>1234</strong>')

print(verification_check.status)

Pensez bien à mettre l’ID du service généré lors de la création du service (le service.sid) ainsi que le code entré par l’utilisateur (j’ai mis “1234”) là.

Et voilà. En fonction de la réponse (“approved” ou “pending” dans verification_check.status) vous saurez si le code entré est correct ou non.

Super simple ça !

Alors ça, c’était pour la validation d’un code par SMS ou appel téléphonique.

Mettre en place une validation TOTP (double authentification)

TOTP c’est de l’authentification multifacteur. Vous allez voir, avec Verify c’est également super simple.

La première étape consiste à générer un « secret » et éventuellement un QR Code à scanner avec une application comme Authy ou Google Authenticator.

Pour ce faire (toujours en Python dans la démo), on va évidemment créer une connexion au service de Twilio comme dans le paragraphe précédent en n’oubliant pas de préciser les informations relatives au TOTP :

service = client.verify.services.create(
friendly_name='KORBEN VERIFICATION',
code_length=4,
totp_code_length=6,
totp_time_step=30,
totp_skew=2,
skip_sms_to_landlines=True,
)

Puis nous allons créer une entité qui représentera notre utilisateur :

entity = client.verify \
.services(service.sid) \
.entities \
.create(identity='<strong>identity</strong>')

print(entity.sid)
print(service.sid)

Cette entité aura son id (entity.sid) qui nous servira dans la mise en place de la double authentification.

Pour générer ensuite le “secret” que l’utilisateur devra entrer dans son application TOTP, vous devez créer un nouveau facteur comme ceci et récupérer le secret contenu dans new_factor.binding ainsi que l’URI associée.

new_factor = client.verify \
.services(service.sid) \
.entities(entity.sid) \
<strong>.new_factors</strong> \
.create(
friendly_name="Korben's Phone",
factor_type='totp'
)

print(new_factor.binding['secret'])
print(new_factor.binding['uri'])

Le secret obtenu peut alors être immédiatement importé dans une application comme Authy pour obtenir les codes 2FA associés (tokens).

otpauth://totp/KORBEN%20VERIFICATION:Korben%27s%20Phone?secret=<strong>LE_CODE_SECRET</strong>&issuer=KORBEN%20VERIFICATION&algorithm=SHA1&digits=6&period=30

Comme j’utilise Python, je vais utiliser la lib pyqrcode (pip install pyqrcode) et l’appeler comme ceci :

import pyqrcode
...
qr = pyqrcode.create(new_factor.binding['uri'])
qr.png('qr.png', scale=6)

Et voilà, je récupère un beau QR Code à scanner avec une application d’authentification.

factor = client.verify.services(service.sid) \
.entities(entity.sid) \
.factors(new_factor.sid) \
.update(auth_payload=<strong>code</strong>)
print(factor.status)

Les tarifs

Concernant le coût, cela va bien sûr dépendre du volume, mais pour le canal SMS, il vous en coûtera 0.05 $ par vérification réussie + le coût d’envoi du SMS en fonction du pays. Pour le canal e-mail, ce sera selon la tarification de SendGrid. Enfin, les canaux Push et TOTP sont inclus dans les frais de vérification et sont facturés lorsqu’une demande est approuvée ou refusée.

Si vous voulez en savoir plus, je vous invite à consulter le site de Twilio.