gcgj-dify-1.7.0/web/docs/MFA_IMPLEMENTATION.md

MFA実装 引き継ぎ書

概要

DifyにTOTPベースの多要素認証（MFA）機能を実装しました。ユーザーは認証アプリ（Google Authenticator等）を使用して、パスワードに加えて6桁のワンタイムパスワードでログインできます。

実装済み機能

1. MFA設定機能

• 場所: アカウントページ（右上アイコン → アカウント → MFA設定ボタン）
• 機能:
  • QRコード生成・表示
  • 秘密鍵の表示
  • バックアップコードの生成（10個）
  • TOTPトークンによる設定完了確認

2. MFAログイン機能

• パスワード認証後、MFAが有効な場合は追加認証画面を表示
• TOTPトークンまたはバックアップコードで認証可能
• バックアップコードは使い捨て

3. MFA無効化機能

• アカウントパスワードの再確認が必要
• 無効化後は通常のパスワードログインに戻る

技術仕様

Backend (API)

主要ファイル

• /api/controllers/console/auth/mfa.py - MFA APIエンドポイント
• /api/services/mfa_service.py - MFAビジネスロジック
• /api/models/account.py - MFA関連フィールド追加
• /api/libs/totp.py - TOTP実装

APIエンドポイント

GET  /console/api/account/mfa/status - MFAステータス取得
POST /console/api/account/mfa/setup - MFA設定開始（QRコード生成）
POST /console/api/account/mfa/setup/complete - MFA設定完了
POST /console/api/account/mfa/disable - MFA無効化
POST /console/api/mfa/verify - ログイン時のMFA検証

データベース変更

Accountテーブルに追加されたフィールド:

• mfa_enabled (Boolean)
• mfa_secret (String, 暗号化)
• mfa_backup_codes (Text, JSON形式)

Frontend (Web)

主要ファイル

• /web/app/components/header/account-setting/mfa-page.tsx - MFA設定ページ
• /web/app/components/signin/mfa-verify.tsx - MFAログイン画面
• /web/service/use-mfa.ts - MFA APIサービス
• /web/app/account/account-page/index.tsx - アカウントページへのMFA統合

状態管理

• React Query使用（@tanstack/react-query）
• MFAステータスはuseQueryでキャッシュ管理
• 設定変更後はinvalidateQueriesで更新

既知の問題と解決済みバグ

1. APIルーティング問題（解決済み）

• 問題: MFAエンドポイントが404エラー
• 原因: /console/api/mfa/*ではなく/console/api/account/mfa/*に配置すべきだった
• 解決: controllers/console/workspace/account.pyでルート登録

2. パスワード検証エラー（解決済み）

• 問題: MFA無効化時に500エラー
• 原因: 存在しないAccountService.check_account_passwordメソッドを呼び出し
• 解決: libs.password.compare_passwordを使用

3. i18n翻訳エラー（解決済み）

• 問題: 日本語で「operation.cancel」と表示される
• 原因: 翻訳キーのネームスペース不足
• 解決: t('common.operation.cancel')に修正

4. モーダル表示問題（解決済み）

• 問題: 設定ドロップダウンが開かない、クリックできない
• 原因: Dialog（z-index: 40）とModal（z-index: 70）の混在
• 解決: MenuDialogコンポーネントの構造を修正

テスト状況

Backendテスト

• ファイル: /api/tests/unit_tests/controllers/console/auth/test_mfa.py
• 状態: 14個のテストケース実装済み、実行環境に課題あり
• 注意: Dockerコンテナ内でのモック設定が複雑

Frontendテスト

• ファイル: /web/app/components/header/account-setting/mfa-page.test.tsx
• 状態: テストファイル作成済み、実行環境未整備
• 必要な作業:
  1. npm install --legacy-peer-depsでJest依存関係をインストール
  2. npm test -- mfa-page.test.tsxでテスト実行

ローカル開発環境でのテスト実行

Frontend単体テストの実行手順

1. 依存関係のインストール

   cd web
   npm install --legacy-peer-deps
   

2. テスト実行

   # 特定のテストファイルを実行
   npm test -- mfa-page.test.tsx
   
   # watchモードで実行
   npm test -- --watch mfa-page.test.tsx
   

3. カバレッジ確認

   npm test -- --coverage mfa-page.test.tsx
   

手動テストシナリオ

1. MFA有効化フロー

   • アカウントページでMFAボタンをクリック
   • QRコードをGoogle Authenticatorでスキャン
   • 6桁のコードを入力
   • バックアップコードを保存

2. MFAログインフロー

   • ログアウト後、通常ログイン
   • MFA画面で6桁コードを入力
   • またはバックアップコードを使用

3. MFA無効化フロー

   • アカウントページでMFA無効化をクリック
   • アカウントパスワードを入力
   • MFAが無効化されることを確認

今後の改善提案

1. バックアップコード再生成機能

   • 現在はMFA設定時のみ生成
   • 紛失時の再生成機能が必要

2. セッション管理の強化

   • MFA認証後の専用セッショントークン
   • デバイス記憶機能

3. 管理者機能

   • ユーザーのMFA強制リセット
   • 組織全体でのMFA必須設定

4. 監査ログ

   • MFA関連イベントの記録
   • 不正アクセス試行の検知

重要な注意事項

1. ビルド時間: Webコンテナのビルドは30分以上かかる場合があります
2. Docker再起動: 大きな変更後は全コンテナの再起動が必要な場合があります

   docker-compose down && docker-compose up -d
   

3. 502エラー対策: nginx-proxyの再起動が必要な場合があります

   cd ../nginx-proxy && docker-compose up -d
   

連絡先

実装に関する質問がある場合は、このドキュメントと併せて以下を参照してください：

• /CLAUDE.md - プロジェクト固有のルール
• /api/tests/mfa_test_instructions.md - テスト手順詳細