ユニバーサルログインに対するMFA登録をカスタイズする

Auth0は多要素認証（MFA）でユーザーアクセスを確保するための様々な要素をサポートしています。ポストログインアクションを使用することで、MFAフローをカスタマイズし、指定要素でユーザーにに登録を促します。要素でユーザーが登録をした後、その要素を今後のログインの認証の2番目のメソッドとして使用できます。

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

この機能を使用すると、MFA登録フローをカスタマイズすることができます。すでに登録されているユーザーのMFAフローをカスタマイズしたい場合、「ユニバーサルログインに対するMFA選択をカスタイズする」を参照してください。

アクションを使用して、MFA登録フローをカスタマイズできます。具体的には、ログインフローのポストログイントリガーを、以下の認証APIメソッドを使用して変更できます：

• enrollWith：登録時にユーザーに表示されるデフォルトの要素を指定します。オプションで、ユーザーが選択できる要素の代替リストを提供することも可能です。提供される場合、「別のメソッドを試す」リンクが登録プロンプトに表示されます。

• enrollWithAny：登録時にユーザーが選択できる要素のセットを指定します。デフォルトでは、このメソッドは、ユーザーが希望する要素を選択できる選択プロンプトを表示します。場合によっては、ユーザーエクスペリエンスが異なる場合があります。

  • 複数の要素が指定された場合、選択プロンプトがユーザーに表示されます。

  • ユーザーが1つを除く他のすべての指定された要素で登録済みの場合は、選択プロンプトはスキップされ、ユーザーは残りのファクターで登録するように促されます。

  • ユーザーがすべての指定された要素で登録済みの場合は、コマンドは失敗し、ログインシーケンスは継続します。

これらのメソッドを組み合わせて、MFA登録フローをカスタマイズできます。ロールや最後にログインした日付などのユーザーメタデータを組み込んで、よりカスタマイズされたエクスペリエンスを作成することもできます。

カスタマイズされた登録フローは次の要素をサポートします。

• otp

• recovery-code

• push-notification

• phone

  • preferredMethod: voice

  • preferredMethod: sms

  • preferredMethod: both

• webauthn-platform

• webauthn-roaming

ユーザーが要素で登録した後、その値はenrolledFactorsに追加されます。このプロパティは、ユーザーアカウントに関連したアクティブ要素のリストを示します。

メソッド名がmfaに設定されている場合、配列event.authentication.methodsにはtypeフィールドが含まれます。このフィールドには、enrolledFactorsのtypeフィールドで使用されるものと一致する因子値（文字列）が含まれます。

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

詳しくは、以下のリソースをご確認ください:

• アクションのトリガー：ログイン後 - イベントオブジェクト

• アクションのトリガー：ログイン後 - APIオブジェクト

enrollWithやenrollWithAnyコマンドを使用することで、コンテキスト情報を活用してユーザーに提示する最適な登録や一連の登録を決定できます。

• enrollWithコマンドは、初期またはデフォルトの要素と代替のリストをサポートします。ユーザーはコマンドごとに1つの要素のみを登録できます。

• enrollWithAnyコマンドは要素のリストをサポートします。指定された要素の順序によって、リストがユーザーにどのように表示されるかが決まります。ユーザーはコマンドごとに1つの要素のみを登録できます。

これらのコマンドを使用すると、次のことが可能になります。

• シーケンス化されたフロー：ユーザーに対して、特定の順序に並べた、一連の要素で登録します。

• コンテキストに基づくフロー：フロー内での以前のコマンドに基づいて、どの要素でユーザーに促すかを決定します。

これらのフローを説明するために、次の例を考えてみましょう:

// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // already enrolled, challenge
    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')) {
          // if is admin and doesn't have a security key, meaning a different factor was used, enroll now
          api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
  }
  else {
    // not enrolled; choose a factor to enroll now
    api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    if (event.user.app_metadata.isAdmin) {
      // one more factor for admins
      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) {
      // enforce both factors are used by challenging the one that has not been used yet
      if (!performed('webauthn-roaming')) {
        api.authentication.challengeWith({type: 'webauthn-roaming'})
      }
      else if (!performed('otp')) {
        api.authentication.challengeWith({type: 'otp'})
      }
  }
};

これら2つのアクションを組み合わせると、管理者ロールを持たないユーザーがワンタイムパスワード（OTP）またはセキュリティ キーのいずれかを使用して登録する必要があるシナリオが作成されます。逆に、管理者ロールを持つユーザーは、両方の要素に登録する必要があります。

アクション1は、app_metadataを確認してユーザーが管理者であるかどうかを判断し、特定の要素に登録するようユーザーに促します。管理者ユーザーがOTPのみに登録している場合は、最初にOTPを入力して認証を完了する必要があります。次に、セキュリティキー（webauthn-roaming）を使用して登録するように促されます。

アクション1の実行後、フローは一時停止し、アクション2の実行時にevent.user.enrolledFactorsとevent.authentication.methodsの両方が更新されます。これにより、ユーザーにさまざまな要素に異議を申し立てるか登録するかの選択肢が与えられたときに、アクションコードは実際のユーザーデータに基づいて決定を下すことができます。

注意：アクションを実行するこの方法は、enrollWithまたはenrollWithAnyコマンドを含むものにしか適用されません。その他の目的を果たすアクションに影響はありません。

MFAフローをカスタマイズする前に、テナントでMFAをセットアップし、アクション設定を使用して、MFA要素のカスタマイズを有効にします。［Auth0 Dashboard（Auth0ダッシュボード）］の［Security（セキュリティ）］>［Multi-factor Auth（多要素認証Auth）］から、1つ以上の要素を設定し、MFAポリシーを定義することができます。

