ユーザーMFA管理

My Account API を使用して、ユーザー自身が多要素認証の認証要素を登録、表示、削除できるカード形式の UI をレンダリングする方法を説明します。

UserMFAManagement コンポーネントを使用すると、ユーザーは My Account API を通じて、自身の多要素認証の認証要素を単一のカードベースのインターフェースで登録、表示、削除できます。

My Account API の認証方法管理機能を使用して、ユーザーの認証方法を管理するための包括的な UI をレンダリングします。

UserMFAManagement コンポーネントを使用すれば、ナビゲーションを制御したり、API エンドポイントを呼び出したり、state を管理したりする必要はありません。

​

サポート対象の認証要素

このコンポーネントは、My Account API で設定されたすべての認証方法に対応しています。

認証要素	コンポーネントがレンダリングする内容
Email OTP	メールアドレス入力 → 6 桁の OTP 検証
SMS OTP	国番号の選択 + 電話番号の入力 → 6 桁の OTP 検証
TOTP (認証器アプリ)	手動入力用キー付き QR コード → 6 桁の OTP 検証
プッシュ通知	Auth0 Guardian で読み取る QR コード → 「承認待ち」状態
パスキー	説明画面 → OS の生体認証プロンプト → リスト内の登録済みエントリ
リカバリーコード	コピー操作と「コードを保存しました」の確認を含む、一度だけ表示されるコードのリスト

​

アプリケーションを設定する

フレームワークを選択して、環境変数とUniversal Componentsを構成します。

React（SPA）

​

設定要件

UserMFAManagement コンポーネントをレンダリングする前に、Build Account Security UI を参照して、Auth0 テナントとアプリケーションを設定してください。

​

MFA方式とスコープを有効にする

MFA方式を有効にする

1. Dashboard > Security > Multi-factor Auth に移動します。
2. 使用する認証要素を有効にします。詳細については、Multi-Factor Authentication Factors を参照してください。

My Account API の権限を設定する

Build Account Security UI に従って、My Account API のユーザー委譲アクセス権限を設定します。認証方式の管理フローを完全に利用するには、5 つすべての権限が必要です。

​

コンポーネントをインストールする

pnpm

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form と @tanstack/react-query はピア依存関係です。このコマンドでは、共有ユーティリティと Auth0 連携に必要な @auth0/universal-components-core の依存関係もインストールされます。

​

はじめに

import { UserMFAManagement } from "@auth0/universal-components-react";

export function SecurityPage() {
  return <UserMFAManagement />;
}

• コンポーネントは、フレームワークに関係なく、常にルートエントリ @auth0/universal-components-react からインポートします。
• フレームワーク固有のサブパスを使用するのは Auth0ComponentProvider コンポーネントのみです。React アプリケーションでは /spa、Next.js アプリケーションでは /rwa を使用します。

統合の完全な例

