Universal Login の MFA 選択をカスタマイズする

post-login Actions を使用して MFA フローをカスタマイズし、特定の認証要素またはその組み合わせでユーザーに追加認証を求めます。

Auth0 は、多要素認証 (MFA) でユーザーアクセスを保護するためのさまざまな認証要素をサポートしています。post-login Actions を使用すると、特定の認証要素または認証要素の組み合わせでユーザーに追加認証を求めるように MFA フローをカスタマイズできます。また、ユーザーやその組織に関するコンテキスト情報を使用して、より個別化された体験を作成することもできます。たとえば、特定の組織への所属や割り当てられたユーザーロールに基づいて、特定の認証要素でユーザーに追加認証を求めるようにフローをカスタマイズできます。

• この機能では、MFA の選択フローをカスタマイズできます。MFA の登録フローをカスタマイズする場合は、Universal Login で MFA 登録をカスタマイズする を参照してください。
• Actions で MFA フローをカスタマイズできるのは、Universal Login を使用している場合のみです。
• ここで説明している一部のメソッドは Universal Login でのみ使用でき、Classic Login では使用できません。詳細については、Classic Login の MFA をカスタマイズする を参照してください。

​

仕組み

MFA フローをカスタマイズするには、Actions を使用できます。具体的には、次の Authentication API メソッドを使用して、Login Flow の post-login トリガーをカスタマイズできます。

• challengeWith: ワンタイムパスワード (OTP) など、ユーザーが認証に使用する必要がある認証要素を指定します。このメソッドはユーザーにデフォルトのチャレンジを提示し、必要に応じて別の認証方法を選択できる認証要素ピッカーへのアクセスを提供することもできます。

• challengeWithAny: メールアドレスや OTP など、認証時にユーザーが選択できる認証要素のグループを設定します。デフォルトでは、このメソッドは特定のチャレンジではなく認証要素ピッカーをユーザーに提示します。動作条件は次のとおりです。

  • 2 つ以上の認証要素が指定されている場合、認証要素ピッカーが表示されます。
  • ユーザーが指定された認証要素のうち 1 つにしか登録していない場合 (または指定された認証要素が 1 つ בלבדの場合) 、認証要素ピッカーはスキップされます。
  • ユーザーが指定された認証要素のいずれにも登録していない場合、コマンドは失敗します。

これらのメソッドを組み合わせて使用することで、必要に応じて MFA フローを調整できます。また、ロールや過去に使用した認証要素などのユーザーメタデータをこれらのメソッドに組み込むことで、より細かく調整されたフローを作成することもできます。

コマンドの MFA チャレンジを選択する際は、以下の認証要素、または enrolledFactors の値を使用できます。enrolledFactors は、ユーザーのアカウントに関連付けられた有効な認証要素の一覧を表します。

• otp

• email

• push-notification

  • otpFallback

• phone

  • preferredMethod: voice
  • preferredMethod: sms
  • preferredMethod: both

• webauthn-platform

• webauthn-roaming

配列 event.authentication.methods には、メソッドの name が mfa に設定されている場合、type フィールドが含まれます。type は文字列で、enrolledFactors の type フィールドで使用される認証要素の値 (上記参照) と一致する値を含みます。MFA チャレンジが実行されると、methods には name:mfa のオブジェクトが含まれ、その type にはそのチャレンジで使用された認証要素が設定されます。methods が更新されるのは、Action の開始時のみです。チャレンジの結果を確認するには、フロー内の次の Action で methods にアクセスする必要があります。

詳しくは、以下のリソースを参照してください。

• Actions Triggers: post-login - Event Object
• Actions Triggers: post-login - API Object

​

シーケンスフローとコンテキストフロー

challengeWith または challengeWithAny コマンドを使用すると、コンテキスト情報に基づいて、ユーザーに提示する最適なチャレンジやチャレンジの組み合わせを判断できます。具体的には、次のことが可能です。

• シーケンスフロー: 複数の異なる認証要素によるチャレンジを、特定の順序でユーザーに提示します。
• コンテキストフロー: フロー内のそれまでのチャレンジに基づいて、次にどの認証要素でユーザーにチャレンジするかを判断します。

これらのフローをわかりやすく示すために、次の例を見てみましょう。

// ACTION 1 

