OAuth 2.0 Flows Implementation

スキル概要

このスキルは、OAuth 2.0 認可フローの実装とセキュリティベストプラクティスを提供します。

コアドメイン:

• OAuth 2.0 仕様の理解と実装
• 適切なフロー選択基準
• PKCE（Proof Key for Code Exchange）実装
• セキュリティ考慮事項とベストプラクティス

専門家の思想:

• Aaron Parecki: OAuth 2.0 の実用的セキュリティガイドライン策定者
• 核心概念: シンプルで堅牢、実装者が正しく使える認可フロー設計

参照書籍:

• 『OAuth 2.0 Simplified』- 実装者向けの実践的ガイド
• OAuth 2.0 RFC 6749 - 公式仕様

OAuth 2.0 フローの種類と選択基準

1. Authorization Code Flow（認可コードフロー）

概要: 最も安全で推奨される OAuth フロー

適用場面:

• サーバーサイド Web アプリケーション
• クライアントシークレットを安全に保管できる環境
• Next.js App Router 等の SSR/SSG 環境

フロー:

1. クライアント → 認可サーバー: 認可リクエスト
2. 認可サーバー → ユーザー: ログイン画面表示
3. ユーザー → 認可サーバー: 認証・同意
4. 認可サーバー → クライアント: 認可コード返却（redirect）
5. クライアント → 認可サーバー: 認可コード + クライアントシークレット
6. 認可サーバー → クライアント: アクセストークン返却

セキュリティ考慮事項:

• クライアントシークレットはサーバー側のみで保管
• redirect URI の厳格な検証必須
• state パラメータで CSRF 対策
• 認可コードは一度のみ使用可能（再利用検出）

実装時の判断基準:

• アプリケーションはサーバーサイドコンポーネントを持つか？
• クライアントシークレットを安全に保管できるか？
• redirect URI は事前登録されているか？

2. Authorization Code Flow + PKCE

概要: パブリッククライアント（SPA、モバイルアプリ）向けのセキュア化拡張

適用場面:

• シングルページアプリケーション（React、Vue 等）
• モバイルアプリ（iOS、Android）
• クライアントシークレットを安全に保管できない環境

PKCE の仕組み:

1. Code Verifier生成: ランダムな43-128文字の文字列
2. Code Challenge生成: SHA256(Code Verifier) → Base64URL
3. 認可リクエスト: code_challenge + code_challenge_method=S256
4. トークンリクエスト: code_verifier（元の文字列）
5. 認可サーバー検証: SHA256(code_verifier) == code_challenge

セキュリティ考慮事項:

• Code Verifier は暗号学的に安全な乱数生成器で作成
• code_challenge_method は必ず"S256"を使用（"plain"は非推奨）
• Code Verifier はメモリにのみ L 保持、永続化しない
• 認可コードインターセプト攻撃を防止

実装時の判断基準:

• クライアントシークレットを安全に保管できないか？
• SPA またはモバイルアプリか？
• PKCE は OAuth 2.0 プロバイダーでサポートされているか？

3. Refresh Token Flow

概要: 長期間のアクセス維持のためのトークン更新メカニズム

適用場面:

• ユーザーが長時間ログイン状態を維持する必要がある
• アクセストークンの有効期限が短い（15 分-1 時間）
• バックグラウンド処理や定期的な API 呼び出しが必要

フロー:

1. 初回認証: Authorization Code Flow → アクセストークン + リフレッシュトークン
2. アクセストークン期限切れ検出
3. リフレッシュトークン → 認可サーバー: トークン更新リクエスト
4. 認可サーバー → クライアント: 新アクセストークン（+ 新リフレッシュトークン）

セキュリティ考慮事項:

• リフレッシュトークンはセキュアストレージに保管（HttpOnly Cookie 推奨）
• リフレッシュトークンローテーション実装（再利用検出）
• リフレッシュトークンの有効期限設定（例: 30 日-90 日）
• トークンファミリー管理と異常検出

実装時の判断基準:

• アクセストークン有効期限は 1 時間以下か？
• ユーザーは長期間ログイン状態を維持するか？
• リフレッシュトークンローテーションはサポートされているか？

OAuth 2.0 セキュリティベストプラクティス

1. State Parameter（CSRF 対策）

目的: CSRF による認可コード窃取を防止

実装:

// 認可リクエスト時
const state = generateRandomString(32);
sessionStorage.setItem("oauth_state", state);
window.location.href = `${authEndpoint}?state=${state}&...`;

// コールバック時
const returnedState = new URL(window.location.href).searchParams.get("state");
const savedState = sessionStorage.getItem("oauth_state");
if (returnedState !== savedState) {
  throw new Error("State mismatch - potential CSRF attack");
}

判断基準:

• state パラメータは暗号学的に安全な乱数か？
• state は認可リクエストとコールバックで一致するか？
• state は一度使用後に削除されるか？

2. Redirect URI Validation

目的: オープンリダイレクタ脆弱性を防止

実装パターン:

• 完全一致検証（ホワイトリスト方式）
• ワイルドカード使用禁止
• スキーム（https://）も含めた検証
• ローカル開発用 URI と本番用 URI の分離

判断基準:

• redirect URI は事前に OAuth プロバイダーに登録されているか？
• 動的な redirect URI 生成を避けているか？
• 本番環境では HTTPS 必須になっているか？

3. Scope Design（最小権限の原則）

目的: 必要最小限の権限のみ要求

設計原則:

