Universal Login の MFA 登録をカスタマイズ

post-login Actions を使用して、特定の認証要素への登録をユーザーに促すよう MFA フローをカスタマイズします。

Auth0 は、多要素認証 (MFA) によってユーザーアクセスを保護するための、さまざまな認証要素をサポートしています。post-login Actions を使用すると、特定の認証要素への登録をユーザーに促すように MFA フローをカスタマイズできます。ユーザーが認証要素を登録すると、以後のログインではその認証要素を第 2 の認証手段として使用できます。

また、コンテキスト情報を利用して、MFA 登録フローをさらに細かくカスタマイズすることもできます。たとえば、あるアプリケーションでは SMS への登録を促し、別のアプリケーションではプッシュ通知や WebAuthN への登録を促すことができます。

この機能を使うと、MFA 登録フローをカスタマイズできます。すでに登録済みのユーザー向けに MFA フローをカスタマイズしたい場合は、Universal Login の MFA 選択をカスタマイズ を参照してください。

​

仕組み

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

• enrollWith: 登録時にユーザーに提示するデフォルトの認証要素を指定します。必要に応じて、ユーザーが選択できる代替の認証要素の一覧を指定することもできます。指定した場合は、登録プロンプトに Try Another Method リンクが表示されます。

• enrollWithAny: 登録時にユーザーが選択できる認証要素のセットを指定します。デフォルトでは、このメソッドはユーザーが希望する認証要素を選べる選択プロンプトを表示します。場合によっては、ユーザー体験が次のように異なることがあります。

  • 2 つ以上の認証要素が指定されている場合は、選択プロンプトがユーザーに表示されます。
  • 指定された認証要素のうち、1 つを除くすべてにユーザーがすでに登録済みである場合は、選択プロンプトはスキップされ、残りの認証要素への登録が求められます。
  • 指定されたすべての認証要素にユーザーがすでに登録済みである場合は、コマンドは失敗し、ログインシーケンスは続行されます。

これらのメソッドを組み合わせて、MFA登録フローをカスタマイズできます。また、roles や最終ログイン日などのユーザーのメタデータを利用して、より個別化された体験を作成することもできます。

カスタマイズされた登録フローでは、次の認証要素がサポートされます。

• otp

• recovery-code

• push-notification

• phone

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

• webauthn-platform

• webauthn-roaming

ユーザーが認証要素に登録すると、その値が enrolledFactors に追加されます。このプロパティは、そのユーザーアカウントに関連付けられた有効な認証要素の一覧を表します。

配列 event.authentication.methods には、メソッド名が mfa に設定されている場合、type フィールドが含まれます。このフィールドには、enrolledFactors の type フィールドで使用されるものと一致する認証要素の値 (String) が含まれます。

MFA 登録が行われると、methods には、そのイベントで使用された認証要素が type に設定された name:mfa のオブジェクトが含まれます。methods と enrolledFactors は、Action が最初に開始された時点でのみ更新されます。登録イベントの結果には、フロー内の次の Action でアクセスできます。

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

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

​

順序立てられたコンテキスト対応フロー

enrollWith または enrollWithAny コマンドを使用すると、コンテキスト情報を利用して、ユーザーに提示する最適な登録方法や一連の登録を判断できます。

• enrollWith コマンドでは、初期またはデフォルトの認証要素と、代替の認証要素のリストを指定できます。ユーザーはコマンドごとに 1 つの認証要素にのみ登録できます。
• enrollWithAny コマンドでは、認証要素のリストを指定できます。指定した認証要素の順序によって、ユーザーに表示される順番が決まります。ユーザーはコマンドごとに 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) {
      // 管理者にはもう一つの認証要素を追加
      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 によるチャレンジでauthenticationを完了します。その後、セキュリティキー (webauthn-roaming) を登録するよう求められます。

ユーザーアカウントの安全を保つため、追加の認証要素を登録する前に、ユーザーは既存の enrolledFactors のいずれかを使って MFA チャレンジを完了する必要があります。この条件により、異なる認証要素や設定を持つアプリケーションがすでに使用された後でも、カスタムの MFA 登録ポリシーを安全に実装できます。

Action 1 の実行後、フローは一時停止し、Action 2 が実行される時点で event.user.enrolledFactors と event.authentication.methods の両方が更新されます。これにより、ユーザーが異なる認証要素でチャレンジするか登録するかを選べる場合でも、Action コードは実際のユーザーデータに基づいて判断できます。

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

​

始める前に

MFA フローをカスタマイズする前に、テナントで MFA を設定し、Customize MFA Factors using Actions 設定を有効にする必要があります。1 つ以上の認証要素を有効にし、Auth0 Dashboard の Security > Multi-factor Auth で MFA ポリシーを定義できます。

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

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

注: enrollWith または enrollWithAny コマンドを使用する Actions は、テナントで MFA を有効または無効にする既存のポリシーやルールよりも優先されます。

​

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

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

​

post-login Actionをテストする

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

1. Authentication > Authentication Profile に移動します。
2. 試す を選択して、新しいタブでサンプルのログインプロンプトを開きます。
3. 資格情報を入力し、新しい MFA フローをテストします。

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

​

使用例

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

​

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

以下のサンプルでは、デフォルトでOTPによる認証が求められます。必要に応じて、ユーザーは Try Another Method リンクからメール認証に切り替えることもできます。

​

トラブルシューティング

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

​

テナントログ

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

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

ご自身またはユーザーに想定外の動作が発生した場合は、以下のイベントコードに対応するテナントログを確認して詳細を把握してください。

状況	イベント	エラーメッセージ
ユーザーが特定の認証要素への登録を求められています。ただし、要求された認証要素が次のいずれかの条件に該当します。 その認証要素がテナントで有効になっていない。 その認証要素がユーザーのブラウザーでサポートされていない。 ユーザーがすでに要求された認証要素に登録している。 この場合、代替の認証要素が利用可能であれば、ユーザーはフローを完了できます。	w	PostLogin アクションで MFA登録が使用されていますが、要求された認証要素 ${factor.name} が正しく設定されていません。要求された認証要素を有効にし、ユーザーがまだその認証要素に登録していないことを確認してください。
ユーザーが1つ以上の認証要素への登録を求められていますが、指定された認証要素は登録に使用できません。この場合、ユーザーはフローを完了できません。	mfar	PostLogin アクションで MFA登録が使用されていますが、要求された認証要素が正しく設定されていません。MFA を実行するには、要求された認証要素を有効にし、ユーザーがまだそれらに登録していないことを確認してください。
ユーザーが、既存の登録を使用した少なくとも1つのチャレンジを完了せずに、新しい認証要素に登録しようとしています。	mfar	MFA登録が要求されましたが、ユーザーはすでに MFA に登録済みです。新しい認証要素に登録する前に、既存の認証要素を少なくとも1つ使ってチャレンジしてください。

​

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

以下のチェックリストは、カスタマイズした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 がデプロイ済みで、パイプラインに保存されていることを確認します。

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

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

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