Configurar una puerta de enlace SMS personalizada para conexiones sin contraseña

Esta guía corresponde a la implementación personalizada heredada de SMS para conexiones sin contraseña y solo se aplica a los inquilinos de Auth0 creados antes de marzo de 2025.Los inquilinos nuevos deben seguir las instrucciones de autenticación sin contraseña con proveedor telefónico SMS.

Esta guía le mostrará cómo usar una puerta de enlace SMS personalizada para enviar códigos de un solo uso. De forma predeterminada, las conexiones SMS sin contraseña usan Twilio para enviar códigos de un solo uso. Sin embargo, si tiene una puerta de enlace SMS personalizada, puede modificar su conexión para usarla en su lugar.

Auth0 no admite la autenticación básica por SMS.

Configure una conexión SMS sin contraseña. Para saber cómo hacerlo, lea la sección Implement Passwordless en Passwordless Connections.
Obtenga un Token de acceso para la Management API. Lo necesitará para realizar llamadas a la Management API y actualizar su conexión sin contraseña.
Use el endpoint GET Connections para recuperar información sobre las conexiones asociadas a su inquilino. En concreto, debe obtener el id de su conexión SMS sin contraseña para poder usarlo en una llamada posterior a la API que actualiza la propia conexión. Asegúrese de reemplazar ACCESS_TOKEN por el token que obtuvo en el paso 1 antes de realizar la siguiente llamada a la Management API:

La respuesta del endpoint será un array de objetos. Cada objeto representa una conexión asociada a tu inquilino. 4. Identifica el ID de tu conexión. Puedes encontrar el ID asociado a tu conexión sin contraseña revisando el array de objetos que obtuviste del endpoint GET Connections en el paso 2. Para encontrar el objeto específico de tu conexión sin contraseña, puedes buscar la propiedad "name": "sms". Ten en cuenta que la conexión muestra actualmente la información de Twilio que proporcionaste durante el proceso de configuración.

   [
       {
           "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"
           ],
       }
   ]

Actualiza la conexión. Puedes hacerlo haciendo una llamada PATCH al endpoint Update a Connection. En concreto, actualizarás el objeto options de la conexión para proporcionar información sobre la puerta de enlace SMS.
Debes enviar el objeto options completo en cada llamada; de lo contrario, sobrescribirás los datos existentes que no se incluyan en las llamadas posteriores.
Realiza los siguientes cambios:
- Elimina los parámetros twilio_sid y twilio_token
- Agrega el parámetro provider y asígnale el valor sms_gateway
- Agrega el parámetro gateway_url y asígnale la URL de tu puerta de enlace SMS. Auth0 debe poder acceder a esta URL para usar tu puerta de enlace y enviar mensajes en tu nombre.
La carga útil tendrá un aspecto similar a este:
```
{
    "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,
}
```

Peticiones autenticadas

Si tu puerta de enlace SMS acepta peticiones autenticadas basadas en tokens, puedes agregar lo siguiente al objeto options:

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

Cuando incluyes gateway_authentication en el objeto options, Auth0 agrega un JSON Web Token al encabezado Authorization cada vez que envía solicitudes a tu puerta de enlace SMS. El token contiene los valores gateway_authentication.subject y gateway_authentication.audience, y está firmado con gateway_authentication.secret. Si tu secreto está codificado en base64-url, establece secret_base64_encoded en true. Una vez que hayas actualizado tu conexión, Auth0 enviará lo siguiente a tu puerta de enlace SMS cada vez que un usuario se registre o inicie sesión con tu conexión de .

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

Si establece la propiedad forward_req_info del objeto options en true, la puerta de enlace también recibirá información de la solicitud HTTP que inició el proceso de autenticación sin contraseña. Esto incluye la dirección IP del cliente que llama a /passwordless/start y su agente de usuario.

{
  "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"
       }
}

Manejo de errores

Auth0 solo tendrá en cuenta el código HTTP que devuelva la puerta de enlace SMS; ignorará el resto de la respuesta (por ejemplo, el cuerpo y el tipo de respuesta). Si la puerta de enlace SMS devuelve un código HTTP distinto de 200, el endpoint /passwordless/start devolverá un código HTTP 400 y una respuesta similar a la siguiente:

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

Si la puerta de enlace SMS devuelve un HTTP 401, error_description será La autenticación falló al llamar a la puerta de enlace SMS: 401. (Tenga en cuenta que la redacción de la descripción del error puede cambiar en cualquier momento.) Auth0 establece un tiempo de espera de 30 segundos para las llamadas HTTP a puertas de enlace SMS personalizadas. Si la puerta de enlace SMS no responde dentro de ese plazo, el endpoint /passwordless/start también devolverá un código HTTP 400. La respuesta tendrá el formato que se muestra arriba y el campo error_description será Tiempo de espera al llamar a la puerta de enlace SMS: <Timeout Code>. (De nuevo, la redacción de la descripción del error puede cambiar en cualquier momento.)

​Peticiones autenticadas

​Manejo de errores

Peticiones autenticadas

Manejo de errores