AgentSkillsCN

onboarding

为 idp-server 项目新手量身打造的入门指南——从项目全局概览、学习路线图，到开发环境搭建与首次贡献，全程贴心陪伴，助您快速上手。

SKILL.md
--- frontmatter
name: onboarding
description: idp-serverプロジェクト初心者向けのオンボーディングガイド。プロジェクト全体像、学習ロードマップ、開発環境構築、最初のコントリビューションまでをサポート。

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

クイックスタート

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

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

このプロジェクトとは

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

何ができるか

ユーザー認証

機能説明
パスワード認証従来型のID/パスワード認証
多要素認証（MFA）SMS OTP、Email OTP
パスワードレス認証FIDO2/WebAuthn、Passkey
FIDO-UAFモバイルデバイス生体認証
外部IdP連携（SSO）Google、Azure AD、カスタムOIDC

認可・トークン

機能説明
OAuth 2.0Authorization Code、Client Credentials、Refresh Token
OpenID ConnectID Token発行、UserInfo、Discovery
CIBAバックチャネル認証（Poll/Push/Ping）
FAPI金融グレードAPI（Baseline/Advanced）

身元確認（eKYC）

機能説明
本人確認フロー外部eKYCサービス連携
Verified ClaimsOpenID Connect for IDA準拠
確認結果管理身元確認結果の保存・参照

エンタープライズ機能

機能説明
マルチテナント組織・テナント単位の完全分離
管理APIテナント/クライアント/ユーザー管理
セキュリティイベントSlack/Email/Webhook通知、SSF対応
監査ログ全操作の記録・検索
Verifiable Credentialsデジタル証明書発行

設定・カスタマイズ

機能説明
認証ポリシークライアント/スコープ別の認証要件
パスワードポリシー複雑性・有効期限・履歴管理
セッション管理SSO、RP-Initiated Logout、Back-Channel Logout
カスタムクレーム任意の属性をトークンに追加

技術スタック

  • •Java 21+ / Spring Boot 3.x
  • •Gradle / PostgreSQL & MySQL
  • •Hexagonal Architecture + DDD
code
┌─────────────────────────────────────────────────────────────┐
│                      idp-server                              │
├─────────────────────────────────────────────────────────────┤
│  OAuth 2.0 / OpenID Connect / CIBA / FAPI 準拠              │
│  マルチテナント対応 / eKYC連携 / Enterprise Ready           │
└─────────────────────────────────────────────────────────────┘

学習ロードマップ

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

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

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

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

code
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基礎（未経験の場合）

code
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: レイヤー構造を理解する

code
┌─────────────────────────────────────────────────────────────┐
│                    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: モジュール一覧

モジュール役割依存関係
idp-server-coreOIDCコアエンジンplatform
idp-server-platform共通基盤（JSON, HTTP, Mapper等）なし
idp-server-use-casesEntryService（ユースケース実装）core, control-plane
idp-server-control-plane管理API契約定義core
idp-server-core-adapter永続化実装（PostgreSQL/MySQL）core
idp-server-springboot-adapterSpring Boot統合use-cases
idp-server-core-extension-cibaCIBA拡張core
idp-server-core-extension-fapiFAPI拡張core
idp-server-core-extension-ida身元確認拡張core
idp-server-authentication-interactors認証方式実装core
idp-server-federation-oidc外部IdP連携core

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

code
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: 必要なツール

bash
# Java 21+
java -version

# Gradle
./gradlew --version

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

# Docker (DB用)
docker --version

Step 3.2: ビルド確認

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

# ビルド
./gradlew build

# 単体テスト
./gradlew test

Step 3.3: ローカル起動

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

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

Step 3.4: E2Eテスト実行

bash
cd e2e
npm install
npm test

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

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

  1. •エントリーポイント: OAuthV1Api
  2. •EntryService: OAuthFlowEntryService.authorize()
  3. •Handler: AuthorizationRequestHandler
  4. •レスポンス生成: AuthorizationResponse
code
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パターンを理解

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

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

Step 5.1: Good First Issue を探す

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

Step 5.2: 開発フロー

bash
# 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: コーディング規約

ルール説明
Tenant第一引数Repository操作は常にTenantを第一引数に
値オブジェクト優先String/Map濫用禁止
Validator/Verifiervoid + throw パターン
両DB対応PostgreSQL + MySQL両方実装

よく使うスキル

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

スキル用途
/architectureアーキテクチャ・レイヤー構造
/authentication認証機能実装
/authorization-endpoint認可エンドポイント
/token-managementトークン発行・管理
/control-plane管理API開発
/federation外部IdP連携
/cibaCIBA実装
/identity-verification身元確認機能

困ったときは

ドキュメント検索

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

コード検索

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

E2Eテストから学ぶ

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

Issue一覧確認

bash
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/ - 各機能のスキル