design(security/db): Keycloak User Storage SPI 設計 ADR(docs/adr/0006-...)

[win2cot]

Phase 1 Setup 2-1: Keycloak User Storage SPI 設計 ADR

概要

「既存 users テーブルを Keycloak User Storage SPI で参照する」設計を ADR として確定する。docs/adr/0006-keycloak-user-storage-spi.md を起票。

詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.3、§3.6。

背景

Phase 1 Sprint 1 Infra(#206 配下、起票予定)で Keycloak Custom Image を実装する際、User Storage SPI が「既存 users テーブル」を参照する必要がある。本 Issue で接続経路・更新方向・同期方針を確定し、Sprint 1 Infra の着手前にデザイン根拠を残す。

開発計画書 v1.2 では「DBA: 既存users テーブル参照用 ReadOnly レプリカ整備」と曖昧だった項目を、infrastructure-plan v5 で Keycloak User Storage SPI 設計 として具体化(2026-05-23 確定)。

議論ポイント(ADR で決める)

1. 対象 DB: 既存 users テーブルはどこにある?
   • (a) 同 RDS の別 DB / schema(同 cluster 内、JDBC で接続)
   • (b) 別 RDS / 別 cluster(別 connection、network 経路要)
   • (c) 既存システムの DB(外部、API 経由 or DB 直接)
2. 接続経路:
   • (i) Keycloak Custom SPI から JDBC 直接接続
   • (ii) 既存 API(REST)経由
   • (iii) 中間プロキシ
3. 更新方向:
   • 初期は read のみ を推奨(write は将来検討)
   • 既存 users との同期方針(JIT? Periodic sync?)
4. API 互換性: Keycloak User Storage SPI バージョン(24+)と既存 user store API の整合
5. Federated Identity: OIDC sub claim と users.oidc_sub 列の突合
6. Performance: SPI 呼び出し頻度、キャッシュ戦略

ADR 内容(docs/adr/0006-keycloak-user-storage-spi.md)

下記セクションを含む:

• Title / Status (Proposed → Accepted)
• Context(なぜ User Storage SPI が必要か、開発計画書 v1.2 「既存DB別所」表記からの経緯)
• Decision(対象 DB / 接続経路 / 更新方向 等の選定結果)
• Consequences(運用・性能・将来拡張への影響)
• Alternatives Considered(他案と却下理由)
• Related: infrastructure-plan v5 §5.3、Sprint 1 Infra で実装する Keycloak Custom Image

受入条件

• docs/adr/0006-keycloak-user-storage-spi.md が存在し、accepted status
• 議論ポイント 1〜6 すべてに決定根拠が記載
• Sprint 1 Infra(Keycloak Custom Image 実装)が参照可能な粒度
• 「既存 users」テーブルの場所が確定(対象 DB が具体化)
• 初期は read のみ、write は将来検討と明文化
• 基本設計書 §4.2.1 / 要件定義書 §5.3 の「既存DB別所」表記との関係を整理(Phase 1 Sprint 0 docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90 で本ファイルへの参照を入れる)

関連

• 親 tracker Issue: [Phase 1 Infra] Setup 0-2 + Sprint 0-5 Infra ストリーム横断 tracker #206
• Milestone: Phase 1 Setup 2(due 2026-06-13)
• 依存: なし(Setup 1 と並行可)
• 隣接: Sprint 1 Infra(Keycloak Custom Image 実装、ADR を前提に進む)、[Phase 1 Sprint 0] scaffold ↔ 設計書 v1.4.x 整合実装(2 週間、2026-06-14 〜 06-27) #121 Sprint 0 App の docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90(docs 補正)
• 詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.3 / §3.6 / §9.3

備考

• task-type: task-type:design
• 優先度: priority/p0(Sprint 1 Infra のクリティカルパス)
• area: area/security + area/db