EcAuth リポジトリガイド

このファイルは Claude Code (claude.ai/code) がこのリポジトリで作業する際のガイダンスを提供します。

プロジェクト概要

パスキー認証（B2B）と OpenID Connect フェデレーション（B2C）を提供する Identity Provider システムです。

認証方式

リポジトリ構成

このプロジェクトは複数のリポジトリで構成されています：

コアリポジトリ

ドキュメントリポジトリ

• EcAuthDocs/: 設計ドキュメント（EcAuthDocs リポジトリ）
  • @requirements.md: 要件定義書
  • @b2b-passkey-architecture.md: B2Bパスキー アーキテクチャ設計書
  • @user-management-architecture.md: ユーザー管理設計（B2C/B2B統合）
  • @technical-qa.md: 技術 Q&A
  • secrets-management.md: シークレット管理設計

注: ルートの CLAUDE.md は EcAuth/docs/claude-repository-guide.md へのシンボリックリンクです。

依存関係

EcAuth (IdentityProvider)
  ├─ EcAuth.IdpUtilities (NuGet: EcAuth.IdpUtilities)
  └─ EcAuth.MockIdP (外部環境、E2E テスト用)
       └─ EcAuth.IdpUtilities (NuGet: EcAuth.IdpUtilities)

ecauth-infrastructure
  └─ EcAuth.MockIdP の Azure デプロイ管理

環境構成

EcAuth は以下の 3 つの環境で構成されています：

環境変数テンプレート

1Password を使用した環境変数設定

1Password CLI を使用して、テンプレートから自動的に .env を生成できます。

# 前提条件: 1Password CLI がインストールされていること
# https://developer.1password.com/docs/cli/get-started/

# 1Password にサインイン
eval $(op signin)

# ローカル Docker 開発（EcAuth DB: Docker, MockIdP: Azure dev）
op inject -i .env.dev.tpl -o .env

# ステージング環境（EcAuth DB: Azure, MockIdP: Azure staging）
op inject -i .env.staging.tpl -o .env

# 完全ローカル環境（MockIdP も Docker 内で動かす場合）
cp .env.docker .env

1Password アイテム構成

環境変数の概要

.env ファイルには以下のカテゴリの設定が含まれます：

• データベース接続情報: DB_HOST, DB_PASSWORD, ConnectionStrings__EcAuthDbContext 等
• Organization/Client 設定: DEFAULT_ORGANIZATION_CODE, DEFAULT_CLIENT_ID 等
• MockIdP 連携設定: MOCK_IDP_BASE_URL, FEDERATE_OAUTH2_* 等
• 外部 IdP 認証情報: GOOGLE_OAUTH2_CLIENT_ID 等（オプション）

開発コマンド

環境セットアップ

cd EcAuth

# HTTPS 対応で Docker 環境を起動（証明書は自動生成）
# 対象: Linux / Docker for Windows (WSL2)
docker compose -p ec-auth up -d --build

ビルド・テスト

cd EcAuth

# ソリューション全体のビルド
dotnet build EcAuth.sln

# ユニットテスト実行
dotnet test IdentityProvider.Test/IdentityProvider.Test.csproj

# 特定のテストクラス実行
dotnet test --filter ClassName=TokenServiceTests

cd EcAuth/IdentityProvider

# マイグレーション追加
dotnet ef migrations add <MigrationName>

# マイグレーション適用（.env から環境変数を読み込み）
export $(cat ../.env | grep -v '^#' | xargs) && \
export ConnectionStrings__EcAuthDbContext="Server=${MIGRATION_DB_HOST},1433;Database=${DB_NAME};User Id=${DB_USER};Password=${DB_PASSWORD};TrustServerCertificate=true;" && \
dotnet ef database update

ローカル開発環境

# GitHub CLI を使用して自動設定（一度だけ実行）
echo "protocol=https
host=github.com" | gh auth git-credential get | awk -F= '/username/ {u=$2} /password/ {p=$2} END {system("dotnet nuget add source https://nuget.pkg.github.com/EcAuth/index.json --name github --username " u " --password " p " --store-password-in-clear-text")}'

GitHub Actions 環境

- name: Add GitHub Packages source with credentials
  run: |
    dotnet nuget remove source github || true
    dotnet nuget add source https://nuget.pkg.github.com/EcAuth/index.json \
      --name github \
      --username ${{ github.actor }} \
      --password ${{ secrets.ORG_PAT || secrets.PACKAGES_READ_TOKEN }} \
      --store-password-in-clear-text