exports.onExecutePostLogin = async (event, api) => {

   api.authentication.challengeWithAny([{ type: 'phone'}, { type: 'push-notification' }]);

} 

// ============================================ 

// ACTION 2 

// 前のアクションでユーザーが行った操作に基づいて判断する 

exports.onExecutePostLogin = async (event, api) => { 

    if(event.authentication.methods.find(m => m.type === 'phone') && event.authorization?.roles.includes('admin')) { 

        api.authentication.challengeWith({ type: 'push-notification' }); 

    }

}

このシナリオでは、まず Action 1 で challengeWithAny コマンドを使用して、ユーザーに SMS によるチャレンジを求めます。次に、ユーザーは Admin のユーザーロールを持ち、かつ SMS チャレンジも完了しているため、Action 2 でプッシュ通知によるチャレンジを求めます。

このフローでは、次の理由から、ユーザーにどの認証要素でチャレンジするかを判断できます。

1. Action 1 の実行後にフローが一時停止します。
2. ユーザーが Action 1 によって要求された MFA フローを完了します。
3. Action 2 の event.authentication.methods.type に、直前の MFA チャレンジの情報が設定されます。
4. Action 1 のコンテキスト情報を使用してフローが再開され、Action 2 が実行されます。

この例で示す動作は、Actions でリダイレクトを使用する場合と似ていますが、challengeWith および challengeWithAny を使用するコマンドには、次の固有の利点があります。

• 各コマンドの後でフローが一時停止するため、後続の Actions で利用できるユーザー情報を蓄積できます。一方、リダイレクトはフロー内の最後のコマンドとして一度だけ発生します。
• challengeWith または challengeWithAny コマンドを含む各 Action の実行後に MFA がトリガーされます。リダイレクトでは、MFA はパイプライン内の最後の Action として実行されます。

注: このような Actions の実行方法は、challengeWith または challengeWithAny コマンドを含むものにのみ適用されます。ほかの目的の Actions には影響しません。

​

始める前に

MFA フローをカスタマイズする前に、まずテナントで MFA を有効にし、ユーザーに適切な認証要素を登録するよう求める必要があります。

​

テナントを準備する

開始するには、テナントで MFA を設定し、Customize MFA Factors using Actions 設定を有効にします。1 つ以上の認証要素を設定し、Security > Multifactor Auth にある Auth0 Dashboard で MFA ポリシーを定義できます。

• セットアップ手順の詳細については、多要素認証を有効にする を参照してください。
• 特定の認証要素の設定については、多要素認証の要素 を参照してください。

フローをカスタマイズするには、Additional Settings セクションで Customize MFA Factors using Actions トグルを必ず有効にする必要があります。この設定が有効になっていないと、カスタマイズしたフローは正しく動作しません。

• challengeWith および challengeWithAny コマンドを呼び出す Actions は、api.multifactor.enable によって有効になっているチャレンジをすべて上書きします。また、Define Policies で使用できる MFA 設定よりも優先されます。
• ユーザーがアプリケーションへのアクセスを試みる際に MFA を完了できるようにするには、Require Multi-factor Auth 設定を Use Adaptive MFA または Always のいずれかに設定してください。Actions コードが実行されない場合、この設定がバックアップとして機能し、ユーザーが MFA を回避するのを防ぎます。
• コマンドでリスク評価を使用する場合は、Adaptive MFA Risk Assessment トグルを有効にし、post-login Actions コードで event.authentication.riskAssessment を使用してください。

​

ユーザーを認証要素に登録する

MFA を設定したら、有効化した認証要素のうち 1 つ以上にユーザーが登録されるようにしてください。ユーザーは、post-login Action コマンドでチャレンジされる前に、認証手段に登録しておく必要があります。

ユーザーがサインアップした後、またはテナント内で作成された後は、Management API の authentication-methods エンドポイントを使用して登録情報を作成できます。また、Auth0 Dashboard のユーザープロファイルページから、ユーザーの登録を直接管理することもできます。

​

MFA フローをカスタマイズする

テナントの準備ができたら、post-login Actions を作成して MFA フローをカスタマイズできます。手順とユースケース例を以下に示します。

テナント内の Actions (または一連の Actions) では、1 回のユーザーフローにつき、次のコマンドのうち 4 つ までしか実行できません。

