EcAuth 要件定義書

1. プロジェクト概要

1.1 背景

EC-CUBEは技術リテラシーの低いユーザーに多く利用されているが、開発の煩雑なソーシャルログインやパスキーの導入実績が乏しい。Eコマースという個人情報やクレジットカード決済など、セキュリティが最重要視される環境にもかかわらず、多くのサイトはパスワード認証のみという現状がある。

特に管理画面においては、フィッシング攻撃による管理者アカウント乗っ取りのリスクが高く、店舗全体のセキュリティに影響を及ぼす可能性がある。

1.2 目的

EcAuthは以下の2層構造で認証サービスを提供する：

EC-CUBE に接続するためのプラグイン（無料）を提供することにより、パスキーやソーシャルログインの導入を促進する。

1.3 プロジェクトスコープ

• B2Bパスキー認証サービスの開発（WebAuthn/FIDO2）
• OpenID Connectに基づくIDフェデレーションサービスの開発
• EC-CUBE用接続プラグインの開発
• 将来的なAPI公開による他サービスへの展開
• 将来的なマルチプラットフォーム展開（WordPress / WooCommerce、Magento等）

2. 機能要件

2.1 認証機能

2.1.1 OpenID Connect実装

• 対応フロー: Authorization Code Flow
• 対応スコープ: openid, profile, email, phone, address, b2b
• 提供クレーム: RFC 7519 Section 4.1に準拠
• PKCE対応: 必須
• トークン暗号化: RSA 2048bit署名

2.1.2 外部IdP連携

対応予定プロバイダー:

• B2C向け: Google, Facebook, LINE, Yahoo Japan, Apple, Microsoft
• B2B向け: Azure Entra ID, Google Workspace

連携方式:

• プロトコル: OpenID Connect
• トークン有効期限: 外部IdPに準拠
• ユーザーマッピング: EcAuthユーザーテーブルに外部IdPのsubjectを1:N紐付け

2.1.3 パスキー対応

WebAuthn/FIDO2に準拠したパスキー認証を実装する。

2.1.3.1 B2Bパスキー（管理画面用）

• 対象: EC-CUBE管理者（店舗オーナー、スタッフ）
• 価格: フリーミアム（Client ごとに 5 MAU まで無料）
• データモデル:
  • B2BUser: 管理者ユーザー情報
  • B2BPasskeyCredential: パスキー認証情報（公開鍵、SignCount等）
  • WebAuthnChallenge: 認証チャレンジ（5分有効）
