メインコンテンツへスキップ
Auth0 は、多要素認証 (MFA) でユーザーアクセスを保護するためのさまざまな認証要素をサポートしています。post-login Actions を使用すると、 フローをカスタマイズして、ユーザーに特定の認証要素への登録を促すことができます。ユーザーが認証要素を登録すると、以後のログインでその要素を追加の認証方法として使用できます。 コンテキスト情報を使用して、MFA 登録フローをさらに細かくカスタマイズすることもできます。たとえば、あるアプリケーションでは SMS への登録を促し、別のアプリケーションではプッシュ通知または WebAuthn への登録を促すことができます。 この機能を使用すると、MFA 登録フローをカスタマイズできます。すでに登録済みのユーザー向けの MFA フローをカスタマイズする場合は、Universal Login の MFA 選択をカスタマイズする を参照してください。

​
仕組み

Actions を使用して、MFA の登録フローをカスタマイズできます。具体的には、次の Authentication API メソッドを使用して、Login Flow の post-login トリガーを変更できます。
  • enrollWith: 登録時にユーザーに提示するデフォルトの認証要素を指定します。必要に応じて、ユーザーが選択できる代替の認証要素リストを指定することもできます。これを指定すると、登録プロンプトに［別の方法を試す］リンクが表示されます。
  • enrollWithAny: 登録時にユーザーが選択できる認証要素のセットを指定します。デフォルトでは、このメソッドは、ユーザーが希望する認証要素を選択できる選択プロンプトを表示します。場合によっては、ユーザー体験が次のように変わることがあります。
    • 2 つ以上の認証要素が指定されている場合は、選択プロンプトがユーザーに表示されます。
    • 指定された認証要素のうち 1 つを除いて、ユーザーがすでにすべてに登録済みの場合は、選択プロンプトはスキップされ、残っている認証要素への登録が求められます。
    • 指定された認証要素のすべてにユーザーがすでに登録済みの場合は、コマンドは失敗し、ログイン シーケンスは続行されます。
これらのメソッドを組み合わせて使用することで、MFA の登録フローをカスタマイズできます。また、ロールや最終ログイン日時などのユーザー メタデータを取り入れて、より個別最適化された体験を作成することもできます。 カスタマイズされた登録フローでは、次の認証要素がサポートされます。
  • otp
  • recovery-code
  • push-notification
  • phone
    • preferredMethod: voice
    • preferredMethod: sms
    • preferredMethod: both
  • webauthn-platform
  • webauthn-roaming
ユーザーが認証要素に登録すると、その値が enrolledFactors に追加されます。このプロパティは、そのユーザー アカウントに関連付けられている有効な認証要素の一覧を表します。 配列 event.authentication.methods には、メソッドの名前が mfa に設定されている場合、type フィールドが含まれます。このフィールドには、enrolledFactors の type フィールドで使用される値と一致する認証要素の値 (文字列) が格納されます。 MFA の登録が発生すると、methods には name:mfa のオブジェクトが含まれ、type にはそのイベントで使用された認証要素が設定されます。methods と enrolledFactors は、Action の開始時にのみ更新されます。登録イベントの結果には、フロー内の次の Action でアクセスできます。 詳細については、次のリソースを参照してください。

​
順序指定フローとコンテキストベースのフロー

enrollWith または enrollWithAny コマンドを使用すると、コンテキスト情報に基づいて、ユーザーに提示する最適な登録方法や登録の組み合わせを判断できます。
  • enrollWith コマンドは、最初に提示する、またはデフォルトで選択する認証要素と、代替の認証要素のリストをサポートします。ユーザーが 1 回のコマンドで登録できる認証要素は 1 つだけです。
  • enrollWithAny コマンドは、認証要素のリストをサポートします。指定した認証要素の順序によって、ユーザーに表示されるリストの順番が決まります。ユーザーが 1 回のコマンドで登録できる認証要素は 1 つだけです。
これらのコマンドを使用すると、次のことが可能です。
  • 順序指定フロー: 特定の順序で複数の認証要素にユーザーを登録します。
  • コンテキストベースのフロー: メタデータやフロー内の前のコマンドに基づいて、どの認証要素のプロンプトをユーザーに表示するかを決定します。
