Project

General

Profile

Actions
Copy link

Feature #36

open
RA

[TAK-240] K&Kホスティング連携モードを追加しEPAA単体利用と切り替えられるようにする

Feature #36: [TAK-240] K&Kホスティング連携モードを追加しEPAA単体利用と切り替えられるようにする

Added by Redmine Admin about 3 hours ago. Updated about 3 hours ago.

Status:
New
Priority:
High
Assignee:
-
Start date:
09/30/2026
Due date:
% Done:

0%

Estimated time:
(Total: 0:00 h)

Description

Linear migration metadata

Original description

背景

K&Kのホスティングサービスと連携したサービス展開を想定し、EPAAを単体で利用する従来モードに加えて、K&K側の環境・設定発行に追従する利用モードを追加したい。

現状のEPAA単体利用は維持しつつ、K&K連携時はEPAA側で不要なプロジェクト管理や環境別設定入力を省き、導入・運用の手間を減らす。

要求

  • EPAA単体利用モードを維持する。
  • K&Kホスティングサービス連携モードを追加する。
  • K&K連携モードでは、EPAA側で複数プロジェクトを作成・管理しなくてよい構成にする。
  • K&K連携モードでは、dev / stg / 本番の接続先・環境設定をEPAA側で一つずつ登録させない。
  • dev / stg / 本番の設定はK&K側で発行される前提とし、EPAAはその発行情報を参照または取り込んで動作する。
  • K&K連携モードとEPAA単体モードの違いが、管理画面・生成・リリース・検証手順で混同されないようにする。

非目標

  • EPAA単体利用モードを廃止しない。
  • K&K側のホスティングサービスそのものの実装はこのIssueの直接対象外とする。
  • dev / stg / 本番をEPAA側で個別に手入力・個別管理する前提にはしない。

受入条件

  • 管理者がEPAA単体モードとK&K連携モードのどちらで運用するか判別できる。
  • K&K連携モードでは、複数プロジェクト作成を前提にしない操作導線になっている。
  • K&K連携モードでは、dev / stg / 本番ごとの設定値をEPAA側で個別登録しなくても環境情報を扱える。
  • 既存のEPAA単体利用・ローカル検証・dev.epaa.jp検証の前提が壊れていない。
  • 設定が生成挙動やリリース挙動に影響する場合、YAML直編集だけでなくEPAA GUIから作成・編集・削除できる管理経路が定義されている。

影響範囲候補

  • Core GUI: モード選択、プロジェクト/環境設定画面、表示文言、入力制御
  • Backend/API: K&K連携設定の取得・保存・検証、モード判定、リリース/環境情報参照
  • DB: 連携モードやK&K発行情報を保持する場合のテーブル/リリースSQL
  • OpenAPI: fixed APIを追加・変更する場合は先に契約を定義
  • Generator/Runtime: 環境別生成・リリース手順に影響する場合は境界を明確化
  • Docs: EPAA単体利用とK&K連携利用の運用手順を分けて記載
  • Test: 5002検証、設定レポート、API検証マトリクス、必要に応じてブラウザ証跡

注意事項

  • 実装前に要件定義・設計レビューを行い、単体モード互換性とK&K連携モードの責務境界を確定する。
  • K&K側が発行する設定の形式、取得方法、認証方式、更新タイミングは未確定事項として設計で整理する。
  • 子Issueは設計後に FE / BE / DB / Test / Docs へ分割するか判断する。
  • NotionのEPAA開発管理へ背景・決定事項を残すかは別途確認する。

実装前API契約・責務境界（2026-09-02整理）

確定方針

  • EPAA Coreは利用者PC上のデスクトップ／ローカルWebとして動作する。
  • CoreはOAuth 2.0/OIDCのPublic Clientとし、Authorization Code + PKCE（S256）を使用する。Client Secretは配布・保持しない。
  • Redirect URIは http://127.0.0.1:{ephemeral-port}/oauth/callback のループバック方式とする。Coreは認可開始時だけ待受し、完了またはタイムアウト後に閉じる。
  • state、OIDC nonce、PKCE verifierを毎回生成し、認可レスポンスで厳密検証する。組み込みWebViewは使わずOS既定ブラウザを使う。
  • 初期管理者パスワードはAPIで受け渡さない。bootstrap は単回利用・短寿命の初回設定URLを返す。
  • K&K側がID/PW、MFA、端末承認、契約・支払い状態、接続許可を所有する。
  • Core側がPKCE、一時トークン、SSH秘密鍵、ローカル設定、セットアップ実行を所有する。
  • K&Kへ送るのはSSH公開鍵のみ。CoreはK&KのID/PW、初期管理者パスワード、SSH秘密鍵を受信・送信・ログ保存しない。
  • K&K API未完成中は、同一OpenAPI契約から生成または実装したスタブでCore開発を先行する。

API契約のたたき台