設定されているシークレット:

• ORG_PAT: Organization レベルのトークン（推奨）
• PACKAGES_READ_TOKEN: 後方互換性のために残している従来のトークン

E2E テスト

E2E テストは外部環境（Azure）の MockIdP を使用します。

環境変数

フェデレーション認証テスト

cd EcAuth/E2ETests

# 依存関係インストール
yarn install

# ローカル Docker 環境を起動
docker compose -p ec-auth up -d --build

# フェデレーション認証テスト
E2E_AUTHORIZATION_ENDPOINT=https://localhost:8081/v1/authorization \
E2E_TOKEN_ENDPOINT=https://localhost:8081/v1/token \
E2E_REDIRECT_URI=https://localhost:8081/v1/auth/callback \
npx playwright test tests/specs/federate_authorization_code_flow.spec.ts --reporter=list

プロジェクト構造

このリポジトリのコンポーネント

• IdentityProvider: メイン IdP API（ASP.NET Core）
• ConsoleApp: CLI ツール（RSA 鍵ペア生成等）
• E2ETests: Playwright E2E テスト
• IdentityProvider.Test: xUnit ユニットテスト

アーキテクチャ重要ポイント

詳細は CLAUDE.md を参照してください。

マルチテナント実装

TenantMiddleware (リクエストから Organization を特定)
  ↓
OrganizationFilter (EF Core クエリフィルター適用)
  ↓
各エンティティに Organization 単位のデータフィルタリング適用

B2Bパスキー認証フロー

/v1/b2b/passkey/authenticate/options → チャレンジ生成
  → EC-CUBEプラグイン側でWebAuthn API呼び出し（navigator.credentials.get()）
  → /v1/b2b/passkey/authenticate/verify → 署名検証 → 認可コード発行
  → EC-CUBE管理画面にログイン

OAuth2/OpenID Connect フロー（B2C）

/v1/authorization → 外部 IdP にリダイレクト
  → /v1/authorization/callback (JIT ユーザープロビジョニング、認可コード発行)
  → クライアント（EC-CUBE）にリダイレクト

/v1/token → 認可コード検証 → ID Token + Access Token 発行

/v1/userinfo → Access Token 検証 → ユーザー情報返却（subject のみ）

技術スタック

• .NET: 10.0（LTS）
• Entity Framework Core: 10.0
• データベース: Microsoft SQL Server 2022
• WebAuthn: Fido2.NetLib
• テスト: xUnit (ユニット), Playwright (E2E)
• Docker: マルチステージビルド対応

開発時の注意事項

コーディング規約

• 行末の空白は削除
• 改行コードは LF
• 日本語コミュニケーション前提
• セキュリティ脆弱性（SQL Injection、XSS、Command Injection 等）に注意

CI/CD

GitHub Actions ワークフロー：

• .github/workflows/dotnet_tests.yml: xUnit テスト
• .github/workflows/playwright.yml: E2E テスト
• .github/workflows/migrate-staging.yml: ステージング DB マイグレーション（1Password 連携）

EF Core 9 移行関連

.NET 8 から .NET 9 への移行時、マイグレーション実行時のトランザクション管理変更によるタイムアウトエラーに対処済み。詳細は technical-qa.md の Q3 を参照。

.NET メジャーバージョン移行の順序（標準手順）

.NET のメジャーバージョンを上げる際は、リポジトリ間の依存関係とインフラ側ランタイムの差し替えを正しい順序で進めないと、NuGet restore 失敗・Azure Web App の起動失敗・環境間の不整合を起こす。2026-04 に実施した .NET 9 → .NET 10（LTS）移行 の流れを標準手順として記録する。

依存関係とデプロイの順序