• アプリケーションが本当に必要とするスコープのみ要求
• 段階的権限要求（初回は最小限、必要時に追加）
• スコープの詳細な説明（ユーザーの同意を得やすくする）

例:

// ❌ 過剰な権限要求
scope: "user:email user:profile repo admin:org";

// ✅ 最小権限
scope: "user:email"; // メールアドレスのみ必要な場合

判断基準:

• 各スコープの必要性は明確か？
• 管理者権限は本当に必要か？
• 段階的権限要求は考慮されているか？

4. Token Storage（トークン保管）

保管場所の評価:

保管場所	セキュリティ	XSS 耐性	CSRF 耐性	推奨用途
HttpOnly Cookie	高	✅ 高	⚠️ 要対策	サーバーサイドアプリ
Memory（変数）	中	✅ 高	✅ 高	SPA（タブクローズで消失）
localStorage	低	❌ 低	✅ 高	非推奨（XSS 脆弱）
sessionStorage	低	❌ 低	✅ 高	非推奨（XSS 脆弱）

推奨パターン:

• アクセストークン: メモリまたは HttpOnly Cookie
• リフレッシュトークン: HttpOnly Cookie（Secure、SameSite=Lax/Strict）
• ID トークン: メモリまたは HttpOnly Cookie

判断基準:

• XSS 攻撃シナリオは考慮されているか？
• トークンは localStorage に保存されていないか？
• HttpOnly Cookie 使用時、CSRF 対策は実装されているか？

リソース参照

詳細実装パターン

cat .claude/skills/oauth2-flows/resources/authorization-code-flow.md

PKCE 実装詳細

cat .claude/skills/oauth2-flows/resources/pkce-implementation.md

セキュリティチェックリスト

cat .claude/skills/oauth2-flows/resources/security-checklist.md

トークンストレージ戦略

cat .claude/skills/oauth2-flows/resources/token-storage-strategies.md

スクリプト実行

OAuth 2.0 設定検証

node .claude/skills/oauth2-flows/scripts/validate-oauth-config.mjs <config-file>

テンプレート参照

Authorization Code Flow 実装テンプレート

cat .claude/skills/oauth2-flows/templates/auth-code-flow-template.ts

PKCE 実装テンプレート

cat .claude/skills/oauth2-flows/templates/pkce-implementation-template.ts

実装時のワークフロー

Phase 1: フロー選定

1. アプリケーションタイプを分析（サーバーサイド/SPA/モバイル）
2. クライアントシークレット保管可否を評価
3. 適切なフローを選択（Authorization Code / Authorization Code + PKCE）
4. 選択理由を文書化

Phase 2: プロバイダー設定

1. OAuth 2.0 プロバイダーを選定（Google、GitHub 等）
2. プロバイダーにアプリケーション登録
3. Client ID / Client Secret を取得
4. redirect URI を登録（開発・本番環境別）
5. 必要なスコープを定義

Phase 3: 実装

1. 認可リクエスト実装（state、PKCE 含む）
2. コールバックハンドラー実装
3. トークン交換ロジック実装
4. エラーハンドリング実装

Phase 4: セキュリティ強化

1. state パラメータ検証実装
2. redirect URI 検証強化
3. トークンストレージのセキュア化
4. CSRF/XSS 対策の多層化

Phase 5: テストと検証

1. 正常系フローのテスト
2. エラーケース（認証拒否、タイムアウト等）のテスト
3. セキュリティテスト（CSRF、リダイレクタ等）
4. 本番環境での検証

判断基準

フロー選択の判断

• アプリケーションタイプは正確に把握されているか？
• クライアントシークレットの保管可否は評価されているか？
• PKCE の必要性は判断されているか？
• リフレッシュトークンの使用可否は決定されているか？

セキュリティの判断

• state パラメータは実装されているか？
• redirect URI は厳格に検証されているか？
• トークンストレージは適切か？
• スコープは最小権限の原則に従っているか？

実装品質の判断

• エラーハンドリングは包括的か？
• ログとモニタリングは実装されているか？
• テストカバレッジは十分か（80%以上）？
• ドキュメンテーションは完全か？

ベストプラクティス

セキュアなパラメータ生成

// Code Verifier（PKCE用）
function generateCodeVerifier(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

// State Parameter
function generateState(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

エラーハンドリング

• 認証エラーは詳細情報を漏らさない
• ユーザーフレンドリーなエラーメッセージ
• セキュリティイベントはログに記録
• リトライ戦略の実装（一時的障害用）

環境変数管理

# .env.example
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/api/auth/callback
OAUTH_AUTHORIZE_URL=https://provider.com/oauth/authorize
OAUTH_TOKEN_URL=https://provider.com/oauth/token

関連スキル連携

.claude/skills/session-management/SKILL.md との連携

• OAuth 2.0 で取得したトークンのセッション統合
• トークン有効期限とセッション有効期限の整合
• リフレッシュフローとセッション延長の連携

.claude/skills/nextauth-patterns/SKILL.md との連携

• NextAuth.js での OAuth 2.0 プロバイダー設定
• カスタムプロバイダー実装
• セッションコールバックでのトークン管理

.claude/skills/security-headers/SKILL.md との連携

• CSRF 対策の多層化（state + CSRF トークン）
• Cookie 属性の適切な設定
• セキュリティヘッダーによる追加保護

バージョン履歴

バージョン	日付	変更内容
1.0.0	2025-11-26	初版リリース - OAuth 2.0 フロー実装パターン