MFA で Auth0 の Unified Phone Experience を使用する

電話プロバイダーの設定を Unified Phone Experience に移行します。

開始前に

Unified Phone Experience に移行するには、次のいずれかの条件を満たしている必要があります。

• テナントで Multi-Factor Authentication (MFA) の SMS、音声、または SMS+音声通知が有効化され、設定済みである
• テナントでパスワードレス SMS が有効化され、設定済みである

MFA とパスワードレスのどちらも設定していない場合は、最初から設定を開始するために Configure Auth0’s Unified Phone Experience を参照してください。

MFA とパスワードレスの両方で異なるプロバイダーを使用している場合は、Custom Phone Provider を使用する必要があります。

Phone as ID を利用している場合は、自動的に Auth0 の Unified Phone Experience を使用しているため、追加の作業は不要です。

Unified Phone Experience では、すべての電話プロバイダー設定をテナント内の 1 か所に集約できます。電話認証要素ごとに電話プロバイダーを何度も設定する必要はありません。MFA の電話認証要素の詳細については、SMS and voice notifications for MFA を参照してください。

SMS and Voice notifications for Multi-Factor Authentication (MFA) 用の電話プロバイダーがすでに設定されている場合は、その設定を Unified Phone Experience に移行し、テナントレベルで適用できます。

テナントレベルのプロバイダーを使用している場合、電話メッセージが正常に送信されたかどうかは Auth0 からエンドユーザーに通知されません。問題をトラブルシューティングするには、tenant logs を確認してください。

​

電話プロバイダーを更新する

Unified Phone Experience を使用するには、次の手順を実行します:

• 現在の設定を確認する

• プロバイダーを設定する:

  • Twilio を設定する
  • カスタム電話プロバイダーを設定する

• 電話番号ファクターと配信方法を更新する

• Management API エンドポイントを更新する

• Auth0 Actions トリガーを更新する

​

現在の設定を確認する

1. 現在の MFA 設定を確認するには、Auth0 Dashboard > Security > Multi-factor Auth に移動します。

2. Phone Message を選択します。

3. 新しい Auth0 テナントでは Unified Phone Experience を使用でき、テナントの電話プロバイダーを設定するよう促すバナーが表示されます。

   

• 2025 年 3 月より前からある既存のテナントでは、Unified Phone Experience に加えて、MFA 用の SMS 通知と音声通知も設定できます。

  

Auth0 では Unified Phone Experience の使用を推奨しています。電話プロバイダーの設定に SMS and Voice notifications for Multi-Factor Authentication (MFA) を使用する必要があり、Use Tenant-Level Messaging Provider の切り替えが表示されない場合は、Auth0 Support にお問い合わせください。

4. テナント設定を確認するには、Dashboard > Tenant Settings に移動します。
5. Advanced を選択します。
6. Unified Phone Experience を探します。
   
7. 必要に応じて有効にします。

​

Twilio をテナントレベルのプロバイダーとして設定する

MFA の電話プロバイダーとして Twilio を使用している場合は、Unified Phone Experience に Twilio SID と AuthToken を追加する必要があります。Twilio SID は既存の設定からコピーできますが、AuthToken の値は Twilio から取得する必要があります。

1. Branding > Phone Provider に移動します。

2. プロバイダーを選択して設定します。

   

   1. 電話プロバイダーとして Twilio を選択します。

   2. 配信方法を選択します。

   3. Twilio の設定を入力します。

      使用する MFA 要素は、テナントレベルで設定した配信方法のサブセットである必要があります。

3. Save して変更を保存します。

4. 本番環境で使用する前に、Send Test Message を選択してテナントレベルのプロバイダーをテストします。

5. テナントレベルのプロバイダーを有効にします。

   1. MFA の場合は、Security > Multi-factor Auth > Phone Message. に移動します。

   2. Use Tenant-level Messaging Provider を選択します。

      テナントにトグルが表示されない場合は、すでに Unified Phone Experience を使用しています。

6. Save して変更を保存します。

​

Auth0 Actions を使用してカスタムプロバイダーを設定する

Unified Phone Experience では、カスタム電話通知に send-phone-message Actions Trigger ではなく、電話通知用の custom-phone-provider Actions Trigger を使用します。

次の理由により、send-phone-message Actions trigger を custom-phone-provider Actions trigger に直接移行することはできません。

• メッセージタイプと通知タイプの間に 1:1 の対応関係はありません。

• send-phone-message Actions trigger に関連付けられたシークレットや依存関係を移行すると、セキュリティ上の懸念が生じたり、テナントでの利用体験が損なわれたりする可能性があります。