1. EcAuth.IdpUtilities TargetFramework と依存パッケージを net10.0 系に更新。NuGet コンシューマに対する破壊的変更となるため SemVer に従い MAJOR をバンプ (例: 1.0.0 → 2.0.0)。PR マージ後、タグ push (例: v2.0.0) で publish-nuget.yml が GitHub Packages に publish。
2. EcAuth.MockIdP TargetFramework と Dockerfile のベースイメージを net10.0 系に。EcAuth.IdpUtilities の PackageReference を新バージョン (2.0.0 等) に追従。PR マージで Docker Build & Push → Azure Container Apps の dev (:latest) が自動更新。staging / production MockIdP は別管理。
3. EcAuth (IdentityProvider / ConsoleApp / Test) TargetFramework / Dockerfile / GitHub Actions の dotnet-version を更新。IdpUtilities の PackageReference 追従。mise.toml を dotnet = "10" に。.config/dotnet-tools.json の dotnet-ef バージョンも同時更新 (マニフェスト古いと tool restore 後に旧バージョンが優先される)。
4. ecauth-infrastructure (staging 先行) environments/staging/main.tf の module.web_app_identityprovider に dotnet_version = "10.0" の 明示 override を追加。modules/web-app/variables.tf の default は旧値のまま維持。PR マージで apply-staging のみ差分 apply (他環境は no-op)。
5. staging デプロイ EcAuth staging.yml が main push で自動起動。staging 環境で E2E verify を通過させる。
6. ecauth-infrastructure (production) environments/production/main.tf に dotnet_version = "10.0" override 追加。modules/web-app/variables.tf の default も新バージョンに更新。PR マージで apply-production のみ差分 apply。
7. production デプロイ production.yml を workflow_dispatch で手動実行。action=migrate-and-deploy で migrate → build → deploy → verify。

重要な制約・落とし穴

• ecauth-infrastructure の PR 分割は必須: .github/workflows/terraform.yml が push to main で全環境を並列 apply する設計のため、staging と production の段階デプロイを実現するには PR を環境ごとに分割し、各環境で override を明示指定する必要がある。詳細は ecauth-infrastructure CLAUDE.md の「環境別デプロイのルール」。
• Linux Azure App Service の LinuxFxVersion はメジャー版排他: DOTNETCORE|10.0 への切替は旧メジャーのランタイムを実質的に除去するため、既存 net9.0 app は rollForward: Minor（デフォルト）では起動できない可能性がある。今回は結果として稼働したが、本質的には Azure 側切替と同時か直後に net10.0 app をデプロイ すべき。
• NuGet パッケージは SemVer 厳守: TargetFramework 変更は PackageReference レベルで破壊的変更（NU1202 相当の互換性エラーを発生させる）。必ず MAJOR バンプし、すべてのコンシューマ（MockIdP / EcAuth）で参照バージョンを追従させる。
• ツールマニフェスト (.config/dotnet-tools.json) の更新漏れに注意: dotnet tool install --global --version X と dotnet tool restore を併用すると、マニフェスト側の旧バージョンがローカルツールとして優先される（rollForward: false の場合は特に）。Dockerfile 側は dotnet tool restore のみに集約し、バージョンはマニフェスト側で一元管理する。
• E2E テストの冪等化: staging で B2B パスキー登録テスト等が残存データと衝突して失敗する場合、run ごとに external_id / b2b_subject を unique に生成する（b2b_subject は UUID 形式必須）。

移行時の検証観点（チェックリスト）

• 全 3 .NET リポジトリ（IdpUtilities / MockIdP / EcAuth）で dotnet build / dotnet test が pass
• IdpUtilities が NuGet 新バージョンで publish 済み、MockIdP / EcAuth の CI が restore 成功
• dotnet ef migrations has-pending-model-changes が差分ゼロ
• staging の apply-* で想定外の drift が Plan に現れない
• staging デプロイ後に /healthz が {"status":"healthy","database":"connected"} を返す
• staging で B2B パスキー E2E と OIDC フェデレーション E2E が通過
• production デプロイ後に /healthz が同様に 200 を返す
• Azure portal で staging / production の Web App Stack settings が新バージョンになっている

トラブルシューティング

Docker 起動失敗

# コンテナログ確認
docker compose -p ec-auth logs identityprovider

# データベース接続確認
docker compose -p ec-auth exec db /opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P '<YourStrong@Passw0rd>' -C -Q "SELECT name FROM sys.databases"

E2E テスト失敗

• ignoreHTTPSErrors: true 設定済み（自己署名証明書対応）
• 失敗時は E2ETests/test-results/ にスクリーンショット・動画が保存される

マイグレーション失敗

• .env ファイルの環境変数が正しく読み込まれているか確認
• EF Core 9 のトランザクション管理の制限に注意（直接 SQL 実行推奨）