パスワードレス接続向けのカスタムSMSゲートウェイを設定する

このガイドは、パスワードレス接続向けの従来のカスタム SMS 実装について説明するもので、2025 年 3 月より前に作成された Auth0 テナントにのみ適用されます。新しいテナントでは、SMS 電話番号プロバイダーの設定手順に従ってください。

このガイドでは、カスタム SMS ゲートウェイを使用してワンタイムコードを送信する方法を説明します。デフォルトでは、パスワードレス SMS 接続は、ワンタイムコードの送信に Twilio を使用します。ただし、カスタム SMS ゲートウェイがある場合は、そのゲートウェイを使用するように接続を変更できます。

Auth0 は基本的な SMS 認証をサポートしていません。

SMS パスワードレス接続を設定します。手順については、パスワードレス接続の「Implement Passwordless」セクションを参照してください。
Management API のアクセストークンを取得します。これは、パスワードレス接続を更新するために Management API を呼び出す際に必要です。
GET Connections エンドポイントを使用して、テナントに関連付けられている接続の情報を取得します。具体的には、後続の API 呼び出しで接続自体を更新するときに使用する、パスワードレス SMS 接続の ID を取得する必要があります。次の Management API 呼び出しを実行する前に、ACCESS_TOKEN を手順 1 で取得したトークンに必ず置き換えてください。

エンドポイントからのレスポンスは、オブジェクトの配列です。各オブジェクトは、テナントに関連付けられた 1 つの接続を表します。 4. 接続 ID を特定します。手順 2 の GET Connections エンドポイントから返されたオブジェクト配列を確認すると、パスワードレス接続に対応する ID を確認できます。パスワードレス接続に該当するオブジェクトを見つけるには、"name": "sms" プロパティを検索します。その接続には現在、セットアップ時に指定した Twilio の情報が表示されていることを確認してください。

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

接続を更新します。これを行うには、Update a Connection endpoint に PATCH リクエストを送信します。具体的には、SMSゲートウェイに関する情報を指定するために、接続の options オブジェクトを更新します。
呼び出しのたびに options オブジェクト全体を送信する必要があります。そうしないと、後続の呼び出しで含まれていない既存のデータが上書きされます。
次の変更を行います。
- twilio_sid パラメーターと twilio_token パラメーターを削除する
- provider パラメーターを追加し、sms_gateway に設定する
- gateway_url パラメーターを追加し、SMSゲートウェイの URL に設定する。Auth0 がメッセージを代理送信する際にこの gateway を使用できるようにするには、Auth0 からこの URL にアクセスできる必要があります。
ペイロードは次のようになります。
```
{
    "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,
}
```

認証付きリクエスト

SMS Gateway がトークンベースの認証付きリクエストを受け付ける場合は、以下を options オブジェクトに追加できます。

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

options オブジェクトに gateway_authentication を含めると、Auth0 は SMS ゲートウェイにリクエストを送信するたびに、Authorization ヘッダーに JSON Web Token を追加します。このトークンには gateway_authentication.subject と gateway_authentication.audience の値が含まれ、gateway_authentication.secret で署名されます。シークレットが base64url エンコードされている場合は、secret_base64_encoded を true に設定します。接続を更新すると、ユーザーが接続でサインアップまたはログインするたびに、Auth0 は以下の情報を SMS ゲートウェイに送信します。

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

options オブジェクトの forward_req_info プロパティを true に設定すると、ゲートウェイはパスワードレスのプロセスを開始した HTTP リクエストの情報も受け取ります。これには、/passwordless/start を呼び出すクライアントの IP アドレスと 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"
       }
}

エラー処理

Auth0 は SMSゲートウェイから返される HTTP ステータスコードのみを参照し、それ以外のレスポンス (例: レスポンスボディやレスポンスタイプ) は無視します。 SMSゲートウェイが 200 以外の HTTP コードを返した場合、/passwordless/start エンドポイントは HTTP 400 コードと、次のようなレスポンスを返します。

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

SMSゲートウェイが HTTP 401 を返した場合、error_description は Authentication failed while calling the SMS gateway: 401 になります。 (エラーの説明文は、予告なくいつでも変更される可能性がある点にご注意ください。) Auth0 は、カスタム SMSゲートウェイへの HTTP 呼び出しに 30 秒のタイムアウトを設定しています。SMSゲートウェイがこの時間内に応答しない場合、/passwordless/start エンドポイントも HTTP 400 コードを返します。レスポンスは上記の形式となり、error_description フィールドは Timeout while calling the SMS gateway: <Timeout Code> になります。 (繰り返しになりますが、エラーの説明文は予告なくいつでも変更される可能性があります。)

​認証付きリクエスト

​エラー処理

認証付きリクエスト

エラー処理