• Actions は複数の trigger をサポートできるため、移行が難しい場合があります。たとえば、Actions は send-phone-message trigger と post-login trigger の両方をサポートできます。

• send-phone-message Actions trigger と custom-phone-provider Actions trigger でサポートされる event type は異なります。

  • send-phone-message は SMS と Voice の message type をサポートします。詳しくは、Action triggers: send-phone-message Event Object を参照してください。
  • custom-phone-provider は otp_verify、otp_enroll、blocked_account、change_password、password_breach の notification type をサポートします。詳しくは、Actions triggers: custom-phone-provider Event Object を参照してください。

• カスタム電話プロバイダーごとに設定できる Action は 1 つだけです。すでにカスタム電話プロバイダーに Action を設定している場合は、新しい Action に関連付ける前に、その Action を必ず無効にする必要があります。

そのため、既存の send-phone-message を、新しいコンテキスト変数を使用する新しい custom-phone-provider に変換する必要があります。

コアペイロード

send-phone-message context object	custom-phone-provider context object	ステータス
text	notification.as_text and notification.as_voice	更新
message_type	notification.message_type 値の違いに注意してください: second-factor-authentication と otp_enroll、verify と otp_verify	更新
action	notification.delivery_method	更新
language	notification.locale	更新
code	notification.code	更新
recipient	notification.recipient	更新

リクエストデータ

send-phone-message context object	テナントレベルのプロバイダーコンテキストオブジェクト	ステータス
ip	ip	変更なし
user_agent	user_agent	変更なし
language	language	更新
method	method optional	更新
hostname	hostname optional	更新
geoip	geoip	更新

テナントデータ

send-phone-message context object	テナントレベルのプロバイダーコンテキストオブジェクト	ステータス
tenant.id	tenant	更新
N/A	tenant.home_url	新規
N/A	tenant.logo_url	新規
N/A	tenant.support_email	新規
N/A	tenant.support_url	新規

アプリケーションデータ

send-phone-message context object	テナントレベルのプロバイダーコンテキストオブジェクト	ステータス
client.client_metadata	client.metadata	更新
client.client_id	client.client_id	変更なし
client.name	client.name	変更なし

ユーザーデータ

send-phone-message context object	テナントレベルのプロバイダーコンテキストオブジェクト	ステータス
user.user_id	user.user_id	変更なし
user.name	user.name	変更なし
user.email	user.email	変更なし
user.app_metadata	user.app_metadata	変更なし
user.user_metadata	user.user_metadata	変更なし
user.email_verified	user.email_verified	変更なし
user.phone_number	user.phone_number	変更なし
user.phone_verified	user.phone_verified	変更なし
user.picture	user.picture	変更なし
user.created_at	user.created_at	変更なし
user.updated_at	user.updated_at	変更なし
user.multifactor	user.multifactor	変更なし
user.identities	N/A	削除
user.family_name	user.family_name	変更なし
user.given_name	user.given_name	変更なし
user.nickname	user.nickname	変更なし
user.username	user.username	変更なし
N/A	user.login_count	新規

コンテキスト変数の完全な一覧については、Customize Phone Templates を参照してください。

カスタム電話番号プロバイダーの例を確認します。

