Unified Auth Plan - knpy/yuka-app GitHub Wiki

統合認証システム設計プラン

概要

yuka-appにおける統一された認証システムの設計と実装プラン。

システム構成

アーキテクチャ概要

[ユーザー] 
    ↓
[Next.js Frontend]
    ↓
[NextAuth.js] ← Google OAuth 2.0
    ↓
[Session Management]
    ↓
[API Routes] → [Google Calendar API]

実装プラン

Phase 1: 基本認証機能 ✅

  • NextAuth.js設定
  • Google OAuth Provider統合
  • 基本的なログイン/ログアウト
  • セッション管理

Phase 2: カレンダー統合 ✅

  • Google Calendar APIスコープ追加
  • アクセストークン取得
  • Calendar API呼び出し
  • イベントデータ表示

Phase 3: 高度な機能

  • トークンリフレッシュ機能
  • オフラインアクセス対応
  • エラーハンドリング強化
  • ユーザープロファイル管理

技術仕様

認証フロー

  1. 初回ログイン

    • Google OAuth同意画面表示
    • 必要なスコープの許可取得
    • アクセストークンとリフレッシュトークン取得

  2. セッション維持

    • JWTベースのセッション管理
    • アクセストークンの自動更新
    • セキュアなCookie設定

  3. API呼び出し

    • Bearer認証によるAPI呼び出し
    • トークン期限チェック
    • 自動リフレッシュ機能

必要なスコープ

const scopes = [
  'openid',
  'email', 
  'profile',
  'https://www.googleapis.com/auth/calendar.readonly'
];

環境変数設定

# Google OAuth
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

# NextAuth
NEXTAUTH_SECRET=your_secret_key
NEXTAUTH_URL=http://localhost:3000

# セキュリティ設定
JWT_SECRET=your_jwt_secret

セキュリティ考慮事項

1. トークン管理

  • 暗号化: アクセストークンはJWTで暗号化保存
  • 有効期限: 適切なトークン期限設定
  • リフレッシュ: 自動的なトークン更新機能

2. セッションセキュリティ

  • HTTPS強制: 本番環境でのHTTPS通信
  • Secure Cookie: セキュアなCookie設定
  • CSRF対策: CSRFトークンの実装

3. API保護

  • 認証チェック: すべてのAPI呼び出しで認証確認
  • スコープ検証: 必要最小限のスコープのみ使用
  • レート制限: API呼び出し頻度制限

エラーハンドリング

1. 認証エラー

const handleAuthError = (error: AuthError) => {
  switch (error.type) {
    case 'OAuthSignInError':
      // Google OAuth認証エラー
      redirectToLogin();
      break;
    case 'TokenExpiredError':
      // トークン期限切れ
      refreshToken();
      break;
    case 'AccessDeniedError':
      // アクセス拒否
      showErrorMessage('認証が拒否されました');
      break;
  }
};

2. API呼び出しエラー

const handleAPIError = (response: Response) => {
  if (response.status === 401) {
    // 認証エラー - 再ログイン要求
    signOut();
  } else if (response.status === 403) {
    // 権限エラー - スコープ不足
    requestAdditionalScopes();
  } else if (response.status === 429) {
    // レート制限 - 再試行
    retryAfterDelay();
  }
};

テスト戦略

1. ユニットテスト

  • 認証ロジックのテスト
  • トークン管理機能のテスト
  • エラーハンドリングのテスト

2. 統合テスト

  • OAuth認証フローのテスト
  • Google Calendar API連携テスト
  • セッション管理のテスト

3. E2Eテスト

  • ユーザー認証フローのテスト
  • カレンダー表示機能のテスト
  • ログアウト機能のテスト

モニタリング

1. ログ出力

// 認証イベントのログ
logger.info('User login successful', { 
  userId: user.id, 
  timestamp: new Date().toISOString() 
});

// API呼び出しのログ
logger.info('Calendar API called', { 
  endpoint: '/calendar/events',
  responseTime: '250ms' 
});

2. メトリクス

  • ログイン成功率
  • API呼び出し頻度
  • エラー発生率
  • レスポンス時間

3. アラート

  • 認証エラー急増時のアラート
  • API制限に近づいた際の通知
  • セキュリティ異常検知

パフォーマンス最適化

1. トークンキャッシュ

  • メモリキャッシュによる高速アクセス
  • 適切な有効期限設定
  • 自動無効化機能

2. API呼び出し最適化

  • 必要最小限のデータ取得
  • バッチ処理による効率化
  • キャッシュ戦略の実装

3. セッション最適化

  • 軽量なセッションデータ
  • 効率的なセッション検索
  • 適切なクリーンアップ

運用手順

1. デプロイ前チェック

  • 環境変数の設定確認
  • OAuth設定の検証
  • セキュリティ設定の確認
  • テストの実行

2. 運用監視

  • 日次のエラーログ確認
  • 週次のパフォーマンス分析
  • 月次のセキュリティ監査

3. トラブルシューティング

今後の拡張計画

短期目標（1-2ヶ月）

  • リフレッシュトークン自動更新
  • 詳細なエラーハンドリング
  • パフォーマンス監視

中期目標（3-6ヶ月）

  • 複数カレンダー対応
  • オフライン機能
  • データ同期機能

長期目標（6ヶ月以上）

  • 他サービス連携（Outlook等）
  • AIによる予定最適化
  • チーム機能
⚠️ **GitHub.com Fallback** ⚠️