• 設定プロセスについての詳細は、「多要素認証を有効にする」をご覧ください。

• 指定要素の構成についての詳細は、「多要素認証の要素」をご覧ください。

フローのカスタマイズには、［追加設定］セクションのアクショントグルを使用して、［MFA要素のカスタマイズ］を有効にする必要があります。この設定が無効になっている場合、カスタマイズされたフローは、正常に作動しません。

注意：enrollWithまたはenrollWithAnyコマンドを使用したアクションは、テナントでMFAを有効または無効にする既存のポリシーまたはルールをオーバーライドします。

テナントにMFAを設定した跡、ログイン後のアクションを作成してMFA登録フローをカスタマイズできます。

アクションをAuth0 Dashboardで作成できます。

1. ［Actions（アクション）］>［Flows（フロー）］に移動し、［Login（ログイン）］を選択します。

2. 追加アクションパネルで、プラス記号(+)アイコンを選択し、［Build from scratch（ゼロから構築）］を選択します。

3. アクションの作成のポップアップでの表示:

   • アクションの名前を入力します。

   • トリガーとして、 ログイン/ポストログインを選択します。

   • ランタイムには、Node 18（推奨）を使用します。

4. 正確性のために、ポップアップをご確認ください。その後、 ［作成］を選択します。

5. コードエディターでは、カスタムコードをonPostExecuteコマンドに追加します。

6. コマンドの準備が整ったら、［導入］を選択します。

7. 成功した導入通知で［フローの追加］を選択します。

   • 注意：通知が閉じられている場合、コードエディターの上の［Back to Flow（フローに戻る）］を選択します。

8. 新しいコマンドを「アクションの追加」パネルから、ログインフローにドラッグアンドドロップします。その後、［適用］を選択します。

保存後に追加の変更を行う場合、［Actions（アクション）］>［Library（ライブラリ）］>［Custom（カスタム）］に移動し、アクションを選択します。その後、必要な時にコードの更新と再導入ができます。

コマンドが適切に機能するように、Auth0 Dashboardを通じてアクションをテストできます:

1. ［認証］>［認証プロファイル］に移動します。

2. ［試す］を選択し、新しいタブでログインプロンプトのサンプルを開きます。

3. 資格情報を入力し、新しいMFAフローをテストします。

フローが成功したら、確認画面が表示されます。問題が生じたら,、Auth0 Dashboardの［Actions（アクション）］>［Library（ライブラリ）］>［Custom（カスタム）］に移動し、コードを更新することができます。

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

次のサンプルでは、デフォルトで、OTPでユーザーにチャレンジを行います。必要であれば、ユーザーは「他の方法を試す」リンクにアクセスし、代わりにメールで認証することができます。

カスタマイズされたMFA登録でエラーや予期しない結果が発生した場合は、以下の情報を使用して問題を特定し解決するのに役立ててください。

テナントログを通じて、カスタマイズされたMFA登録を監視できます。

テナントログは、Auth0 Dashboardの［Monitoring（モニタリング）］>［Logs（ログ）］から利用可能です。その他に、Management APIを使用して、ログを取得します。

予期しない動作が発生した場合は、次のイベントコードのテナントログを確認して、詳細情報を得てください。

以下のチェックリストは、カスタマイズされたMFAフローに関する一般的な問題を特定し解決するための追加の提案を提供します。

1. 「アクションでMFA要素をカスタマイズする」トグルを有効にする必要があります。

   • ［Auth0 Dashboard（Auth0ダッシュボード）］>［Security（セキュリティ）］>［Multi-factor Auth（多要素認証）］に移動し、［追加設定］セクションのトグルが有効になっていることを確認してください。

2. アクションで参照されるファクターは、テナントで有効にする必要があります。

   • コードを確認する:［Auth0 Dashboard（Auth0ダッシュボード）］>［Actions（アクション）］>［Library（ライブラリ）］>［Custom（カスタム）］に移動し、アクションコードを確認します。参照されたすべての要素が、ユースケースに適用可能であることを確認してください。

   • 要素を確認する:［Auth0 Dashboard（Auth0ダッシュボード）］>［Security（セキュリティ）］>［Multi-factor Auth（多要素認証）］に移動し、アクションで参照されたすべての要素が有効になっていることを確認してください。

3. アクションが導入され、パイプラインに保存されていることを確認してください。

   1. ［Auth0 Dashboard（Auth0ダッシュボード）］>［Actions（アクション）］>［Library（ライブラリ）］>［Custom（カスタム）］に移動します。リストからアクションを見つけ、ステータスが「導入済み」になっていることを確認してください。異なるステータスが表示 されている場合、アクションにアクセスし、コードを確認したのち,右上の［導入］をクリックします。

   2. ［Auth0 Dashboard（Auth0ダッシュボード）］>［Actions（アクション）］>［Library（ライブラリ）］>［Flows（フロー）］に移動し、 ［ログイン］を選択します。アクションがフローに表示されていることを確認してください。表示されていない場合、［アクションの追加］パネルの［カスタム］タブにアクセスし、ログインフローにアクションをドラッグアンドドロップします。その後、［適用］を選択します。

4. ポストログインアクションが最新バージョンにアップグレードされていることを確認してください。

   • ［Auth0 Dashboard（Auth0ダッシュボード）］>［Actions（アクション）］>［Library（ライブラリ）］>［Custom（カスタム）］に移動し、アクションを選択します。アクションが古い場合、アクションの更新を促す黄色のバナーが表示されます。バナーが表示された場合、［Update（更新）］を選択します。

   • Deploy CLIを使用する際には、ポストログインアクションの最新バージョンを指定して導入することもできます。詳しくは、「Deploy CLIを構成する」をご覧ください。