これらのフローをわかりやすく示すため、次の例を見てみましょう。 
// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // 登録済み、チャレンジを実行
    api.authentication.challengeWithAny(event.user.enrolledFactors.map(m => ({type: m.type})));
    if (event.user.app_metadata.isAdmin &&
        !event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
          // 管理者かつセキュリティキーが未登録の場合（別の要素が使用されたことを意味する）、今すぐ登録
          api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
  }
  else {
    // 未登録；今すぐ登録する要素を選択
    api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    if (event.user.app_metadata.isAdmin) {
      // 管理者向けにもう1つの要素を追加
      api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    }
  }
};

// Action 2

exports.onExecutePostLogin = async (event, api) => {
  function performed(type) {
    return event.authentication.methods.some(m => m.name === 'mfa' &&
           m.type === type &&
           Date.now() - new Date(m.timestamp).getTime() < 5000)
  }
  if (event.user.app_metadata.isAdmin) {
      // 未使用の要素にチャレンジすることで、両方の要素が必ず使用されるよう強制
      if (!performed('webauthn-roaming')) {
        api.authentication.challengeWith({type: 'webauthn-roaming'})
      }
      else if (!performed('otp')) {
        api.authentication.challengeWith({type: 'otp'})
      }
  }
};
これら 2 つの Actions を組み合わせると、admin ロールを持たないユーザーは、ワンタイムパスワード (OTP) またはセキュリティキーのいずれかに登録する必要があります。逆に、admin ロールを持つユーザーは、両方の認証要素に登録する必要があります。 Action 1 は app_metadata を確認してユーザーが admin かどうかを判定し、そのうえで特定の要素への登録を促します。admin ユーザーが OTP にしか登録していない場合は、まず認証を完了するために OTP でチャレンジを実行します。その後、セキュリティキー (webauthn-roaming) への登録を求められます。
ユーザーアカウントの安全を保つため、追加の要素に登録する前に、ユーザーは既存の enrolledFactors のいずれかを使用して MFA チャレンジを完了する必要があります。この条件により、異なる要素や構成を持つアプリケーションがすでに使用されたあとでも、カスタムの MFA 登録ポリシーを安全に実装できます。
Action 1 の実行後、フローは一時停止し、Action 2 の実行時に event.user.enrolledFactors と event.authentication.methods の両方が更新されます。これにより、ユーザーに異なる要素でチャレンジするか登録するかの選択肢が提示された場合でも、Action コードは実際のユーザーデータに基づいて判断できます。 注: この Actions の実行方法は、enrollWith または enrollWithAny コマンドを含むものにのみ適用されます。その他の目的の Actions には影響しません。

​
始める前に

MFA フローをカスタマイズする前に、テナントで MFA を設定し、[Actions を使用して MFA 認証要素をカスタマイズ] 設定を有効にする必要があります。1 つ以上の認証要素を有効にし、 の Security > Multi-factor Auth で MFA ポリシーを定義できます。 フローをカスタマイズするには、Additional Settings セクションで [Actions を使用して MFA 認証要素をカスタマイズ] トグルを有効にする必要があります。この設定を有効にしていないと、カスタマイズしたフローは正しく動作しません。
Auth0 Dashboard > Security > Multi-factor Auth > Additional Settings
注: enrollWith または enrollWithAny コマンドを含む Actions は、テナントで MFA を有効または無効にする既存のポリシーや Rules をすべて上書きします。

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

テナントで MFA を設定した後、post-login Actions を作成して MFA 登録フローをカスタマイズできます。
テナント内の Actions (または一連の Actions) では、1 回のユーザーフローにつき、次のコマンドを実行できるのは 4 回 までです。
  • enrollWith
  • enrollWithAny
  • challengeWith
  • challengeWithAny
この上限を超えた場合 (つまり、この種類のコマンドの 5 回目の実行が試行された場合) 、認証エラーが発生します。

​
Post-Login Action を作成する

Auth0 Dashboard では Actions を作成できます。
  1. Actions > Flows に移動し、Login を選択します。
  2. Add Action パネルで プラス記号 (+) アイコンを選択し、Build from scratch を選びます。
  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 を選択します。
