外部パスワード認証委譲

← 導入ガイドに戻る

---

既存の認証基盤（社内認証API等）をそのまま使い、idp-server を OIDC レイヤーとして被せます。

パスワード検証を外部サービスに委譲するため、ユーザーデータベースを移行する必要がありません。

---

概要図

ユーザーが見る画面

┌───────────────────────────┐     ┌───────────────────────────┐     ┌───────────────────────────┐
│  あなたのアプリ            │     │  ログイン画面             │     │  あなたのアプリ            │
│                           │     │                           │     │                           │
│  ┌─────────────┐          │     │  メールアドレス: [______] │     │  ようこそ、○○さん        │
│  │  [ログイン]  │ ────────────→ │  パスワード:     [______] │     │  （ログイン完了）          │
│  └─────────────┘          │     │                           │     │                           │
│                           │     │  ┌─────────────┐          │     └───────────────────────────┘
└───────────────────────────┘     │  │  [ログイン]  │ ──────────────→        ↑
                                  │  └─────────────┘          │             │
                                  └───────────────────────────┘             │
                                                                   OIDCトークン発行

バックエンドの処理フロー

ログイン画面                 idp-server                    外部認証サービス
    │                            │                        （社内認証API等）
    │  POST /password-           │                              │
    │  authentication            │                              │
    │  {username, password}      │                              │
    │ ──────────────────────────→│                              │
    │                            │  POST /auth/password         │
    │                            │  {username, password}        │
    │                            │ ────────────────────────────→│
    │                            │                              │
    │                            │  200: {user_id, email, name} │
    │                            │  401: {error}                │
    │                            │ ←────────────────────────────│
    │                            │                              │
    │                            │  レスポンスをユーザー属性に    │
    │                            │  マッピング                  │
    │                            │                              │
    │  認証結果                   │                              │
    │ ←──────────────────────────│                              │
    │                            │                              │

---

できること

外部認証サービスへの委譲

既存の認証基盤をそのまま活用できます。idp-server はパスワードを検証せず、外部サービスに転送します。

• HTTP API 委譲: 外部サービスの認証APIにユーザー名/パスワードを転送
• レスポンスマッピング: 外部サービスのレスポンスから idp-server のユーザー属性に自動変換
• プロバイダー識別: 外部サービスごとにプロバイダーIDを付与して識別
• 複数API チェーン: 認証API → ユーザー詳細APIなど、複数の外部APIを順番に呼び出し、結果を統合

OIDCレイヤーの提供

外部認証基盤に標準プロトコルを追加できます。

• Authorization Code Flow: 外部認証を OIDC 準拠のフローでラップ
• IDトークン発行: 認証結果を標準的な JWT として発行
• UserInfo エンドポイント: マッピングされたユーザー情報を OIDC 標準で提供

セキュリティ機能

idp-server 側でのセキュリティ制御を追加できます。

• アカウントロック: 認証失敗回数に基づくロック（外部サービスとは独立）
• セッション管理: ログイン状態の有効期限、SSO
• トークン制御: アクセストークン、リフレッシュトークンの有効期限管理

ログイン（パスワードのみ）との違い

項目	ログイン（パスワードのみ）	外部パスワード認証委譲
パスワード検証	idp-server 内蔵	外部サービスが実行
パスワードポリシー	idp-server で管理	外部サービスが管理
ユーザー登録	idp-server で管理	外部サービスが管理
ユーザーデータベース移行	必要	不要
ブルートフォース防止	パスワードポリシーで設定	認証ポリシーの failure/lock_conditions

---

導入時に決めること

1. 外部認証サービスのAPI仕様

決めること	説明
エンドポイントURL	外部認証サービスの認証API URL
リクエスト形式	送信するフィールド名（username/password がデフォルト）
レスポンス形式	返却されるフィールド名（user_id, email, name 等）
エラー形式	認証失敗時のレスポンス（HTTP 401 等）

idp-serverでの設定:

