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

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

このガイドは、パスワードレス接続向けの従来のカスタム SMS 実装について説明するもので、2025 年 3 月より前に作成された Auth0 テナントにのみ適用されます。

新しいテナントでは、SMS 電話プロバイダーを使用したパスワードレス認証の手順に従ってください。

このガイドでは、カスタム SMS ゲートウェイを使用して使い捨てコードを送信する方法を説明します。

既定では、パスワードレス SMS 接続 は Twilio を使用して使い捨てコードを送信します。ただし、カスタム SMS ゲートウェイを利用している場合は、接続を変更してそちらを使用できます。

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

1. SMS のパスワードレス接続を設定します。方法については、Passwordless Connections の Implement Passwordless セクションを参照してください。
2. Management API 用のアクセストークンを取得します。これは、Management API を呼び出してパスワードレス接続を更新する際に必要です。
3. 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": "[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. 接続を更新します。これは、Update a Connection endpoint に PATCH リクエストを送信することで実行できます。具体的には、SMS Gateway に関する情報を指定するために、接続の options オブジェクトを更新します。

   呼び出しのたびに options オブジェクト全体を送信する必要があります。そうしないと、後続の呼び出しに含まれない既存のデータが上書きされます。

   次の変更を行います。

   • twilio_sid と twilio_token の両方のパラメーターを削除する
   • provider パラメーターを追加し、sms_gateway に設定する
   • gateway_url パラメーターを追加し、SMS Gateway の URL に設定する。Auth0 がこの URL にアクセスできる必要があります。これにより、Auth0 はこの gateway を使用して、ユーザーに代わってメッセージを送信できます。

   payload は次のようになります。

   {
       "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 で署名されます。

secret が base64-url エンコードされている場合は、secret_base64_encoded を true に設定します。

接続を更新すると、ユーザーが パスワードレス 接続でサインアップまたはログインするたびに、Auth0 は以下の内容を SMS Gateway に送信します。

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

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

{
  "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 Gateway から返された HTTP ステータスコードのみを参照し、それ以外のレスポンス (例: レスポンス本文やレスポンスタイプ) は無視します。

SMS Gateway から 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 Gateway から HTTP 401 が返された場合、error_description は SMS ゲートウェイ の呼び出し中に認証に失敗しました: 401 となります。 (エラー説明の文言は、予告なく変更される場合があることにご注意ください。)

Auth0 では、カスタム SMS Gateway への HTTP 呼び出しに 30 秒のタイムアウトが設定されています。SMS Gateway からこの時間内に応答がない場合、/passwordless/start エンドポイントも HTTP 400 を返します。レスポンスは上記の形式となり、error_description フィールドは SMS ゲートウェイ の呼び出し中にタイムアウトしました: <Timeout Code> となります。 (重ねてになりますが、エラー説明の文言は予告なく変更される場合があります。)