• enrollWith
• enrollWithAny
• challengeWith
• challengeWithAny

この上限を超えると (つまり、この種の 5 つ目のコマンドが実行されようとすると) 、認証エラーが発生します。

​

Post-Login Action を作成する

1. Auth0 Dashboard で Actions > Flows に移動し、Login を選択します。

2. Add Action で Custom を選択し、Create Action をクリックします。

3. Create Action ポップアップで、以下を設定します。

   • Action の名前を入力します。
   • トリガーとして Login / Post-Login を選択します。
   • ランタイムには Node 22 (Recommended) を使用します。

4. ポップアップの内容が正しいことを確認し、Create を選択します。

5. 作成後、コードエディターに onPostExecute が表示されます。このハンドラーにカスタムコードまたはコードサンプルを追加します。

6. コードの準備ができたら、Deploy を選択します。

7. デプロイ成功の通知で Add to Flow を選択します。

   • 注: 通知が閉じている場合は、コードエディターの上にある Back to Flow を選択します。

8. Add Action パネルから新しい Action を Login フローにドラッグ＆ドロップし、Apply を選択します。

Action をさらに更新するには、Actions > Library > Custom に移動して対象の Action を選択します。その後、必要に応じてコードを更新し、再デプロイできます。

MFA フローにリダイレクトを追加する場合は、ユーザーが MFA をスキップまたは回避できないように、Action が次の条件を満たしていることを確認してください。

• リダイレクト (sendUserTo) は、MFA の処理とは別の Action に含める必要があります。
• リダイレクト Action は、フロー内で最後に実行される Action である必要があります。

リダイレクトの詳細については、Redirect with Actions を参照してください。

​

post-login Action をテストする

Action が想定どおりに機能することを確認するには、Auth0 Dashboard からテストできます。

• Authentication > Authentication Profile に移動します。
• Try を選択して、新しいタブでサンプルのログインプロンプトを開きます。
• 認証情報を入力し、新しい MFA フローをテストします。

フローが正常に完了すると、確認画面が表示されます。問題が発生した場合は、Auth0 Dashboard の Actions > Library > Custom に移動してコードを更新できます。

​

使用例

以下に、MFA フローをカスタマイズする際の一般的なユースケースを示します。

​

現在の登録認証要素に基づいてチャレンジ方法を決定する

次のサンプルでは、ユーザーが以下の認証要素を登録済みの場合に、MFA チャレンジを実行します。

• ワンタイムパスワード (OTP)
• 電話番号

exports.onExecutePostLogin = async (event, api) => {

 api.authentication.challengeWithAny([{type: 'otp'}, {type: 'phone'}]);

}

​

ロールを使用してチャレンジ方法を決定する

次のサンプルでは、すべてのユーザーに OTP を求めます。ユーザーが Admin ロールを持ち、アプリケーションに対してより高いレベルのアクセスが必要な場合は、step-up authentication の一環として追加の認証要素を求めます。

exports.onExecutePostLogin = async (event, api) => {
    api.authentication.challengeWith({type: 'otp'});

    const isAdmin = event.authorization?.roles.includes('admin');
    if(isAdmin) {
        api.authentication.challengeWith({type: 'phone'});
    }
}

​

メタデータを使用してチャレンジ方法を判断する

この例では、MFA 認証要素は組織レベルで有効になっています。このサンプルでは、異なる種類のメタデータを使用して、各ユーザーに適したチャレンジを判断します。

• 組織メタデータ: 特定の組織で有効になっている認証要素など、組織レベルのデータ。
• ユーザーメタデータ: ユーザーのプロフィールに電話番号が関連付けられているかどうかなど、ユーザーレベルのデータ。

