Use Case External Password Auth

外部パスワード認証委譲

パスワード認証を外部サービス（HTTP API）に委譲するユースケース。 idp-server 内蔵のパスワード検証を使わず、authentication-configurations の execution.function = "http_request" を使って外部 API にユーザー名/パスワードを転送し、レスポンスからユーザー情報をマッピングする。

ユースケース: 既存の認証基盤（社内認証 API 等）を持つ組織が、idp-server を OIDC レイヤーとして導入するケース。idp-server は HTTP API で外部サービスと連携するため、外部サービスが HTTP エンドポイントを提供している必要がある。

テンプレート実行

テンプレート: config/templates/use-cases/external-password-auth/

# 基本実行
bash config/templates/use-cases/external-password-auth/setup.sh

# カスタマイズ例
ORGANIZATION_NAME="my-company" \
EXTERNAL_AUTH_URL="https://auth.internal.example.com/api/authenticate" \
EXTERNAL_PROVIDER_ID="ldap-wrapper" \
SESSION_TIMEOUT_SECONDS=3600 \
ACCESS_TOKEN_DURATION=1800 \
REFRESH_TOKEN_DURATION=604800 \
bash config/templates/use-cases/external-password-auth/setup.sh

# ドライラン（実際には作成しない）
bash config/templates/use-cases/external-password-auth/setup.sh --dry-run

細かい設定 Q&A（逆引き）

「やりたいこと -> 設定」の対応表: qa.md

ユーザーが具体的にやりたいことを言った場合は、qa.md を参照して該当するQ&Aの設定キー+値を提示すること。

設定変更 x 挙動確認（ハンズオン）

「設定を変えて → 挙動が変わることを体験する」実験ガイド:

• config/templates/use-cases/external-password-auth/EXPERIMENTS.md - http_request（単数）の基本実験
• config/templates/use-cases/external-password-auth/EXPERIMENTS-http-requests.md - http_requests（複数形）の複数API チェーン実験

設定の効果を手元で確認したい場合はこれらのガイドを案内すること。

自動検証スクリプト: config/templates/use-cases/external-password-auth/verify.sh

ヒアリング項目

ヒアリング結果 -> 環境変数マッピング

外部認証サービス

セッション設定

トークン有効期限

設定対象と手順

1. 外部パスワード認証設定（認証メソッド設定） -- 核心

API: POST /v1/management/organizations/{org-id}/tenants/{tenant-id}/authentication-configurations

この設定が外部パスワード認証委譲の核心。execution.function = "http_request" で外部サービスにリクエストを転送し、user_mapping_rules でレスポンスをユーザー属性にマッピングする。

{
  "type": "password",
  "metadata": {
    "description": "External password authentication via HTTP request"
  },
  "interactions": {
    "password-authentication": {
      "execution": {
        "function": "http_request",
        "http_request": {
          "url": "https://auth.example.com/api/authenticate",
          "method": "POST",
          "header_mapping_rules": [
            { "static_value": "application/json", "to": "Content-Type" }
          ],
          "body_mapping_rules": [
            { "from": "$.request_body.username", "to": "username" },
            { "from": "$.request_body.password", "to": "password" }
          ]
        }
      },
      "user_resolve": {
        "user_mapping_rules": [
          { "from": "$.execution_http_request.response_body.user_id", "to": "external_user_id" },
          { "from": "$.execution_http_request.response_body.email", "to": "email" },
          { "from": "$.execution_http_request.response_body.name", "to": "name" },
          { "static_value": "external-auth", "to": "provider_id" }
        ]
      },
      "response": {
        "body_mapping_rules": [
          {
            "from": "$.execution_http_request.response_body.user_id",
            "to": "user_id",
            "condition": { "operation": "exists", "path": "$.execution_http_request.response_body.user_id" }
          },
          {
            "from": "$.execution_http_request.response_body.email",
            "to": "email",
            "condition": { "operation": "exists", "path": "$.execution_http_request.response_body.email" }
          },
          {
            "from": "$.execution_http_request.response_body.error",
            "to": "error",
            "condition": { "operation": "exists", "path": "$.execution_http_request.response_body.error" }
          },
          {
            "from": "$.execution_http_request.response_body.error_description",
            "to": "error_description",
            "condition": { "operation": "exists", "path": "$.execution_http_request.response_body.error_description" }
          }
        ]
      }
    }
  }
}

