Configurer une passerelle SMS personnalisée pour les connexions Passwordless

Ce guide présente l’ancienne implémentation SMS personnalisée pour les connexions Passwordless et s’applique uniquement aux locataires Auth0 créés avant mars 2025.Les nouveaux locataires doivent suivre les instructions d’authentification Passwordless avec un fournisseur de téléphone SMS.

Ce guide explique 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 disposez d’une passerelle SMS personnalisée, vous pouvez modifier votre connexion pour l’utiliser à la place.

Auth0 ne prend pas en charge l’authentification SMS standard.

Configurez une connexion SMS Passwordless. Pour savoir comment faire, consultez la section Implement Passwordless dans Connexions Passwordless.
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.
Utilisez le point de terminaison GET Connections pour récupérer des renseignements sur les connexions associées à votre locataire. Plus précisément, vous devez obtenir l’ID de votre connexion SMS Passwordless afin de pouvoir l’utiliser dans un appel API ultérieur pour mettre à jour la connexion. Assurez-vous de remplacer ACCESS_TOKEN par le jeton que vous avez obtenu à l’étape 1 avant d’effectuer l’appel suivant à la Management API :

La réponse du point de terminaison sera un tableau d’objets. Chaque objet représente une connexion associée à votre locataire. 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 informations Twilio que vous avez fournies pendant le processus de configuration.

   [
       {
           "id": "con_UX85K7K0N86INi9U",
           "options": {
               "disable_signup": false,
               "name": "sms",
               "twilio_sid": "TWILIO_SID",
               "twilio_token": "TWILIO_AUTH_TOKEN",
               "from": "+15555555555",
               "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"
           ],
       }
   ]

Mettez à jour la connexion. Vous pouvez le faire en envoyant une requête PATCH au point de terminaison Mettre à jour une connexion. Plus précisément, vous allez mettre à jour l’objet options de la connexion afin de fournir des informations sur la passerelle SMS.
Vous devez envoyer l’objet options dans son intégralité à chaque appel; 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 attribuez-lui la valeur sms_gateway
- Ajoutez le paramètre gateway_url et attribuez-lui l’URL de votre passerelle SMS. Auth0 doit pouvoir joindre cette URL pour utiliser votre passerelle afin d’envoyer des messages en votre nom.
Votre charge utile 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 les requêtes authentifiées par jeton, 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 à 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é à l’aide de gateway_authentication.secret. Si votre secret est encodé en base64url, définissez secret_base64_encoded à true. Une fois la connexion mise à jour, Auth0 enverra ce qui suit à votre passerelle SMS chaque fois qu’un utilisateur s’inscrit ou se connecte avec votre connexion .

{
  "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 également des informations sur la requête HTTP qui a déclenché le processus Passwordless. Cela comprend l’adresse IP de l’application qui appelle /passwordless/start et son agent utilisateur.

{
  "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 tient compte que du code HTTP renvoyé par la passerelle SMS; il ignore le reste de la réponse (p. ex., le corps 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 ainsi qu’une réponse semblable à la suivante :

{
 "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 un code 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 de l’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 d’expiration>. (Là encore, le libellé de la description de l’erreur peut changer à tout moment.)

​Requêtes authentifiées

​Gestion des erreurs

Requêtes authentifiées

Gestion des erreurs