exports.onExecutePostLogin = async (event, api) => {
  const orgFactors = event.organization?.metadata.factors.split(',') ?? [];

  // ユーザーが利用可能なファクターと組織で有効なファクターの積集合を取得する
  const availableFactors = orgFactors.filter(f => event.user?.enrolledFactors?.some(ef => ef.type === f));

  // 利用可能であればプッシュを優先する
  if(availableFactors.includes('push-notification')) {
    api.authentication.challengeWith({ type: 'push-notification' });
    return;
  }

  // ユーザーが確認済みの電話番号を持ち、組織がSMSとメールアドレスを
  // 許可している場合、SMSを優先し、利用可能であれば
  // メールアドレスをフォールバックとして使用する
  if(event.user.phone_number && 
     event.user.phone_verified && 
     availableFactors.includes('phone')) {
    if(availableFactors.includes('email')) {
      api.authentication.challengeWith({ type: 'phone' }, {
        additionalFactors: [{
          type: 'email'
        }]
      });
    } else {
      api.authentication.challengeWith({ type: 'phone' });
    }

    return;
  }

  // プッシュ通知や電話番号を優先できなかった場合、組織で有効であれば
  // メールアドレスにフォールバックし、そうでなければ拒否する。
  if(availableFactors.includes('email')) {
    api.authentication.challengeWith({ type: "email" });
    return;
  }

  api.access.deny("No MFA factors available for this org + user");
};

​

ユーザーが別の認証方法を選択できるようにする

より柔軟に利用できるように、MFA チャレンジの一部として Try Another Method リンクをユーザーに表示できます。このリンクを使うと、ユーザーはデフォルトのチャレンジとは異なる認証方法を選択できます。

これを実現するには、Actions コードに additionalFactors パラメーターを含めます。このパラメーターは、すべてのユーザーに対して特定の認証要素を設定することも、enrolledFactors を使用してユーザーが希望する認証要素を選べるようにすることもできます。

特定の認証要素

次のサンプルでは、デフォルトで OTP によるチャレンジをユーザーに要求します。必要に応じて、ユーザーは Try Another Method リンクから、代わりにメールアドレスで認証できます。

exports.onExecutePostLogin = async (event, api) => {
  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: [{type: 'email'}] })
};

登録済みの認証要素

次のサンプルでは、既定でユーザーに OTP による認証を求めます。必要に応じて、ユーザーは「Try Another Method」リンクから、登録済みの別の認証要素を使用して認証できます。

exports.onExecutePostLogin = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));

  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: enrolledFactors })
};

​

Adaptive MFA を使用して、ユーザーにいつ追加認証を求めるかを判断する

次の例では、ユーザーに追加認証を求めるべきかどうかを判断するために Adaptive MFA を使用します。

Adaptive MFA は柔軟な MFA ポリシーであり、ログイン トランザクション中の潜在的なリスクを評価し、必要に応じてユーザーに追加の認証を求めることで、悪意のある攻撃者 からテナントを保護します。

このケースでは、ユーザーが見慣れないデバイスからログインし、全体の信頼度スコアが低または中の場合に、MFA が要求されます。

/**
* PostLoginフローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - ユーザーおよびログインコンテキストの詳細。
* @param {PostLoginAPI} api - ログインの動作を変更するために使用できるメソッドのインターフェース。
*/
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication?.riskAssessment?.assessments.NewDevice) {

  // 条件の例: NewDeviceの信頼度レベルのみに基づいてMFAを要求する。
    // 未知のデバイスからログインした場合にMFAを要求する。
    let shouldPromptMfa;

    switch (event.authentication.riskAssessment.assessments.NewDevice.confidence) {
      case 'low':
      case 'medium':
        shouldPromptMfa = true;
        break;
      case 'high':
        shouldPromptMfa = false;
        break;
      case 'neutral':
        // このアセッサーが信頼度に関する有用な情報を持たない場合、
        // MFAを要求しない。
        shouldPromptMfa = false;
        break;
    }

      // ユーザーが少なくとも1つのMFA認証要素を登録している場合にのみ
      // MFAを要求する意味がある。
    const canPromptMfa = event.user.enrolledFactors?.length > 0;

    if (shouldPromptMfa && canPromptMfa) {
      const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));
      api.authentication.challengeWithAny(enrolledFactors);
    }

  }

};

​

Actions を使用してユーザーに追加認証を要求する

Actions を使用すると、Login Flow の post-login トリガーを変更して MFA フローをカスタマイズできます。この例では、認証方法として phone と preferredMethod: 'both' を使用しており、ユーザーのアカウントに関連付けられている有効な MFA 認証要素を参照します。詳細については、Actions Triggers: post-login - Event Object を参照してください。

api.authentication.challengeWith({ 
  type: 'phone', 
  options: { preferredMethod: 'both'} 
});

​

トラブルシューティング