外部 API の契約:

マッピングルール:

1b. 複数API チェーン設定（http_requests）

複数の外部APIを順番に呼び出し、結果を統合するパターン。例: 認証API → ユーザー詳細API。

複数API呼び出し時のエラーハンドリング:

成功フィールドとエラーフィールドが共存しないよう、allOf + missing 複合条件を使う:

{
  "from": "$.execution_http_requests[0].response_body.user_id",
  "to": "user_id",
  "condition": {
    "operation": "allOf",
    "value": [
      { "operation": "exists", "path": "$.execution_http_requests[0].response_body.user_id" },
      { "operation": "missing", "path": "$.execution_http_requests[1].response_body.error" }
    ]
  }
}

• exists のみだと、API 2 が失敗してもAPI 1 の成功フィールドが返ってしまう
• allOf で「自身が存在 AND 後続APIのエラーが missing」を両方満たす場合のみ出力

functions（ヘッダー動的生成）:

"header_mapping_rules": [
  {
    "from": "$.unused",
    "to": "x-request-id",
    "functions": [
      { "name": "random_string", "args": { "length": 8 } },
      { "name": "format", "args": { "template": "trace-{{value}}" } }
    ]
  }
]

使える functions: format（テンプレート変換）、random_string（ランダム文字列）、now（現在時刻）、exists（boolean化）。from: "$.unused" は入力不要な functions 用の特殊パス。

詳細と実験手順は EXPERIMENTS-http-requests.md を参照。

2. 認証ポリシー（パスワードのみ、failure/lock_conditions あり）

API: POST /v1/management/organizations/{org-id}/tenants/{tenant-id}/authentication-policies

login-password-only との主な差分:

• available_methods は ["password"] のみ（initial-registration なし = ユーザー自己登録なし）
• failure_conditions / lock_conditions を設定（5回失敗でアカウントロック）

{
  "flow": "oauth",
  "enabled": true,
  "policies": [
    {
      "description": "external_password_only",
      "priority": 1,
      "conditions": {},
      "available_methods": ["password"],
      "success_conditions": {
        "any_of": [
          [
            {
              "path": "$.password-authentication.success_count",
              "type": "integer",
              "operation": "gte",
              "value": 1
            }
          ]
        ]
      },
      "failure_conditions": {
        "any_of": [
          [
            {
              "path": "$.password-authentication.failure_count",
              "type": "integer",
              "operation": "gte",
              "value": 5
            }
          ]
        ]
      },
      "lock_conditions": {
        "any_of": [
          [
            {
              "path": "$.password-authentication.failure_count",
              "type": "integer",
              "operation": "gte",
              "value": 5
            }
          ]
        ]
      }
    }
  ]
}

3. クレーム設定（claims_supported）

API: PUT /v1/management/organizations/{org-id}/tenants/{tenant-id}/authorization-server

重要: この設定が無いと UserInfo / ID Token が sub のみしか返さない。

テンプレートでは public-tenant-template.json に以下が含まれている:

{
  "claims_supported": [
    "sub", "iss", "auth_time", "acr",
    "name", "given_name", "family_name", "nickname", "preferred_username", "middle_name",
    "profile", "picture", "website",
    "email", "email_verified",
    "gender", "birthdate", "zoneinfo", "locale", "updated_at",
    "address", "phone_number", "phone_number_verified"
  ],
  "claims_parameter_supported": true
}

login-password-only との差分

設定確認チェックリスト

設定例ファイル参照

• テンプレート: config/templates/use-cases/external-password-auth/
• 認証メソッド設定: config/templates/use-cases/external-password-auth/authentication-config-password-template.json
• 認証ポリシー: config/templates/use-cases/external-password-auth/authentication-policy.json
• テナント設定: config/templates/use-cases/external-password-auth/public-tenant-template.json
• モックサーバー: config/templates/use-cases/external-password-auth/mock-server.js

関連ドキュメント

• config/templates/use-cases/external-password-auth/README.md - テンプレートの詳細説明
• documentation/docs/content_05_how-to/phase-1-foundation/07-authentication-policy.md - 認証ポリシー設定
• スキル spec-external-integration - 外部サービス連携の詳細（HTTP Request Executor, MappingRule）
• スキル use-case-login - login-password-only との共通設定（セッション、トークン等）

$ARGUMENTS