Spec Fido2

FIDO2/WebAuthn コンテキスト

idp-serverにおけるFIDO2/WebAuthn/パスキー実装のコンテキスト情報。

アーキテクチャ概要

クライアント (sample-web)
    │
    ├── navigator.credentials.create() / get()
    │
    ▼
idp-server (認可フロー内)
    │
    ├── WebAuthn4jRegistrationManager (登録)
    ├── WebAuthn4jAuthenticationManager (認証)
    │
    ▼
WebAuthn4j ライブラリ (内部統合)

重要: 外部FIDO2サーバーではなく、WebAuthn4jライブラリを内部統合。

主要ファイル

実装 (Java)

ドキュメント (How-to)

認可リクエストのpromptパラメータ

Passkey登録・認証の2フェーズ

1. Part A（Passkey登録）: prompt=create でユーザー登録 → パスワード認証 → WebAuthn Registration Challenge → Passkey登録
2. Part B（Passkey認証）: prompt=login で再認証 → WebAuthn認証（ブラウザのPasskeyダイアログ）

CLI環境ではWebAuthnのブラウザインタラクションが必要なため、パスワードフォールバックでのテストに限定される。

E2Eテスト

サンプルアプリ

WebAuthn4j関数マッピング

設定パラメータ

基本設定

{
  "rp_id": "example.com",
  "origin": "https://example.com",
  "rp_name": "My Service",
  "require_resident_key": true,
  "user_verification_required": true
}

アテステーション検証

複数Origin対応

{
  "rp_id": "example.com",
  "allowed_origins": [
    "https://app.example.com",
    "https://www.example.com"
  ]
}

ブラウザ動作の設定確認チェックリスト

FIDO2をブラウザUIで動かす際の必須確認事項:

rp_id と allowed_origins の関係

認証UI URL:    https://auth.local.test
                      ^^^^^^^^^^^^^^
rp_id:                     local.test   ← 登録可能ドメイン（eTLD+1）
allowed_origins:  https://auth.local.test  ← ブラウザページのオリジン（ui_config.base_url と一致）

• rp_id はオリジンの登録可能ドメイン（effective top-level domain + 1）
• allowed_origins はブラウザの collectedClientData.origin と照合される
• 不一致の場合 WebAuthn4j が BadOriginException をスローする

step_definitions（email → fido2）

FIDO2ブラウザ利用時は email でユーザー識別（Step 1）→ FIDO2 で認証（Step 2）の2段構成が必要:

"step_definitions": [
  { "method": "email", "order": 1, "requires_user": false, "allow_registration": true, "user_identity_source": "email" },
  { "method": "fido2", "order": 2, "requires_user": true, "allow_registration": false, "user_identity_source": "sub" }
]

device_registration_conditions

認証デバイス登録にはMFAが必要（脆弱性対策）。email認証成功を条件にする:

"device_registration_conditions": {
  "any_of": [
    [{ "path": "$.email-authentication.success_count", "type": "integer", "operation": "gte", "value": 1 }]
  ]
}

認証ポリシー設定例

{
  "success_conditions": {
    "any_of": [
      [{ "path": "$.password-authentication.success_count", "operation": "gte", "value": 1 }],
      [{ "path": "$.fido2-authentication.success_count", "operation": "gte", "value": 1 }]
    ]
  }
}

パスキー一覧取得

パスキー一覧は ID Token / Userinfo の authentication_devices クレーム から取得。

前提設定

1. 認可サーバー: custom_claims_scope_mapping: true
2. クライアント: scope: "openid claims:authentication_devices"
3. 認可リクエスト: scope=openid+claims:authentication_devices

よくある作業パターン

新機能追加

1. WebAuthn4j*Manager.java に処理追加
2. WebAuthn4jConfiguration.java に設定追加
3. E2Eテスト追加
4. ドキュメント更新

設定変更

1. 04-attestation-verification.md で設定例確認
2. WebAuthn4jConfiguration.java でパース確認
3. E2Eテストで動作確認

WebAuthn4j Executor 一覧（5種）

全て AuthenticationExecutor インターフェースを実装。

WebAuthn4jConfiguration 主要パラメータ

$ARGUMENTS