const { fetch } = require('undici');
/**
* 電話通知の送信時に実行されるハンドラー
* @param {Event} event - ユーザーおよびログインコンテキストの詳細。
* @param {CustomPhoneProviderAPI} api - 電話通知の送信動作を変更するためのメソッドとユーティリティ。
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secrets['MY_ENDPOINT'], {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets['MY_SECRET']}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response.status); // 200
    console.log(await response.text()); // リクエストのレスポンスボディ!
  }

  return;
};

​

MFA custom-phone-provider を設定する

MFA custom-phone-provider トリガーを引き続き設定するには、次の手順を実行します。

1. Branding > Phone Provider に移動します。

2. プロバイダーを選択します。

   1. Custom を選択します。
   2. Provider Configuration で、埋め込みコードエディターに翻訳した send-phone-message Action コードを追加します。

3. 変更を Save します。

4. Send Test Message を選択し、本番環境で使用する前にテナントレベルのプロバイダーをテストします。

5. Security > Multi-factor Auth > Phone Message に戻り、Use Tenant-level Messaging Provider を有効にします。

6. 変更を Save します。

​

MFA の電話番号ファクターと配信方法を更新する

Auth0 Dashboard でテナントレベルのプロバイダーを有効にしていない場合、MFA の電話番号ファクターとして SMS と音声通話を設定することはできません。

Unified Phone Experience への移行中に、現在の通知用 MFA 要素を別の種類に変更する場合は、設定の変更が必要になることがあります。

現在の MFA 電話番号ファクター	目的の MFA 要素	テナントレベルの配信方法	ユーザーの操作
SMS	Voice	SMS	目的の MFA 電話番号ファクターを利用できるように、テナントレベルのプロバイダーを更新する必要があります
SMS	Voice	SMS + Voice	なし
SMS	SMS + Voice	SMS	目的の MFA 電話番号ファクターを利用できるように、テナントレベルのプロバイダーを更新する必要があります
SMS	SMS + Voice	SMS + Voice	なし
Voice	SMS	SMS + Voice	目的の MFA 電話番号ファクターを利用できるように、テナントレベルのプロバイダーを更新する必要があります
Voice	SMS	SMS + Voice	なし
Voice	SMS + Voice	Voice	目的の MFA 電話番号ファクターを利用できるように、テナントレベルのプロバイダーを更新する必要があります
Voice	SMS + Voice	SMS + Voice	なし
SMS + Voice	SMS	SMS + Voice	なし
SMS + Voice	Voice	SMS + Voice	なし

Unified Phone Experience への移行中に、現在のテナントレベルの電話プロバイダーの配信方法を別の種類に変更する場合は、設定の変更が必要になることがあります。

MFA 電話番号ファクター	現在のテナントレベルの配信方法	目的のテナントレベルの配信方法	ユーザーの操作
SMS	SMS	SMS + Voice	なし
SMS	SMS	Voice	MFA 電話番号ファクターが、テナントレベルのプロバイダーで有効になっている配信方法のサブセットになるように更新する必要があります
SMS	SMS + Voice	Voice	MFA 電話番号ファクターが、テナントレベルのプロバイダーで有効になっている配信方法のサブセットになるように更新する必要があります
SMS	SMS + Voice	SMS	なし
Voice	Voice	SMS	MFA 電話番号ファクターが、テナントレベルのプロバイダーで有効になっている配信方法のサブセットになるように更新する必要があります
Voice	Voice	SMS + Voice	なし
Voice	SMS + Voice	SMS	MFA 電話番号ファクターが、テナントレベルのプロバイダーで有効になっている配信方法のサブセットになるように更新する必要があります
Voice	SMS + Voice	Voice	なし
SMS + Voice	SMS + Voice	SMS	なし
SMS + Voice	SMS + Voice	Voice	なし

​

Management API を使用して Guardian エンドポイントを更新する

Unified Phone Experience では、通知に特定のエンドポイントを使用します。プッシュ通知およびワンタイムパスワードで Auth0 Guardian を使用している場合は、新しい Phone Provider Branding エンドポイントを使用するように設定を更新する必要があります。

次の Guardian エンドポイントは、Unified Phone Experience では使用できなくなります。

電話メッセージ送信用 Guardian エンドポイント	スコープ
Twilio 設定を取得する Twilio SMS 設定を取得する	read:guardian_factors
電話プロバイダーの設定を取得する 電話プロバイダーの SMS 設定を取得する	read:guardian_factors
Twilio 設定を更新する Twilio SMS 設定を更新する	update:guardian_factors
電話プロバイダーの設定を更新する SMS 設定を更新する	update:guardian_factors
登録および検証用の電話テンプレートを取得する SMS の登録および検証テンプレートを取得する	read:guardian_factors
登録および検証用の電話テンプレートを更新する SMS の登録および検証テンプレートを更新する	update:guardian_factors

Guardian エンドポイントを、新しい Phone Provider Branding エンドポイントとスコープに置き換えてください。

Phone Provider Branding エンドポイント	スコープ
テナントに設定されている電話プロバイダーを取得する 電話プロバイダーを取得する	read:phone_providers
電話プロバイダーを更新する	update:phone_providers
電話プロバイダーを設定する	create:phone_providers
電話通知テンプレートの一覧を取得する 電話通知テンプレートを取得する	read:phone_templates
電話通知テンプレートを更新する	update:phone_templates
電話通知テンプレートを作成する	create:phone_templates
電話テンプレートを削除する	delete:phone_templates
電話プロバイダーを削除する	delete:phone_providers

次の Guardian エンドポイントは Unified Phone Experience でも引き続き使用できるため、更新する必要はありません。

MFA 電話番号ファクターのエンドポイント	スコープ
有効な電話番号ファクターを取得	read:guardian_factors
有効な電話番号ファクターを更新	update:guardian_factors
電話プロバイダーの設定を取得	read:guardian_factors
電話プロバイダーの設定を更新	update:guardian_factors

​

電話プロバイダーを無効にする

Unified Phone Experience を構成してからこれを無効にすると、MFA を含む既存の電話プロバイダー連携が機能しなくなる可能性があります。