import React from "react";
import { UserMFAManagement } from "@auth0/universal-components-react";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: {
            title: "Two-Factor Authentication",
            description: "Manage the extra verification methods used to protect your account.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Next.js（RWA）

​

設定要件

UserMFAManagement コンポーネントをレンダリングする前に、Build Account Security UI の手順に従って、Auth0 テナントとアプリケーションを設定してください。

​

MFA方式とスコープを有効にする

MFA方式を有効にする

1. Dashboard > Security > Multi-factor Auth に移動します。
2. 使用する認証要素を有効にします。詳しくは、Multi-Factor Authentication Factors を参照してください。

My Account API の権限を設定する

Build Account Security UI で、My Account API のユーザー委譲アクセス権限を設定します。認証方式を完全に管理するフローには、5 つすべての権限が必要です。

​

コンポーネントをインストールする

pnpm

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form と @tanstack/react-query はピア依存関係です。このコマンドでは、共有ユーティリティと Auth0 連携に必要な @auth0/universal-components-core 依存関係もインストールされます。

​

はじめに

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";

export default function SecurityPage() {
  return <UserMFAManagement />;
}

連携の完全な例

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";
import { analytics } from "@/lib/analytics";

export default function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

shadcn

​

設定要件

UserMFAManagement コンポーネントをレンダリングする前に、Build Account Security UI の手順に従って、Auth0 テナントとアプリケーションを設定してください。

​

MFA方式とスコープを有効にする

MFA方式を有効にする

1. Dashboard > Security > Multi-factor Auth に移動します。
2. 必要な認証要素を有効にします。詳しくは、Multi-Factor Authentication Factors を参照してください。

My Account API の権限を設定する

Build Account Security UI で、My Account API のユーザー委譲アクセス権限を設定します。認証方式を完全に管理するフローには、5 つすべての権限が必要です。

​

コンポーネントをインストールする

npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json

インストールコマンドを実行すると、コンポーネントのソースが、すべてのUI依存関係と、共有ユーティリティおよびAuth0連携用の@auth0/universal-components-core依存関係とともにsrc/components/auth0/my-account/に追加されます。

​

はじめに

import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";

export function SecurityPage() {
  return <UserMFAManagement />;
}

連携の完全な例

import React from "react";
import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

​

プロップス

​

表示プロップス

表示プロップスは、コンポーネントの動作に影響を与えずに、レンダリング方法を制御します。

プロップ	型	デフォルト	説明
hideHeader	boolean	false	コンポーネントのヘッダー (タイトルと説明) を非表示にします。
readOnly	boolean	false	すべての変更操作 (登録と削除) を無効にします。認証要素は表示されますが、追加や削除はできません。
showActiveOnly	boolean	false	ユーザーに有効な登録が少なくとも1つある認証要素タイプのみを表示します。登録がない認証要素タイプは非表示になります。
disableEnroll	boolean	false	すべての認証要素タイプで登録ボタンを非表示にします。ユーザーは既存の認証要素を引き続き削除できます。
disableDelete	boolean	false	登録済みのすべての認証要素の行で削除ボタンを非表示にします。ユーザーは新しい認証要素を引き続き登録できます。
factorConfig	Partial <Record<MFAType, { visible?: boolean; enabled?: boolean }>>	{}	認証要素タイプごとの表示状態と有効状態。

factorConfig

factorConfig を使用すると、tenant の設定を編集せずに、特定の認証要素タイプを表示またはグレーアウトできます。 各キーは認証要素タイプを表す string です。どちらのフィールドも省略可能で、デフォルトは true です。

サポートされる認証要素タイプのキー: phone、totp、email、push-notification、webauthn-platform、webauthn-roaming、recovery-code。

• visible は、リスト内の認証要素の行をレンダリングします (非表示にするには false) 。
• enabled は、認証要素の行を操作可能な状態でレンダリングします (false の場合、グレーアウトされ操作できなくなります) 。

<UserMFAManagement
  factorConfig={{
    phone: { visible: true, enabled: true },
    totp: { visible: true, enabled: true },
    email: { visible: true, enabled: false }, // 表示されるがグレーアウト
    "webauthn-platform": { visible: false },  // 完全に非表示
  }}
/>

​

Action プロップス

Action プロップスを使用すると、コンポーネントの認証要素の登録・削除に関するライフサイクルイベントにフックし、操作をトリガーまたはキャンセルできます。

プロップ	型	説明
enrollAction	ComponentAction<MFAType>	認証要素の登録に関するライフサイクルフック。disabled: trueを設定すると、登録アクションを無効にできます。
deleteAction	ComponentAction<MFAType>	認証要素の削除に関するライフサイクルフック。disabled: trueを設定すると、削除アクションを無効にできます。

enrollAction

フローの開始前に登録をキャンセルするには、onBeforeを使用します。登録が正常に完了した後に関連するUIを更新したり、分析データを送信したりするには、onAfterを使用します。

<UserMFAManagement
  enrollAction={{
    onBefore: (factor) => window.confirm(`Enroll ${factor}?`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Enrolled", { factor });
    },
  }}
/>

deleteAction

組み込みの確認ダイアログが表示される前に削除をキャンセルするには、onBefore を使用します。認証要素が正常に削除された後、onAfter が実行されます。

<UserMFAManagement
  deleteAction={{
    onBefore: (factor) =>
      window.confirm(`Remove your ${factor} authenticator? You may be locked out if this is your only factor.`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Deleted", { factor });
    },
  }}
/>

​

プロップスをカスタマイズ

カスタマイズ用プロップスを使用すると、ソースコードを変更せずに文言、バリデーションルール、スタイリングを調整できます。

プロップス	型	説明
customMessages	Partial<UserMfaManagementMessages>	デフォルトの UI テキストと翻訳を上書きします。
styling	ComponentStyling<UserMFAManagementClasses>	CSS 変数とクラスを上書きします。
schema	{ email?: RegExp; phone?: RegExp }	メールアドレスおよび電話番号の入力フィールド用のカスタムバリデーションパターン。

customMessages

すべてのテキストと翻訳をカスタマイズできます。すべてのフィールドは任意です。

利用可能なメッセージ

ヘッダー header.title, header.description, no_active_mfa, loading_text, component_error.title, component_error.description

Actions actions.remove_button_label, actions.cancel_button_label, actions.confirm_button_label, actions.continue_button_label, actions.submit_button_label, actions.verify_button_label, actions.back_button_label, actions.deleting_button_text, actions.menu_aria_label

認証要素タイプごと ({factor}は、phone、totp、email、push-notification、webauthn-platform、webauthn-roaming、またはrecovery-codeに置き換えます) factors.{factor}.title, factors.{factor}.description, factors.{factor}.button_text

通知 notifications.factor_enroll_success, notifications.factor_remove_success, notifications.fetch_factors_error, notifications.factor_delete_error

登録と削除 enrollment および remove_factor_dialog

<UserMFAManagement
  customMessages={{
    header: {
      title: "Two-Factor Authentication",
      description: "Add extra layers of security to protect your account.",
    },
    no_active_mfa: "You haven't enrolled any authentication methods yet.",
    factors: {
      phone: {
        title: "Text message (SMS)",
        description: "Receive a one-time code via text message.",
        button_text: "Add method",
      },
      totp: {
        title: "Authenticator app",
        description: "Use Google Authenticator, Authy, or any TOTP app.",
      },
    },
    notifications: {
      fetch_factors_error: "Unable to load your security methods.",
    },
  }}
/>

スタイルをカスタマイズ

CSS変数とクラスの上書きで外観をカスタマイズできます。ライト／ダークテーマに対応しています。

利用可能なスタイリングオプション

変数—CSSカスタムプロパティ

• common 両方のテーマに適用
• light ライトモードのみ
• dark ダークモードのみ

クラスの上書き

• UserMFAManagement-item 各認証要素タイプのカードコンテナ
• EnrollFactorModal-dialogContent 認証要素の登録用マルチステップダイアログのコンテンツ領域
• FactorDeleteModal-dialogContent Delete確認ダイアログのコンテンツ領域

<UserMFAManagement
  styling={{
    variables: {
      light: { "--color-primary": "#4f46e5" },
      dark: { "--color-primary": "#818cf8" },
    },
    classes: {
      "UserMFAManagement-item": "rounded-2xl shadow-md border-2",
      "EnrollFactorModal-dialogContent": "max-w-lg",
      "FactorDeleteModal-dialogContent": "max-w-sm",
    },
  }}
/>

schema

enrollment 中のユーザー入力を検証するための組み込み正規表現パターンを上書きします。どちらの field も任意です。設定されていない field には default のパターンが使用されます。

• email は、Email-OTP enrollment 時に入力されたメールアドレスを検証します (default: 標準的な RFC-5322 形式のパターン) 。
• phone は、SMS enrollment 時に入力された電話番号を検証します (default: 国際 E.164 形式を受け入れます) 。

<UserMFAManagement
  schema={{
    // 自社ドメインのみに制限
    email: /^[a-zA-Z0-9._%+-]+@example\.com$/,
    // 米国の電話番号のみ
    phone: /^\+1[2-9]\d{2}[2-9]\d{6}$/,
  }}
/>

​

TypeScript 型定義

type MFAType =
  | "phone"
  | "totp"
  | "email"
  | "push-notification"
  | "webauthn-platform"
  | "webauthn-roaming"
  | "recovery-code";

interface FactorConfigOptions {
  visible?: boolean;
  enabled?: boolean;
}

interface UserMFAManagementClasses {
  "UserMFAManagement-item"?: string;
  "EnrollFactorModal-dialogContent"?: string;
  "FactorDeleteModal-dialogContent"?: string;
}

interface ComponentAction<Item, Context = void> {
  disabled?: boolean;
  onBefore?: (item: Item, context?: Context) => boolean;
  onAfter?: (item: Item, context?: Context) => void | boolean | Promise<boolean>;
}

interface UserMFAManagementProps {
  hideHeader?: boolean;
  showActiveOnly?: boolean;
  disableEnroll?: boolean;
  disableDelete?: boolean;
  readOnly?: boolean;
  factorConfig?: Partial<Record<MFAType, FactorConfigOptions>>;
  customMessages?: Partial<UserMfaManagementMessages>;
  styling?: ComponentStyling<UserMFAManagementClasses>;
  schema?: { email?: RegExp; phone?: RegExp };
  enrollAction?: ComponentAction<MFAType>;
  deleteAction?: ComponentAction<MFAType>;
}

​

高度なカスタマイズ

上記のコンポーネント設定に加え、カスタムMFA管理インターフェースを構築する必要がある場合は、useUserMFA フックを使用します。

import { useUserMFA } from "@auth0/universal-components-react";

export function CustomMfaManagement() {
  const {
    factorsByType,
    isLoadingFactors,
    error,
    visibleFactorTypes,
    handleEnroll,
    handleDeleteFactor,
  } = useUserMFA({
    factorConfig: {
      phone: { visible: true, enabled: true },
      totp: { visible: true, enabled: true },
    },
  });

  if (isLoadingFactors) return <p>Loading authentication methods…</p>;
  if (error) return <p role="alert">{error}</p>;

  return (
    <ul>
      {visibleFactorTypes.map((factorType) => (
        <li key={factorType}>
          <button onClick={() => handleEnroll(factorType)}>
            Add {factorType}
          </button>
          {factorsByType[factorType]?.map((factor) => (
            <button
              key={factor.id}
              onClick={() => handleDeleteFactor(factor.id, factorType)}
            >
              Remove {factorType}
            </button>
          ))}
        </li>
      ))}
    </ul>
  );
}

このフックは、showActiveOnly、readOnly、disableDelete、factorConfig、customMessages、enrollAction、deleteAction を受け取ります。認証要素のデータ、読み込み状態とアクションの状態、登録と削除の状態のほか、登録、検証、削除のフローを実装するために必要なハンドラーを返します。

組み込みのインターフェースを使用する場合は、UserMFAManagement を使用してください。フックを使用する場合は、サポートする認証要素タイプに対応した登録、検証、復旧コード、削除用の UI を実装してください。

enrollAction と deleteAction の onAfter は、アクションの完了直後ではなく、成功通知が閉じたときに実行されます。

​

詳しく見る

ユーザーのパスキー管理

同じライフサイクルの仕組みでWebAuthnパスキーを管理します。

セルフサービスのアカウントセキュリティインターフェースを構築

すべてのMy Accountコンポーネントの概要、前提条件、フレームワークの設定について説明します。