Configurer une passerelle SMS personnalisée pour les connexions Passwordless

Découvrez comment configurer une passerelle SMS personnalisée pour les connexions Passwordless.

Ce guide présente l’ancienne mise en œuvre SMS personnalisée pour les connexions Passwordless et s’applique uniquement aux tenants Auth0 créés avant mars 2025.

Les nouveaux tenants devraient suivre les instructions pour l’authentification Passwordless avec le phone provider SMS.

Ce guide vous montrera comment utiliser une passerelle SMS personnalisée pour envoyer vos codes à usage unique.

Par défaut, les connexions SMS Passwordless utilisent Twilio pour envoyer des codes à usage unique. Toutefois, si vous avez une passerelle SMS personnalisée, vous pouvez modifier votre connexion pour utiliser celle-ci à la place.

Auth0 ne prend pas en charge l’authentification SMS de base.

1. Configurez une connexion SMS Passwordless. Pour savoir comment faire, consultez la section Implement Passwordless dans Connexions Passwordless.
2. Obtenez un jeton d’accès pour la Management API. Vous en aurez besoin pour effectuer des appels à la Management API afin de mettre à jour votre connexion Passwordless.
3. Utilisez le point de terminaison GET Connections pour récupérer des renseignements sur les connexions associées à votre tenant. Plus précisément, vous devez obtenir l’ID de votre connexion SMS Passwordless afin de pouvoir l’utiliser plus tard dans un appel d’API servant à mettre à jour la connexion elle-même. Assurez-vous de remplacer ACCESS_TOKEN par le jeton que vous avez obtenu à l’étape 1 avant d’effectuer la requête suivante vers la Management API :

La réponse du point de terminaison sera un tableau d’objets. Chaque objet représente une connexion associée à votre tenant. 4. Repérez l’ID de votre connexion. Vous pouvez trouver l’ID associé à votre connexion Passwordless en examinant le tableau d’objets renvoyé par le point de terminaison GET Connections à l’étape 2. Pour trouver l’objet correspondant à votre connexion Passwordless, vous pouvez rechercher la propriété "name": "sms". Notez que la connexion affiche actuellement les renseignements Twilio que vous avez fournis lors de la configuration.

   [
       {
           "id": "con_UX85K7K0N86INi9U",
           "options": {
               "disable_signup": false,
               "name": "sms",
               "twilio_sid": "TWILIO_SID",
               "twilio_token": "TWILIO_AUTH_TOKEN",
               "from": "[phone]",
               "syntax": "md_with_macros",
               "template": "Your SMS verification code is: @@password@@",
               "totp": {
                   "time_step": 300,
                   "length": 6
               },
               "messaging_service_sid": null,
               "brute_force_protection": true
           },
           "strategy": "sms",
           "name": "sms",
           "is_domain_connection": false,
           "realms": [
               "sms"
           ],
       }
   ]

5. Mettez à jour la connexion. Vous pouvez le faire en envoyant une requête PATCH au point de terminaison Update a Connexion. Plus précisément, vous mettrez à jour l’objet options de la connexion pour fournir des renseignements sur la passerelle SMS.

   Vous devez envoyer l’objet options au complet avec chaque requête; sinon, vous écraserez les données existantes qui ne sont pas incluses dans les requêtes suivantes.

   Apportez les modifications suivantes :

   • Supprimez les paramètres twilio_sid et twilio_token
   • Ajoutez le paramètre provider et définissez sa valeur sur sms_gateway
   • Ajoutez le paramètre gateway_url et définissez sa valeur sur l’URL de votre passerelle SMS. Auth0 doit pouvoir accéder à cette URL pour utiliser votre passerelle et envoyer des messages en votre nom.

   Votre payload ressemblera à ceci :

   {
       "options": {
         "strategy": "sms",
         "provider": "sms_gateway",
         "gateway_url": "{urlOfYourGateway}",
         "from": "+1 234 567",
         "template": "Your verification code is: @@password@@",
         "brute_force_protection": true,
         "forward_req_info": "true",
         "disable_signup": false,
         "name": "sms",
         "syntax": "md_with_macros",
         "totp": {
           "time_step": 300,
           "length": 6
         }
       },
       "is_domain_connection": false,
   }
   

​

Requêtes authentifiées

Si votre passerelle SMS accepte des requêtes authentifiées au moyen de jetons, vous pouvez ajouter ce qui suit à votre objet options :

"gateway_authentication": {
    "method": "bearer",
    "subject": "urn:Auth0",
    "audience": "urn:MySmsGateway",
    "secret": "MySecretToSignTheToken",
    "secret_base64_encoded": false
}

Lorsque vous incluez gateway_authentication dans votre objet options, Auth0 ajoute un JSON Web Token dans l’en-tête Authorization chaque fois qu’il envoie des requêtes à votre passerelle SMS. Le jeton contient les valeurs gateway_authentication.subject et gateway_authentication.audience, et il est signé avec gateway_authentication.secret.

Si votre secret est encodé en base64url, définissez secret_base64_encoded sur true.

Après avoir mis à jour votre connexion, Auth0 enverra les éléments suivants à votre passerelle SMS chaque fois qu’un utilisateur s’inscrit ou se connecte avec votre connexion Passwordless.

{
  "recipient": "+1 399 999",
  "body": "Your verification code is: 12345",
  "sender": "+1 234 567"
}

Si vous définissez la propriété forward_req_info de l’objet options à true, la passerelle recevra aussi des informations issues de la requête HTTP qui a déclenché le processus Passwordless. Cela comprend l’adresse IP du client qui appelle /passwordless/start et son user agent.

{
  "recipient": "+1 399 999",
  "body": "Your verification code is: 12345",
  "sender": "+1 234 567",
  "req" : { 
      "ip" : "167.56.227.117",
      "user-agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36"
       }
}

​

Gestion des erreurs

Auth0 ne tiendra compte que du code HTTP renvoyé par la passerelle SMS ; il ignore le reste de la réponse (p. ex., le corps de la réponse et le type de réponse).

Si la passerelle SMS renvoie un code HTTP autre que 200, le point de terminaison /passwordless/start renverra un code HTTP 400 et une réponse semblable à celle-ci :

{
 "error":"sms_provider_error",
 "error_description":"Unexpected response while calling the SMS gateway: <HTTP Code Returned by the SMS Gateway>"}
}

Si la passerelle SMS renvoie HTTP 401, error_description sera Échec de l’authentification lors de l’appel à la passerelle SMS : 401. (Veuillez noter que le libellé de la description d’erreur peut changer à tout moment.)

Auth0 impose un délai d’expiration de 30 secondes pour les appels HTTP aux passerelles SMS personnalisées. Si la passerelle SMS ne répond pas dans ce délai, le point de terminaison /passwordless/start renverra également un code HTTP 400. La réponse aura le format indiqué ci-dessus et le champ error_description sera Délai d’expiration lors de l’appel à la passerelle SMS : <Code de délai d’expiration>. (Encore une fois, le libellé de la description d’erreur peut changer à tout moment.)