メインコンテンツまでスキップ

FIDO2/WebAuthn パスキー管理

このドキュメントの目的​

パスキーの一覧取得・削除APIの設定を行うことが目標です。

学べること​

  • ID Tokenからのパスキー一覧取得
  • パスキー削除API
  • ステップアップ認証の設定
  • セキュリティイベント

所要時間​

⏱️ 約10分

前提条件​

パスキー一覧の取得​

ユーザーの登録済みパスキーは、ID TokenまたはUserinfoのauthentication_devicesクレームとして取得できます。専用のAPIエンドポイントはありません。

認可リクエスト（scope=claims:authentication_devices）
       ↓
認証 → ID Token / Userinfo
       ↓
authentication_devices クレーム

事前設定​

authentication_devicesクレームを取得するには、以下の設定が必要です。

1. 認可サーバー設定​

custom_claims_scope_mappingを有効にします。

IDP_SERVER_URL=http://localhost:8080

curl -X PUT "${IDP_SERVER_URL}/v1/management/organizations/${ORGANIZATION_ID}/tenants/${TENANT_ID}/authorization-servers/${AUTH_SERVER_ID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "custom_claims_scope_mapping": true
  }'

2. クライアント設定​

クライアントのスコープにclaims:authentication_devicesを追加します。

{
  "scope": "openid profile claims:authentication_devices"
}

3. 認可リクエスト​

認可リクエストのスコープにclaims:authentication_devicesを含めます。

GET /authorizations?
  response_type=code&
  client_id=${CLIENT_ID}&
  scope=openid+profile+claims:authentication_devices&
  ...

ID Token / Userinfoのauthentication_devicesクレーム​

{
  "sub": "user-123",
  "email": "user@example.com",
  "authentication_devices": [
    {
      "id": "7d181f86-8ced-4d03-8f94-71cd849c9ab5",
      "app_name": "iPhone - Safari (iOS 17.2)",
      "platform": "Mobile",
      "os": "iOS",
      "model": "Safari 17.2",
      "available_methods": ["fido2"]
    }
  ]
}
フィールド説明
idデバイスID（削除時に使用）
app_nameデバイスラベル（User-Agentから自動生成）
platformプラットフォーム（Mobile/Desktop）
osOS名
modelブラウザ名+バージョン
available_methods利用可能な認証方式（fido2等）

クライアント実装例​

// ID Tokenをデコードしてauthentication_devicesを取得
const idTokenClaims = JSON.parse(atob(idToken.split('.')[1]));
const devices = idTokenClaims.authentication_devices || [];

パスキー削除​

DELETE {tenant-id}/v1/me/authentication-devices/{device-id}
Authorization: Bearer {access_token}

レスポンス（成功）​

HTTP/1.1 204 No Content

レスポンス（ステップアップ認証が必要）​

HTTP/1.1 401 Unauthorized

{
  "status": "step_up_authentication_required",
  "message": "Additional authentication is required for this operation"
}

レスポンス（エラー）​

HTTPステータス説明
204削除成功
401ステップアップ認証が必要
403権限なし
404デバイスが存在しない

ステップアップ認証​

セキュリティ上重要な操作（パスキー削除等）に追加認証を要求できます。

設定​

テナントの認証ポリシーで設定します。

{
  "step_up_authentication": {
    "enabled": true,
    "required_for": [
      "device_deregistration",
      "password_change",
      "email_change"
    ],
    "max_age_seconds": 300
  }
}
パラメータ型説明
enabledbooleanステップアップ認証の有効化
required_forarray必要な操作の種類
max_age_secondsinteger認証の有効期間（秒）

required_forの値​

値説明
device_deregistrationデバイス削除
password_changeパスワード変更
email_changeメールアドレス変更
phone_change電話番号変更
mfa_changeMFA設定変更

認証フロー​

  1. クライアントが削除APIを呼び出し
  2. サーバーが認証時刻を確認
  3. max_age_secondsを超過していれば401を返却
  4. クライアントが再認証を実行
  5. 新しいトークンで削除APIを再呼び出し

セキュリティイベント​

パスキーの登録・削除はセキュリティイベントとして記録されます。

イベントタイプ​

イベント説明
device_registrationデバイス登録
device_deregistrationデバイス削除
authentication_success認証成功
authentication_failure認証失敗

イベントデータ​

{
  "event_type": "device_deregistration",
  "timestamp": "2025-01-25T10:30:00Z",
  "tenant_id": "tenant-123",
  "user_id": "user-123",
  "device_id": "7d181f86-8ced-4d03-8f94-71cd849c9ab5",
  "credential_type": "fido2",
  "credential_id": "DQjXXvTeChkhtUuvn7rWiw",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0..."
}

Webhook連携​

セキュリティイベントをWebhookで外部システムに通知できます。

{
  "security_events": {
    "webhook_url": "https://example.com/webhook/security",
    "events": [
      "device_registration",
      "device_deregistration"
    ]
  }
}

デバイス情報の自動抽出​

パスキー登録時、idp-serverはHTTPリクエストのUser-Agentヘッダーを解析し、デバイス情報を自動設定します。

抽出される情報​

フィールド抽出元例
app_nameデバイス + ブラウザ + OSiPhone - Safari (iOS 17.2)
platformデバイス種別Mobile / Desktop
osOS名iOS, macOS, Windows
modelブラウザ + バージョンSafari 17.2

対応プラットフォーム​

User-Agentplatformos
iPhoneMobileiOS
iPadMobileiOS
Android + MobileMobileAndroid
MacintoshDesktopmacOS
WindowsDesktopWindows
LinuxDesktopLinux

関連ドキュメント​

最終更新: 2025-01-25