OAuth/OIDC

  • GET /oauth/authorize
    • 必須: response_type=code, client_id, loopback redirect_uri, scope, state, nonce, code_challenge, code_challenge_method=S256
    • K&K側でMFA・端末承認・有効契約を確認する。
  • POST /oauth/token
    • application/x-www-form-urlencoded
    • 必須: grant_type=authorization_code, code, client_id, redirect_uri, code_verifier
    • Public ClientのためClient Secretは禁止。
    • Access Tokenは短命、AudienceをK&K Core APIに限定する。Refresh Tokenを採用する場合はローテーション必須、OS資格情報ストアへ保存する。
  • 推奨scope: openid core.bootstrap core.deploy-key.write core.setup-result.write

GET /api/v1/core/bootstrap

  • 有効契約・端末承認済みのTokenのみ許可。
  • 応答候補: contractId（opaque ID）、configRevision、environments[]（dev/stg/prod）、FQDN、SSH接続先、固定サーバ設定、DB接続設定、adminSetupUrl、adminSetupExpiresAt。
  • adminSetupUrl はHTTPS、単回利用、短寿命とし、使用後・期限切れ後はK&K側で再発行する。
  • テナントID、顧客名、組織名、利用可能機能、平文パスワードは返さない。
  • Cache-Control: no-store。ETag/configRevisionにより同一スナップショットを識別する。
  • URLや接続設定に資格情報を埋め込まない。DB秘密情報が必要なら別途短命Secret取得方式を契約レビューで決定する。

POST /api/v1/core/deploy-keys

  • 必須Header: Idempotency-Key、Bearer Token。
  • 要求候補: publicKey、fingerprint、environments[]、requestedTtlSeconds。
  • 応答候補: deployKeyId、fingerprint、allowedEnvironments[]、validFrom、expiresAt、接続制約。
  • 公開鍵形式・アルゴリズム・最小鍵長をallowlist化する。秘密鍵や任意のauthorized_keys optionは受理しない。
  • 同じIdempotency-Key＋同じpayloadは同じ結果を返し、異なるpayloadは409。

POST /api/v1/core/setup-results

  • 必須Header: Idempotency-Key、Bearer Token。
  • 要求候補: setupAttemptId、configRevision、status（succeeded/failed）、startedAt、finishedAt、steps[]、安全化済みerror。
  • setupAttemptIdを業務冪等キーとし、再送で二重処理しない。
  • 同一Attemptの同一結果は成功扱い、矛盾する終端結果は409。
  • ログ本文、Token、パスワード、秘密鍵、接続文字列は送信しない。

共通エラー契約

  • application/problem+json（RFC 9457）に統一する。
  • 必須候補: type, title, status, code, detail, traceId, retryable。
  • 主なHTTP status:
    • 400: schema/parameter不正
    • 401: Token不正・期限切れ
    • 403: scope不足、契約・支払い・端末承認・接続許可NG
    • 404: 対象契約・設定なし（他契約の存在は秘匿）
    • 409: 冪等キー競合、revision競合、終端状態競合
    • 422: 公開鍵や設定内容の意味的エラー
    • 429: rate limit（Retry-After）
    • 500/502/503/504: K&K側障害・依存先障害
  • Coreは retryable=true または429/502/503/504のみ指数バックオフ＋jitterで再試行する。401/403/409/422は自動再試行しない。

冪等性・再実行

  • bootstrap はGETとして副作用を持たせず、同一configRevisionを再取得可能にする。ワンタイムURL再発行は別操作として扱う。
  • deploy-keys と setup-results はUUIDのIdempotency-Keyを必須とし、K&K側で最低24時間保持する。
  • CoreはIdempotency-Key、setupAttemptId、deployKeyId、configRevisionをローカル永続化し、プロセス再起動後も同じ処理を再開できるようにする。
  • タイムアウトは失敗確定とみなさず、同じキーで再送する。

K&K側と実装前に合意が必要な残項目

  1. Issuer、Discovery/JWKS URL、client_id、scope、Token署名アルゴリズム、Access/Refresh Token TTL。
  2. 可変loopback portのRedirect URI登録方式と認可コード有効期限。
  3. bootstrap の各環境schema、必須/nullable、DB秘密情報の扱い、configRevision更新規則。
  4. 初回設定URLのTTL、再発行API、URLを開く主体と完了確認方法。
  5. SSH公開鍵アルゴリズム、許可先、接続元制限、TTL上限、失効・再発行API。
  6. setup step/error code一覧、結果の受付後処理、結果照会の要否。
  7. Idempotency-Key保持期間、rate limit、timeout/SLA、監査ログ保持期間。
  8. 開発・検証・本番のBase URL、証明書、疎通元、K&K側スタブ／検証環境の提供方法。