カスタマイズした MFA フローでエラーや想定外の結果が発生した場合は、以下の情報を参考にして問題を特定し、解決してください。

​

テナントログ

カスタマイズした MFA フローは、テナントログ で監視できます。

テナントログは、Auth0 Dashboard の Monitoring > Logs で確認できます。あるいは、Management API を使用してログを取得することもできます。

お客様またはユーザーに想定外の動作が発生した場合は、詳細を確認するために、次のイベントコードについてテナントログを確認してください。

シナリオ	イベントコード	エラーの説明
ユーザーに MFA が求められたものの、要求された認証要素のいずれもチャレンジに使用できません。この場合、ユーザーは MFA を完了できません。	mfar	このシナリオでは、次のエラーメッセージが表示されます。 PostLogin Action で MFA チャレンジが使用されていますが、要求された認証要素が適切に設定されていません。MFA を実行するには、要求された認証要素を有効にし、ユーザーがそれらに登録されていることを確認してください。
ユーザーに MFA が求められたものの、要求された認証要素の 1 つをチャレンジに使用できません。この場合、ユーザーは要求された別の認証要素を使用して MFA を完了できます。	w	このシナリオでは、次の警告メッセージが表示されます。 PostLogin Action で MFA チャレンジが使用されていますが、要求された認証要素 {factor name} が適切に設定されていません。要求された認証要素を有効にし、ユーザーがそれに登録されていることを確認してください。

​

トラブルシューティング チェックリスト

次のチェックリストでは、カスタマイズした MFA フローでよくある問題を特定して解決するための追加の確認事項を示します。

1. Customize MFA factors with Actions トグルを有効にする必要があります。

   • Auth0 Dashboard > Security > Multi-factor Auth に移動し、Additional Settings セクションのトグルが有効になっていることを確認します。

2. Actions で参照している認証要素が、テナントで有効になっている必要があります。

   • コードを確認する: Auth0 Dashboard > Actions > Library > Custom に移動し、Actions のコードを確認します。参照しているすべての認証要素がユースケースに適していることを確認します。
   • 認証要素を確認する: Auth0 Dashboard > Security > Multi-factor Auth に移動し、Actions で参照しているすべての認証要素が有効になっていることを確認します。

3. ユーザーは、Actions で参照している認証要素に登録されている必要があります。

   • 特定のユーザーでエラーが発生している場合は、そのユーザーの詳細を確認し、適切な認証要素に登録されていることを確認します。Auth0 Dashboard > User Management > Users に移動し、一覧からそのユーザーの名前を選択します。

     • Detail タブの Multi-factor Authentication セクションを確認して、登録状況を確認します。ユーザーが登録されていない場合は、このセクションにある Send an enrollment invitation リンクを使用できます。
     • または、Raw JSON タブでユーザーの登録状況を確認することもできます。この情報は Management API を使用して取得することもできます。ただし、メール確認リンクで設定された Email 要素など、自動登録された認証手段は API には一覧表示されない点に注意してください。

   • ユーザーが適切な認証要素に登録されていない場合は、Management API の authentication-methods エンドポイントを使用して登録を作成できます。ユーザーの登録状況は、Auth0 Dashboard のプロフィールページから直接管理することもできます。

4. Actions がデプロイされ、Pipeline に保存されていることを確認します。

   • Auth0 Dashboard > Actions > Library > Custom に移動します。一覧で Action を見つけ、ステータスが Deployed であることを確認します。別のステータスが表示されている場合は、Action を開いてコードを確認し、右上の Deploy をクリックします。
   • Auth0 Dashboard > Actions > Library > Flows に移動し、Login を選択します。フローに Action が表示されていることを確認します。表示されていない場合は、Add Action パネルの Custom タブを開き、Action を Login フローにドラッグ アンド ドロップします。その後、Apply を選択します。

5. post-login Actions を最新バージョンにアップグレードしていることを確認します。

   • Auth0 Dashboard > Actions > Library > Custom に移動し、Action を選択します。Action が古い場合は、Action の更新を促す黄色のバナーが表示されます。バナーが表示されたら、Update を選択します。
   • Deploy CLI を使用する場合は、post-login Actions の最新バージョンをデプロイ対象として指定することもできます。詳細については、Deploy CLI を構成する を参照してください。