infra(compose): Keycloak Realm 設計 + JSON export 配置(keycloak/realm-export/)

[win2cot]

Phase 1 Setup 1-2: Keycloak Realm 設計 + JSON export

概要

Phase 1 Sprint 0 の認証実装で使う Keycloak Realm を設計し、JSON export を keycloak/realm-export/ に配置する。Setup 1-1 の Docker Compose で Keycloak が起動した状態で、Realm を import すれば認証が動く状態を達成する。

詳細仕様: docs/architecture/infrastructure-plan.md v5 §5.2、docs/specs/基本設計書.md §6 認証認可。

背景

webapi/ の Spring Security OAuth2 Resource Server が JWT を検証するために、Keycloak Realm(tasks realm)、Client(tasks-webapi client)、Roles(APP_ADMIN / TENANT_ADMIN / MEMBER)、Test Users(数名)を準備する必要がある。

Setup 2-1(Keycloak User Storage SPI ADR)で「既存 users 参照」設計が確定するまで、本 Issue では Keycloak ローカル user store のみ使う(Test User を Realm に直接定義)。

実装内容

A. Realm 設計

• Realm 名: tasks
• Display name: Tasks Management
• OIDC 設定: 標準
• Client: tasks-webapi(Public client、bearer-only にせず、開発時は public で OK)
  • Valid redirect URIs: http://localhost:8080/*(local)
  • Web origins: http://localhost:8080
• Realm Roles:
  • APP_ADMIN(SaaS 全体管理者)
  • TENANT_ADMIN(テナント管理者)
  • MEMBER(一般メンバー)
• Test Users(local 検証用):
  • admin@example.com / password admin / role APP_ADMIN
  • tenant1-admin@example.com / role TENANT_ADMIN
  • tenant1-member1@example.com / role MEMBER
  • tenant1-member2@example.com / role MEMBER

B. JSON export 配置

Keycloak admin console で Realm export → JSON ファイルを keycloak/realm-export/tasks-realm.json に配置。

C. Docker Compose で自動 import(任意、便利)

docker-compose.local.yml の Keycloak サービスに volume mount + --import-realm 起動引数を追加:

keycloak:
  ...
  command: start-dev --import-realm
  volumes:
    - ./keycloak/realm-export:/opt/keycloak/data/import

これで docker compose up -d 時に Realm が自動 import される。

受入条件

• keycloak/realm-export/tasks-realm.json が存在
• Docker Compose 起動時に tasks realm が自動 import される(または admin console から手動 import 可能)
• tasks realm に Client tasks-webapi、3 つの Realm Role、4 名の Test User が定義済
• OIDC issuer URL: http://localhost:8080/realms/tasks(.well-known/openid-configuration 取得可能)
• Test User でログイン → JWT 取得可能(POST /realms/tasks/protocol/openid-connect/token で grant_type=password 動作)
• JWT の realm_access.roles に Role が含まれることを確認(jwt.io 等でデコード)

想定影響範囲

• Setup 1-4(application.yml)で issuer-uri を設定
• Sprint 0 の OAuth2 / RBAC 実装で利用
• Setup 2-1 ADR で「既存 users 参照」方針が確定したら、Realm の User Federation 設定が追加される(本 Issue では未対応)

関連

• 親 tracker Issue: [Phase 1 Infra] Setup 0-2 + Sprint 0-5 Infra ストリーム横断 tracker #206
• Milestone: Phase 1 Setup 1(due 2026-06-13)
• 依存: Setup 1-1(Compose 雛形)の完了後
• 隣接: Setup 1-4(application.yml)、Setup 2-1(Keycloak SPI ADR)
• 詳細仕様: docs/specs/基本設計書.md §6、docs/architecture/infrastructure-plan.md v5 §3.6

備考

• task-type: task-type:impl(Realm 設計の議論先行は本文に内包、ADR 別途は Setup 2-1)
• 優先度: priority/p0
• area: area/infra + area/security

[claude-automation-impl]

実装着手

方針サマリ

対象: keycloak/realm-export/tasks-realm.json 作成 + docker-compose.local.yml 更新

実装内容:

1. keycloak/realm-export/tasks-realm.json — Keycloak 24 形式の realm export JSON を新規作成
   • Realm 名: tasks / Display name: Tasks Management
   • Client: tasks-webapi(Public client、directAccessGrants 有効)
   • Realm Roles: APP_ADMIN / TENANT_ADMIN / MEMBER
   • Test Users: admin@example.com(admin)、tenant1-admin@example.com(password)、tenant1-member1@example.com(password)、tenant1-member2@example.com(password)
2. docker-compose.local.yml — Keycloak に --import-realm コマンド + volume mount 追加

注意: Keycloak のホストポートは 18080 のため、外部からのアクセスは http://localhost:18080/realms/tasks。Issue 受入条件記載の http://localhost:8080/realms/tasks はタイポと判断(Spring Boot のポートと競合する)。

これから実装します。