Definition of Ready

  • OpenAPI 3.1で上記endpoint、schema、security scheme、Problem Details、exampleを合意済み。
  • K&K/Core双方の責務、秘密情報、ログ禁止項目、Token/SSH鍵ライフサイクルをレビュー済み。
  • 正常系、Token期限切れ、契約NG、revision変更、timeout後再送、冪等競合、部分失敗のcontract test例が確定済み。
  • Coreスタブが合意OpenAPIに追従し、K&K実装なしでも正常系・主要異常系を再現可能。

Linear comments

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-08-25T15:36:39.096Z)

Core対応メモ: K&K連携API前提の実装方針

K&K側の開発は先方担当とし、EPAA Coreは以下のK&K APIが存在する前提で連携モードを実装する。

前提

  • EPAA単体利用モードは維持する。
  • K&K連携モードでは、ユーザーはCore上でK&Kログインを開始する。
  • CoreはK&KアカウントのID/パスワードを直接扱わない。
  • K&K側でID/PW、MFA、契約状態、支払い状態、端末承認を確認する。
  • Coreは短命トークン取得後に初期設定をAPIで取得する。
  • テナントID、顧客名、組織名、利用可能機能はCoreの初期設定には含めない。
  • K&K連携モードはシングルテナント前提。

想定フロー

  1. Coreで「K&Kでログイン」を選択する。
  2. CoreがK&Kのログイン画面をブラウザで開く。
  3. K&K側でID/PW + MFA + 端末承認を行う。
  4. Coreが認可コードを受け取り、トークンを取得する。
  5. CoreがK&K APIから契約・FQDN・固定サーバ設定・初期管理者情報を取得する。
  6. CoreがローカルでSSH鍵ペアを生成する。
  7. Coreが公開鍵だけをK&K APIへ登録する。
  8. K&K側が期限付きでSSH/SCP接続を許可する。
  9. Coreが初期配置を実行する。
  10. Coreがセットアップ結果をK&K APIへ通知する。

K&K API契約案

  • GET /oauth/authorize: ログイン開始。OAuth2/OIDC Authorization Code + PKCE、MFA、端末承認を必須にする。
  • POST /oauth/token: 認可コードを短命アクセストークンへ交換する。
  • GET /api/v1/core/bootstrap: 有効契約の初期設定を取得する。
  • POST /api/v1/core/deploy-keys: Coreが生成したSSH公開鍵を登録する。
  • POST /api/v1/core/setup-results: 初期セットアップの成功・失敗を通知する。

Core側の主な改修候補

  • 起動時または初期設定画面で「単体利用 / K&K連携利用」を選択できるようにする。
  • K&Kログイン開始、PKCE、認可コード受信、トークン取得を実装する。
  • トークンを端末登録と紐付けて安全に保存・失効できるようにする。
  • bootstrap レスポンスからFQDN、サーバ固定設定、DB設定、初期管理者情報を取り込み、既存の初期配置設定へ反映する。
  • 初期管理者パスワードは受信後すぐハッシュ化し、平文を保存・ログ出力しない。
  • SSH秘密鍵はCore側で生成・保管し、K&Kへ送らない。
  • SSH公開鍵登録後、既存のSSH/SCP初期配置処理へ接続する。
  • セットアップ成功・失敗をK&Kへ通知し、再実行時の冪等性を確保する。

注意事項

  • K&K側APIが未実装の間は、Core側にK&K APIクライアントのインターフェースとスタブ実装を用意して進める。
  • API契約は実装前にOpenAPIまたは同等の仕様として固定する。
  • 認証・端末承認・SSH鍵登録はセキュリティ影響が大きいため、FE/BE/API契約レビューとテスト子タスクの分割を検討する。

Subtasks 9 (9 open — 0 closed)

Feature #2: [TAK-274] CoreからK&Kサーバーを初期状態からセットアップできるようにするNew09/30/2026

Actions
Feature #18: [TAK-258] K&K連携のセキュリティ・互換性・E2Eテストを整備するNew09/30/2026

Actions
Feature #19: [TAK-257] セットアップ実行の再開・冪等性と結果通知を実装するNew09/30/2026

Actions
Feature #20: [TAK-256] SSH deploy keyの生成・登録・失効ライフサイクルを実装するNew09/30/2026

Actions
Feature #21: [TAK-255] bootstrap取込・revision管理・初回設定URL処理を実装するNew09/30/2026

Actions
Feature #22: [TAK-254] K&K連携モード設定とGUI導線を実装するNew09/30/2026

Actions
Feature #23: [TAK-253] CoreにOIDC Authorization Code + PKCEを実装するNew09/30/2026

Actions
Feature #24: [TAK-252] K&K APIスタブと契約テスト基盤を実装するNew09/30/2026

Actions
Feature #25: [TAK-251] K&K連携OpenAPI 3.1契約を確定するNew09/30/2026

Actions
Actions
Copy link

Also available in: PDF Atom