Onboarding

idp-server オンボーディングガイド

クイックスタート

詳細なセットアップ手順は以下を参照:

• documentation/docs/content_02_quickstart/quickstart-01-getting-started.md

このプロジェクトとは

idp-serverは、身元確認特化のエンタープライズ・アイデンティティプラットフォームです。

何ができるか

ユーザー認証

認可・トークン

身元確認（eKYC）

エンタープライズ機能

設定・カスタマイズ

技術スタック

• Java 21+ / Spring Boot 3.x
• Gradle / PostgreSQL & MySQL
• Hexagonal Architecture + DDD

┌─────────────────────────────────────────────────────────────┐
│                      idp-server                              │
├─────────────────────────────────────────────────────────────┤
│  OAuth 2.0 / OpenID Connect / CIBA / FAPI 準拠              │
│  マルチテナント対応 / eKYC連携 / Enterprise Ready           │
└─────────────────────────────────────────────────────────────┘

学習ロードマップ

Phase 1: 基礎理解（1-2日）

Step 1.1: プロジェクト概要を読む

CLAUDE.md                           # 必読: プロジェクト概要
documentation/docs/content_01_intro/ # イントロダクション

Step 1.2: コンセプトを理解する

documentation/docs/content_03_concepts/
├── 01-foundation/                  # 基盤
│   ├── concept-01-multi-tenant.md  # マルチテナント
│   ├── concept-02-control-plane.md # 管理API
│   └── concept-03-client.md        # クライアント
├── 02-identity-management/         # ID管理
├── 03-authentication-authorization/ # 認証・認可
│   ├── concept-01-authentication-policy.md
│   └── concept-04-authorization.md
└── 04-tokens-claims/               # トークン・クレーム

Step 1.3: OAuth 2.0/OIDC基礎（未経験の場合）

documentation/docs/content_04_protocols/
├── protocol-01-authorization-code-flow.md  # 認可コードフロー
├── protocol-02-ciba-flow.md                # CIBAフロー
├── protocol-03-introspection.md            # トークンイントロスペクション
└── protocol-06-client-authentication.md    # クライアント認証

Phase 2: アーキテクチャ理解（2-3日）

Step 2.1: レイヤー構造を理解する

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                        │
│  idp-server-springboot-adapter (Controller, Filter)         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  idp-server-use-cases (EntryService)                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      Domain Layer                            │
│  idp-server-core (Handler, Service, Repository IF)          │
│  idp-server-core-extension-* (CIBA, FAPI, IDA等)           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Infrastructure Layer                       │
│  idp-server-core-adapter (Repository実装, SQL)              │
│  idp-server-platform (共通基盤)                              │
└─────────────────────────────────────────────────────────────┘

Step 2.2: モジュール一覧

Step 2.3: 開発者ガイドを読む

documentation/docs/content_06_developer-guide/
├── 01-getting-started/             # 入門（サービス概要、アーキテクチャ、設計原則）
├── 02-control-plane/               # 管理API
├── 03-application-plane/           # OAuth/OIDCエンドポイント
├── 04-implementation-guides/       # 実装ガイド
├── 05-configuration/               # 設定
├── 06-patterns/                    # 共通パターン
├── 07-troubleshooting/             # トラブルシューティング
└── 08-reference/                   # リファレンス

Phase 3: 開発環境構築（半日）

詳細ガイド: documentation/docs/content_02_quickstart/quickstart-01-getting-started.md

Step 3.1: 必要なツール

# Java 21+
java -version

# Gradle
./gradlew --version

# Node.js (E2Eテスト用)
node --version
npm --version

# Docker (DB用)
docker --version

Step 3.2: ビルド確認

# フォーマット適用
./gradlew spotlessApply

# ビルド
./gradlew build

# 単体テスト
./gradlew test

Step 3.3: ローカル起動

# Docker Compose でDB起動
docker-compose up -d

# アプリケーション起動
./gradlew :app:bootRun

Step 3.4: E2Eテスト実行

cd e2e
npm install
npm test

Phase 4: コードリーディング（3-5日）

Step 4.1: 認可フローを追う（推奨開始点）

1. エントリーポイント: OAuthV1Api
2. EntryService: OAuthFlowEntryService.authorize()
3. Handler: AuthorizationRequestHandler
4. レスポンス生成: AuthorizationResponse

libs/idp-server-springboot-adapter/
└── .../restapi/oauth/OAuthV1Api.java

libs/idp-server-use-cases/
└── .../application/enduser/OAuthFlowEntryService.java

libs/idp-server-core/
└── .../openid/authorization/handler/AuthorizationRequestHandler.java

Step 4.2: トークン発行フローを追う

1. TokenV1Api → TokenEndpointEntryService
2. TokenRequestHandler → 各GrantService
3. OAuthTokenCreationServices → トークン生成

Step 4.3: 管理APIパターンを理解

ManagementApi (契約IF)
    ↓
ManagementEntryService (ユースケース)
    ↓
ManagementHandler (ドメインロジック)
    ↓
Repository (永続化)

Phase 5: 最初のコントリビューション（1-2日）

Step 5.1: Good First Issue を探す

gh issue list --label "good first issue" --state open

Step 5.2: 開発フロー

# 1. ブランチ作成
git checkout -b feature/issue-番号-説明

# 2. 実装

# 3. フォーマット
./gradlew spotlessApply

# 4. テスト
./gradlew test
cd e2e && npm test -- --grep "関連テスト"

# 5. コミット
git add -A
git commit -m "feat: 説明"

# 6. PR作成
gh pr create

Step 5.3: コーディング規約

よく使うスキル

開発時に以下のスキルを活用してください：

困ったときは

ドキュメント検索

# キーワードでドキュメント検索
grep -r "キーワード" documentation/docs/

コード検索

# クラス名・メソッド名で検索
grep -r "クラス名" libs/

E2Eテストから学ぶ

e2e/src/tests/
├── spec/           # RFC/OIDC仕様テスト（プロトコル動作確認）
├── scenario/       # シナリオテスト（ユースケース確認）
├── usecase/        # ユースケーステスト（機能確認）
└── monkey/         # ファジングテスト（異常系確認）

Issue一覧確認

gh issue list --state open

次のステップ

1. Phase 1-3 を完了したら、実際にローカルで動かしてみる
2. Phase 4 でコードを読みながら、デバッガで処理を追う
3. Phase 5 で小さなIssueから始める
4. わからないことがあれば、関連するスキルを参照する

目標: 2週間で「認可フロー全体を説明できる」レベルに到達

関連ドキュメント

• CLAUDE.md - プロジェクト概要
• documentation/docs/content_06_developer-guide/ - 開発者ガイド
• documentation/docs/content_02_quickstart/ - クイックスタート
• .claude/skills/ - 各機能のスキル