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

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

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

• この機能では、MFA の選択フローをカスタマイズできます。MFA 登録フローをカスタマイズする場合は、Universal Login で MFA 登録をカスタマイズする を参照してください。
• Actions で MFA フローをカスタマイズできるのは、Universal Login を使用している場合のみです。
• ここで説明する一部の方法は Universal Login でのみ使用でき、クラシックログインでは使用できません。詳しくは、クラシックログイン向けに MFA をカスタマイズする を参照してください。

​

仕組み

Actions を使用すると、MFAフローをカスタマイズできます。具体的には、ログインフロー の post-login トリガーを、以下の Authentication API メソッドで変更できます。

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

• challengeWithAny: ユーザーが認証時に選択できる認証要素のグループを設定します。たとえば、email や 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 には、メソッド名が mfa に設定されている場合、type フィールドが含まれます。type は文字列で、enrolledFactors の type フィールドで使用される値 (上記の一覧) と一致する認証要素の値を含みます。MFAチャレンジが実行されると、methods には name:mfa のオブジェクトが含まれ、その type にはそのチャレンジで使用された認証要素が設定されます。methods が更新されるのは、Action が開始されたときだけです。チャレンジの結果を確認するには、フロー内の次の Action で methods にアクセスする必要があります。

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

• Actions Triggers: post-login - イベント オブジェクト
• Actions Triggers: post-login - API オブジェクト

​

順序付きフローとコンテキストベースのフロー

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

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

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

// アクション 1 

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

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

} 

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

// アクション 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 で利用できるユーザー情報を蓄積できます。一方、リダイレクトが発生するのは、フロー内の最後のコマンドとして 1 回だけです。
• challengeWith または challengeWithAny コマンドを含む各 Action の実行後に MFA がトリガーされます。リダイレクトの場合、MFA はパイプライン内の最後の Action として実行されます。

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

​

始める前に

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

​

テナントを準備する

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

• 設定手順の詳細については、Enable Multi-Factor Authentication を参照してください。
• 特定の認証要素の設定については、Multi-factor Authentication Factors を参照してください。

フローをカスタマイズするには、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 をログインフローにドラッグ＆ドロップし、Apply を選択します。

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

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

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

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

​

post-login Action をテストする

コマンドが正しく機能することを確認するには、Auth0 Dashboard から Action をテストできます。

• 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ロールを持ち、アプリケーションに対してより高いレベルのアクセスを必要とする場合は、ステップアップ認証の一環として、追加の認証要素でチャレンジします。

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(',') ?? [];

  // ユーザーが利用可能な認証要素とorgで有効な認証要素の積集合を取得する
  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;
  }

  // ユーザーが確認済みの電話番号を持ち、organizationが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;
  }

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

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

​

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

より柔軟なエクスペリエンスを提供するために、MFAチャレンジの一部として、ユーザーに別の方法を試すリンクを表示できます。このリンクを使うと、ユーザーはデフォルトのチャレンジとは異なる認証方法を選択できます。

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

特定の認証要素

次のサンプルでは、デフォルトでOTPによるチャレンジがユーザーに提示されます。必要に応じて、ユーザーは「別の方法を試す」リンクから、代わりにメールで認証できます。

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

登録済みの認証要素

次のサンプルでは、デフォルトでOTPによる認証が求められます。必要に応じて、ユーザーは「別の方法を試す」リンクから、登録済みの他の認証要素を使って認証できます。

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;
    }

      // MFAを要求するのは、ユーザーが少なくとも1つの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 を使用すると、ログインフローの 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 を完了できません。	mfar	このシナリオでは、次のエラーメッセージが表示されます。 PostLogin Action で MFA チャレンジが使用されていますが、要求された認証要素が適切に設定されていません。MFA を実行するには、要求された認証要素を有効にし、ユーザーがその認証要素に登録されていることを確認してください。
ユーザーに多要素認証が求められたものの、要求された認証要素の 1 つをチャレンジとして使用できない場合。この場合、ユーザーは要求された別の認証要素を使用して MFA を完了できます。	w	このシナリオでは、次の警告メッセージが表示されます。 PostLogin Action で MFA チャレンジが使用されていますが、要求された認証要素 {認証要素名} が適切に設定されていません。要求された認証要素を有効にし、ユーザーがその認証要素に登録されていることを確認してください。

​

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

以下のチェックリストでは、カスタマイズされた 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 tab の Multi-factor Authentication セクションを確認し、登録状況を確認してください。ユーザーが登録されていない場合は、このセクションにある Send an enrollment invitation リンクを使用できます。
     • または、Raw JSON tab でユーザーの登録状況を確認することもできます。この情報は Management API から取得することも可能です。ただし、メール確認リンクで設定された Email 認証要素のような自動登録された認証器は、API には一覧表示されない点に注意してください。

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

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

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

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

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