• 認証メソッド設定（authentication-configurations）で execution.function = "http_request" を使用
• body_mapping_rules でリクエスト、user_mapping_rules でレスポンスをマッピング
• 複数APIを呼ぶ場合は execution.function = "http_requests"（複数形）を使用し、前のレスポンスを次のリクエストで参照可能

外部APIの契約例:

リクエスト: POST {"username": "user@example.com", "password": "..."}
成功 (200): {"user_id": "ext-123", "email": "user@example.com", "name": "Test User"}
失敗 (401): {"error": "invalid_credentials", "error_description": "..."}

2. ユーザー情報のマッピング

決めること	選択肢の例
ユーザーID	外部サービスの user_id → idp-server の external_user_id
メールアドレス	外部サービスの email → idp-server の email
表示名	外部サービスの name → idp-server の name
プロバイダーID	固定値（例: legacy-auth、internal-api）

idp-serverでの設定:

• user_mapping_rules で外部レスポンスのフィールドを idp-server のユーザー属性にマッピング

3. アカウントロック条件

決めること	選択肢の例
ロック条件	5回失敗でロック、3回失敗でロック、外部サービスに任せる

idp-serverでの設定:

• 認証ポリシーの failure_conditions / lock_conditions で制御

4. セッション管理

決めること	選択肢の例
有効期限	1時間、8時間、24時間
セッション切り替え	1デバイスのみ、切り替え可能、複数同時

idp-serverでの設定:

• テナント session_config で有効期限と切り替えポリシーを設定

5. トークン有効期限

決めること	選択肢の例
アクセストークン	15分、30分、1時間
リフレッシュトークン	1日、7日、30日
IDトークン	10分、1時間

idp-serverでの設定:

• 認可サーバーの extension でトークン有効期限を設定

---

まとめ

外部パスワード認証委譲を導入する際の重要なポイント:

必ず決めること

1. 外部認証サービスのAPI仕様: エンドポイント、リクエスト/レスポンス形式
2. マッピングルール: 外部レスポンスと idp-server ユーザー属性の対応
3. セキュリティレベル: アカウントロック条件、セッション有効期限
4. トークン有効期限: AT/IDT/RTの有効期限

idp-serverが提供すること

• OAuth 2.0/OpenID Connect標準準拠のログイン機能
• 外部認証サービスへのHTTP委譲（http_request/http_requests executor）
• 複数APIチェーン（認証 → 詳細取得など、前のレスポンスを次に引き渡し）
• レスポンスマッピングによるユーザー情報の自動変換
• アカウントロック機能（failure_conditions / lock_conditions）
• セッション管理（SSO、有効期限、セッション切り替え）
• マルチテナント対応（組織ごとの設定分離）

自分で用意すること

• 外部認証サービス（HTTP APIを提供する既存の認証基盤）
• ログイン画面（UI）
• 外部認証サービスの可用性確保

通常のログインとの使い分け

こういう場合は	選ぶべきユースケース
ユーザーDBを新規構築する	ログイン（パスワードのみ）
既存の認証基盤を活かしたい	外部パスワード認証委譲（このページ）
外部IdP（Google等）でログインさせたい	ログイン（ソーシャル連携）

---

テンプレートで試す

ローカル環境ですぐに試せるテンプレートが用意されています。

cd config/templates/use-cases/external-password-auth
./setup.sh

セットアップ後の動作確認:

ガイド	内容
VERIFY.md	基本動作確認（外部認証フロー → ログイン → トークン取得）
EXPERIMENTS.md	設定変更の実験（認証ポリシー、ブルートフォース防止等）
EXPERIMENTS-http-requests.md	HTTP Request の高度な設定（複数APIチェーン、マッピング関数等）

詳細: config/templates/use-cases/external-password-auth/

関連ドキュメント

• How-to: 認証ポリシー設定
• Concept: セッション管理
• Concept: トークン管理

---

最終更新: 2026-03-10