• APIエンドポイント: /v1/b2b/passkey/*
• 本人確認: パスキー登録時はEC-CUBEプラグイン側でパスワード再入力を要求
• RP ID: EC-CUBEサイトのドメインを使用（店舗ごとに異なる）
• フロントUI: EC-CUBEプラグイン側で実装（Twigテンプレートでカスタマイズ可能）

2.1.3.2 B2Cパスキー（フロント用）

• 対象: ECサイトのエンドユーザー（顧客）
• 価格: MAU課金
• 実装時期: Phase 2（B2Bパスキー完了後）
• 本人確認: 仮会員登録機能（メールアドレス確認）で担保

2.2 マルチテナント機能

2.2.1 テナント管理

• Organizationモデルによるテナント管理
• Organization は「組織」に対応する（1 組織 = 1 テナント = 1 OIDC OP）。サイトやアプリケーションは配下の Client で表す
• 論理分離によるテナント間データ分離
• 本番サイトとテストサイトは親子関係で表す（is_sandbox / parent_organization_id）。本番 1 件につきテストサイト 1 件
• Organization は物理削除しない（deleted_at による論理削除）。組織コードと占有ホストは解放されない
• 1 アカウントが持てるサイト数の上限は account.max_sites（単位は本番 Organization 配下の Client 数）

2.2.2 クライアント管理

• Organization配下でのClient管理
• Client = サイト / アプリケーション単位。1 サイトあたり管理画面用（B2B）とフロント用（B2C）の 2 Client を基本構成とする
• RedirectURI管理
• Client IDおよびClient Secretの発行
• 許可RP ID（パスキー用ドメイン）の管理

2.3 ユーザー管理

2.3.1 B2Cエンドユーザー管理

• 個人情報非保持設計（ハッシュ化したメールアドレスのみ保持）
• 外部IdPのsubjectとの紐付け管理
• EC-CUBEのdtb_customerテーブルとUUID文字列による連携
• データモデル: EcAuthUser, ExternalIdpMapping

2.3.2 B2Bユーザー管理

• EC-CUBE管理者向けのパスキー認証
• EC-CUBEのdtb_memberテーブルとの連携
• 発行元（issuer_key）単位でのユーザー分離。EC-CUBE インスタンス由来の識別子と企業 IdP 由来の識別子を名前空間で分ける
• 個人情報非保持設計（B2BUserIdentity.external_id はメールアドレス等の個人情報を含み得るため、正規化のうえ SHA-256 ハッシュ化して保持する。ハッシュ化は EcAuth サーバー側で行い、呼び出し元は平文を送信する。EC-CUBE プラグインが送る値は dtb_member.member_id 由来の不変キー member:{member_id}（EcAuthDocs#110 リリース 7〜8、2026-09-19。それ以前は可変の login_id）。旧 B2BUser.external_id 列は同リリース 6（EcAuth#539、2026-09-12）で削除済み）
• データモデル: B2BUser, B2BUserIdentity, B2BPasskeyCredential, WebAuthnChallenge
• 将来的な企業SSO（Azure Entra ID等）への拡張を考慮

2.3.3 EcAuth管理者アカウント

• Accountテーブルによる管理者認証（SSO非対象）

2.4 EC-CUBE連携

2.4.1 プラグイン提供

• EC-CUBE 2系対応プラグイン
• EC-CUBE 4系対応プラグイン
• プラグイン自体は無料提供
• 1プラグインで以下の全機能を提供（EC-CUBEバージョンごとに1プラグイン）:
  • 管理画面パスキー認証（B2B）
  • フロント画面パスキー認証（B2C）
  • フロント画面外部IdPフェデレーション
  • 企業SSO（Azure Entra ID, Google Workspace）
  • 将来構想: 企業間SAML連携
• 機能の有効化/無効化は設定画面で切り替え可能
• 未契約・未有効化の機能はグレーアウト表示+契約案内を表示
• 有料機能の利用制限はEcAuth側で管理

2.4.2 管理画面パスキー連携

• 管理画面ログイン画面へのパスキーボタン追加
• パスキー管理画面（登録・削除）
• 登録完了通知メール（推奨）

2.4.3 セッション管理

• EcAuthトークン有効期限切れ時のEC-CUBE側ログアウト
• 厳密な整合性は考慮しない設計

3. 非機能要件

3.1 性能要件

• ピーク時処理能力: 100クライアント/秒
• レスポンスタイム: 500ms以内

3.2 セキュリティ要件

3.2.1 データ保護

• 個人情報非保持設計（メールアドレス等の個人情報は平文で保持せず、ハッシュ化して保持する。B2C は EcAuthUser.email_hash、B2B は B2BUserIdentity.external_id が該当。後者は EC-CUBE プラグイン経由では member:{member_id} になり個人情報を含まないが、account_owner 経路ではメールアドレスのハッシュを保持する）
• トークン内個人情報の非保存またはハッシュ化保存
• RSA 2048bit署名によるトークン保護

3.2.2 パスキーセキュリティ

• チャレンジの一意性（毎回ランダム生成、5分で期限切れ）
• SignCount検証によるリプレイ攻撃防止
• RP ID（ドメイン）検証によるフィッシング防止
• User Verification: preferred以上を推奨

3.2.3 コンプライアンス

• 日本の個人情報保護法準拠（必須）
• GDPR対応（将来対応）
• OWASP ZAPによるペネトレーションテスト（低優先度）

3.3 可用性要件

• Azure SQL Databaseのバックアップ・リカバリ機能に準拠

3.4 運用性要件

• 初期段階ではDB直接操作による管理
• 将来的に管理画面実装予定

4. システム構成

4.1 技術スタック

• バックエンド: .NET 9.0, ASP.NET Core
• データベース: Microsoft SQL Server 2022, Azure SQL Database
• WebAuthn: Fido2.NetLib
• フロントエンド: React（将来）
• EC-CUBEプラグイン: PHP, JavaScript, PostgreSQL, MySQL
• インフラ: Azure Web Apps, Docker

4.2 プロジェクト構成

• IdentityProvider: メインAPIプロジェクト
• MockOpenIdProvider: E2Eテスト用モックIdP
• IdpUtilities: 共通ユーティリティライブラリ
• ConsoleApp: CLIユーティリティ（RSA鍵生成等）
• E2ETests: Playwrightによるテスト
• 各種ユニットテスト

5. ビジネス要件

5.1 料金体系

5.1.1 B2Bパスキー（管理画面）

5.1.2 B2Cフロント認証（MAU課金）

段階従量（graduated）。各帯の単価は、その帯に属する MAU の分だけに適用する（所得税の累進課税と同じ計算）。無料枠を超えた瞬間に一定額が発生する崖を作らず、規模が大きくなるほど限界単価が下がる。

帯の単価は社内の計算基準（税抜）で、顧客向けには公表しない（税込にすると ¥16.5 のように端数が出るため）。顧客には下の月額（税込）で示す。消費税は請求書ごとに 1 回だけ計算する（5.2「消費税」）。

月額の例（顧客向けに公表する形）:

5.2 課金・利用状況管理

• 決済基盤: Stripe。MVP はクレジットカード決済のみ。請求書払い（Stripe Invoicing 等）は MVP 後に必要になってから対応
• 支払い主体: Account（サービス申込者）。Account ごとに支払い方法を登録し、管理下の Organization / Client の利用分をまとめて請求する
• 請求サイクル: 月末に Client ごとの MAU を確定し、翌月 1 日に Account ごとの請求書（Stripe Invoice）を起票、2 日後に確定してカードへ自動請求する。起票から確定までの 2 日間は draft で、誤請求があれば void で止められる猶予として使う（安定後は即時確定に短縮できる設定値）
• Stripe の課金モデル: 月次 Invoice 方式。Subscription / Meter は使わない。毎月 1 日に EcAuth のジョブが、支払い主体の Account ごとに Invoice を作成し、請求対象 Client ごとに InvoiceItem（金額は IPricingCalculator が計算、説明に Client 名と MAU を記載）を積む。automatically_finalizes_at で確定日時を予約し、collection_method=charge_automatically で登録済みカードへ請求する。Stripe 側の冪等キーと DB の UNIQUE (year_month, account_subject) で二重起票を防ぐ。
  • Subscription + Meter を採らない理由: Stripe は新規の従量課金実装に Meters ではなく Metronome を推奨するようになった。MAU は月内 distinct で加算できず、期末〜Invoice 確定（約 1 時間）の窓に確定値を 1 回送る必要があり、ジョブの遅延が請求漏れに直結する。Client の追加・削除ごとに Subscription Item を同期する運用も要る。月に 1 つの確定値を請求する EcAuth には Invoice 方式の方が単純で、料金計算をコード 1 箇所（IPricingCalculator）に閉じられる
  • 料金計算は IPricingCalculator に閉じる。マイページの当月見込み額と請求額は同じ実装を通す（IUsageReportService と同じ複製禁止ルール）。単価と帯はコード既定値（非秘密のチューニング定数）で、Terraform / CI には配線しない
  • Stripe Customer は Account 1 : 1（account.stripe_customer_id）。支払い方法の初回登録時（Checkout の setup モード）に遅延作成する。支払い方法の有無は Webhook で account.payment_method_registered_at に反映し、判定時に Stripe API は呼ばない
  • Stripe のモード: accounts テナントは live、stg-accounts テナントは test。キーはテナント別（Stripe:SecretKey:{tenant}）
• 消費税: 料金表の単価は税抜（B2B ¥100、B2C ¥20 / ¥15 / ¥10）で定め、表示と請求は消費税 10% を加えた税込額にする。表示は国税庁の総額表示の形（「110 円（税込）」）に揃える
  • EcAuth は税抜の金額だけを計算する。消費税は月次の請求書に Stripe の税率（TaxRate、10%・税抜）を付け、Stripe が計算する
  • 計算は国税庁の適格請求書の端数処理に従う（インボイス Q&A 問 57）。Stripe の請求書設定の端数処理を「請求書レベル」にし、Account（= 月次の請求書 1 枚）の税抜合計から割引を引いた額に 10% を掛けて1 請求書・1 税率につき 1 回だけ四捨五入する。Client（明細）ごとに税額を丸めて合計しない
  • マイページの見込み額は税抜で示す（「別途消費税」と添える）
  • Stripe Tax は使わない（取引額の 0.5% 等の手数料がかかるため）。海外の顧客に売るときに Stripe Tax へ切り替える。EcAuth は税抜の金額を渡すだけなので、切り替えは請求書の作り方の差で済む
  • 適格請求書: スキルニル株式会社は適格請求書発行事業者（登録番号 T2140001114345）。登録番号は Stripe アカウントの tax ID（jp_trn）として請求書 PDF に載せ、税率ごとの対価の額と消費税額は Stripe の請求書に出る（test モードで確認済み）
• 初月無料: Client を作成した月（JST 暦月）は請求対象にしない。翌月から請求する。暦月の MAU は、月末に使い始めた顧客も数日分で 1 か月分の単価を払う偏りがあるため、作成月を無料にして解消する（解約側の「対象月の開始より後に削除された Organization は当月分を請求する」と対称の条件）。マイページには「初月無料」と表示する
• Account 別の課金設定: 個別契約・社内利用・キャンペーン向けに、Account ごとに次を設定できる（account_billing_plan、Account 1 : 1）。設定は配下の全 Organization / Client に効く
  • 課金しない（billing_exempt + 理由）
  • 割引: 率（0〜100%、割引額の 1 円未満は切り捨て）または定額（円・税抜、請求対象の合計が上限）のどちらか一方。併用はできない。請求対象 Client の合計に 1 回だけ掛け、請求書には負の明細 1 行で載せる
  • 独自料金テーブル: B2B / B2C それぞれの帯（上限 MAU と単価）。未設定なら 5.1 の標準料金
  • 有効期間（valid_from / valid_until、未設定は無期限）。判定は対象月の開始時点で行い、月の途中の切り替えを日割りしない
  すべて EcAuth 側で計算し、Stripe には最終金額だけを送る（見込み額・請求額・上限強制が同じ設定を見るため）。設定は運用 CLI（ConsoleApp の billing-plan コマンド）で行い、管理画面は作らない。不正な設定は既定値に落とさずエラーにする（範囲外の割引を「割引なし」、書き間違えた帯を「無料」として扱うと過大 / 過少請求になるため）
• Client 別の課金設定: client.billing_exempt（+ 理由）で Client 単位でも「課金しない」を設定できる。Account 側の設定と重ねて効く
• 請求対象外の判定: 次の順に判定し、最初に当てはまった理由をマイページに表示する。対象外の Client にも料金表どおりの金額は表示し、請求見込み額だけを 0 にする
  1. Account が「課金しない」（account_exempt）
  2. Organization が請求対象外（organization_not_billable）: サンドボックス、EcAuth 自身の管理用 Organization（accounts / stg-accounts）、対象月の開始までに削除済み
  3. Client が「課金しない」（client_exempt）
  4. 初月無料（first_month）
• 上限強制の応答: 無料枠を超えた Client で支払い方法が未登録のとき、新規ユーザーの register/options は 402 Payment Required、error=payment_required を返し、error_description にマイページへの導線を含める。既存ユーザーの再登録・登録トークン経路・サンドボックス Organization は対象外
• 少額請求の扱い: 無料枠をわずかに超えた月は ¥22〜数百円（税込）の請求がカードに立つ。MVP ではそのまま請求し、「¥500 未満は翌月へ繰り越す」等の下限は実際に問題になってから検討する（Invoice 起票時に合計額で判定できる形にしておく）
• 利用状況の可視化: Client ごとの MAU と登録ユーザー数（参考値）をマイページで確認できるようにする。将来的にダッシュボード化

6. リリース計画

6.1 リリースロードマップ

1. Phase 1 (MVP) — 管理画面パスキー EC-CUBE 4系優先 / 2系対応、Client ごとに 5 MAU まで無料
2. Phase 2 — フロントパスキー ECサイトフロントの B2C パスキー認証、MAU 課金
3. Phase 3 — 外部 IdP 連携 (ソーシャルログイン) Google / LINE / Facebook 等、MAU 課金
4. Phase 4 — 企業 SSO Azure Entra ID / Google Workspace、B2B 有料プラン
5. Phase 5 — マルチプラットフォーム展開 WordPress / Magento 等、フェデレーションハブ強化

Phase 1（MVP）: 管理画面パスキー

• EC-CUBE管理画面へのパスキー認証プラグイン
• Client ごとに 5 MAU まで無料、6 MAU 以上は有料（110 円（税込）/アクティブユーザー/月）
• リリース当初は課金システム未構築のため全ユーザー無料の可能性あり
• 対応バージョン: EC-CUBE 4系（優先）、EC-CUBE 2系

Phase 2: フロントパスキー

• ECサイトフロントへのパスキー認証
• MAU課金

Phase 3: 外部IdP連携（ソーシャルログイン）

• Google, LINE, Facebook対応
• MAU課金

Phase 4: 企業SSO

• Azure Entra ID, Google Workspace連携
• B2B有料プラン

Phase 5: マルチプラットフォーム展開

• EC-CUBE以外のECプラットフォーム・CMSへの対応
• EcAuthのフェデレーションハブとしてのポジション強化

対応プラットフォーム候補と実現可能性:

実現可能性の根拠:

• EcAuthのB2BパスキーAPIはRESTベースであり、特定CMS固有の依存がない
• B2Cフェデレーションは標準的なOAuth2/OIDC Authorization Code Flowに準拠しており、OIDCクライアントを実装可能な任意のプラットフォームから利用可能
• WebAuthn JavaScript API（navigator.credentials.*）の呼び出しはプラグイン側で実装するため、フロントエンドのカスタマイズが可能なプラットフォームであれば対応可能
• SaaSプラットフォーム（Shopify等）は各社の制約に依存するため、機能ごとに実現可否が異なる

プラットフォーム別の技術的考慮事項:

• WordPress / WooCommerce: wp_usermeta に ecauth_subject を保存、WordPress REST API またはadmin-ajaxでEcAuth API連携
• Magento: admin_user / customer_entity テーブルにサブジェクト紐付け、Magentoモジュールとして実装
• Shopify: Multipass API（Shopify Plus限定）またはCustomer Account API / Headless（Hydrogen）での連携に限定

展開優先順位:

1. EC-CUBE（コアターゲット、Phase 1〜4で全機能対応）
2. WordPress / WooCommerce（市場シェア、全機能対応可能）
3. Magento（EC特化、全機能対応可能）
4. Shopify（SaaS制約、B2Cの一部のみ）

6.2 今後の検討事項

• ベータテスト・パイロット導入計画
• サポート体制（ドキュメント、問い合わせ対応）
• 属性情報の変換・統合ルール
• 管理画面の実装
• 監視・ログ収集基盤
• 課金システムの構築（B2B / B2C ともに MAU 課金、Stripe 連携）
• MAU 集計機能（Client 単位。登録ユーザー数は参考値）
• マルチプラットフォーム展開に向けたプラグインSDK / 連携ガイドラインの策定
• 各プラットフォーム向けプラグインの開発・メンテナンス体制

7. 制約事項

• 新規サービスのため既存システムとの統合は不要
• セッション管理・シングルログアウトは現段階では実装しない
• Phase 1〜4はEC-CUBE側の要件に準拠した設計
• マルチプラットフォーム展開（Phase 5）はPhase 1〜4の完了後に着手
• SaaSプラットフォーム（Shopify等）は各社のAPI制約により提供可能な機能が限定される

8. 用語定義

• EcAuth: 本プロジェクトで開発する認証サービス
• IdP: Identity Provider（認証プロバイダー）
• MAU: Monthly Active Users（月間アクティブユーザー数）。当月に人間の認証行為を経てトークン発行されたユーザーを Client ごとに数える。リフレッシュトークンによる再発行は含めない
• PKCE: Proof Key for Code Exchange
• WebAuthn: Web Authentication API（パスキー実装の標準）
• FIDO2: Fast IDentity Online 2（パスキー標準規格）
• B2B: Business-to-Business（管理者向け認証）
• B2C: Business-to-Consumer（エンドユーザー向け認証）
• RP ID: Relying Party Identifier（WebAuthnにおけるドメイン識別子）