保存後にさらに変更を加えるには、Actions > Library > Custom に移動して対象の Action を選択します。その後、必要に応じてコードを更新し、再デプロイできます。

​
Post Login Action をテストする

コマンドが想定どおりに機能することを確認するには、Auth0 Dashboard から Action をテストできます。
  1. Authentication > Authentication Profile に移動します。
  2. Try を選択し、新しいタブでサンプルのログインプロンプトを開きます。
  3. 認証情報を入力して、新しい MFA フローをテストします。
フローが正常に完了すると、確認画面が表示されます。問題が発生した場合は、Auth0 Dashboard の Actions > Library > Custom に移動してコードを更新できます。

​
使用例

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

​
ユーザーに登録用のMFAオプションを提示する

次のサンプルでは、デフォルトでユーザーにOTPによる認証を求めます。必要に応じて、ユーザーは 別の方法を試す リンクを選択して、代わりにメールアドレスで認証できます。

​
トラブルシューティング

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

​
テナントログ

カスタマイズした MFA 登録は、テナントログで監視できます。 テナントログは、Auth0 Dashboard の Monitoring > Logs で確認できます。また、Management API を使用してログを取得することもできます。 お客様またはユーザーに想定外の動作が発生した場合は、以下のイベントコードについてテナントログを確認し、詳細を把握してください。
シナリオイベントエラーメッセージ
ユーザーに特定の認証要素での登録が求められます。ただし、要求された認証要素は次のいずれかの条件に該当します。
  • その認証要素がテナントで有効になっていない。
  • その認証要素がユーザーのブラウザーでサポートされていない。
  • ユーザーがすでに要求された認証要素に登録済みである。
この場合、代替の認証要素が利用可能であれば、ユーザーはフローを完了できます。		wMFA 登録が PostLogin Action で使用されていますが、要求された認証要素 ${factor.name} が正しく設定されていません。要求された認証要素を有効にし、ユーザーがその認証要素にまだ登録していないことを確認してください。
ユーザーに 1 つ以上の認証要素での登録が求められますが、指定された認証要素を登録に使用できません。この場合、ユーザーはフローを完了できません。mfarMFA 登録が PostLogin Action で使用されていますが、要求された認証要素が正しく設定されていません。MFA を実行するには、要求された認証要素を有効にし、ユーザーがそれらにまだ登録していないことを確認してください。
ユーザーが、既存の登録を使ったチャレンジを少なくとも 1 回完了しないまま、新しい認証要素への登録を試みる。mfarMFA 登録が要求されましたが、ユーザーはすでに MFA に登録済みです。新しい認証要素に登録する前に、少なくとも 1 つの既存の認証要素でチャレンジを完了してください。

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

次のチェックリストでは、カスタマイズした MFA フローでよくある問題を特定して解決するための追加のヒントを示します。
  1. Customize MFA factors with Actions トグルが有効になっている必要があります。
  2. Actions で参照している認証要素は、テナントで有効になっている必要があります。
  3. Actions がデプロイされ、パイプラインに保存されていることを確認します。
    1. Auth0 Dashboard > Actions > Library > Custom に移動します。一覧で Action を見つけ、ステータスが Deployed になっていることを確認します。別のステータスが表示されている場合は、その Action を開いてコードを確認し、右上の Deploy をクリックします。
    2. Auth0 Dashboard > Actions > Library > Flows に移動し、Login を選択します。Action がフロー内に表示されていることを確認します。表示されていない場合は、Add Action パネルの Custom tab を開き、Action を Login フローにドラッグアンドドロップします。その後、Apply を選択します。
  4. post-login Actions の最新バージョンにアップグレードしていることを確認します。
    • Auth0 Dashboard > Actions > Library > Custom に移動し、Action を選択します。Action が最新でない場合は、Action の更新を促す黄色のバナーが表示されます。バナーが表示された場合は、Update を選択します。
    • Deploy CLI を使用している場合は、デプロイ時に post-login Actions の最新バージョンを指定することもできます。詳細については、Deploy CLI を設定する を参照してください。