WebAuthnパスキー登録は、認証済みアカウントに対して検出可能なセレモニーオプション、制限されたチャレンジ、および秘密鍵の抽出を約束しないリカバリパスを用いて資格情報をバインドします。
パッケージステータス： AI支援リファレンスパッケージ。静的パッケージ検証は合格していますが、実装シナリオは未実行であり、安定採用前に人間によるドメインレビューが必要です。
決定事項
プライマリ認証後に標準準拠のWebAuthnセレモニーを通じてパスキーを提供し、サーバー側には公開資格情報のみを保存し、チャレンジの有効期限を強制し、利用可能な場合は認証器カウンターをリスク信号として扱い、リカバリは秘密鍵をエクスポートするのではなく信頼を再確立することで処理します。
範囲
- ブラウザクライアントがリライイングパーティIDに対して行う登録および認証セレモニー。
- 資格情報のライフサイクル状態、取り消し、重複処理、および検出可能な資格情報ログイン。
- ユーザー向けの登録プロンプト、同期されたパスキーのラベリング、および正直なリカバリ文言。
- 失敗したセレモニーに対するレート制限および監査信号。
範囲外
- パスワードハッシュ化、セッションCookieの仕組み、OAuthフェデレーション（関連セッションブロックを参照）。
- プロファイルの
attestation選択を超えるエンタープライズ証明ポリシー。 - ハードウェアセキュリティモジュールのプロビジョニングやカスタム認証器ファームウェア。
契約
- 登録チャレンジは、文書化されたリカバリフローが明示的に信頼を高めない限り、すでに認証済みのセッションにのみ発行されます。
- チャレンジはプロファイルTTL後に期限切れとなり、期限切れのチャレンジは資格情報を作成しません。
- 保存される資格情報は資格情報ID、公開鍵、署名カウント、トランスポート、およびバックアップ状態を記録し、秘密鍵はサーバーに保存されません。
- 認証成功時には認証器カウンターがサポートされていれば記録されます。増加しない非ゼロカウンターはクローンの可能性がある信号としてプロファイルのリスクポリシーで処理され、ゼロを報告する認証器は使えるカウンターがないだけで拒否されません。
- 同じ資格情報IDでの重複登録は冪等であり、2つ目のアクティブな行は作成されません。
- パスキーなしのリカバリはプロファイルパス（例：メール＋MFAやバックアップコード）を使用し、その後新しいパスキーを登録することがあります。文言はパスキーの秘密がダウンロードやメール送信可能であると誤解させてはいけません。
- リカバリは理由を記録します。紛失デバイスのパスはプロファイルポリシーの下で他の資格情報を保持する場合があり、疑わしい侵害は影響を受けた資格情報を凍結または取り消し、デフォルトで新規登録前にすべての以前のパスキーを取り消します。
- パスキー追加にステップアップが必要な場合、ユーザー検証が成功しなければ資格情報は破棄されます。
- 取り消された資格情報は、クライアントが秘密鍵をローカルに保持していても即座に認証に失敗します。
実装ガイダンス
- W3C WebAuthn Level 3のセレモニー形状に従い、検出可能なログインが望ましい場合は
residentKey: preferredを推奨します。 rpIdは実際に登録可能なドメインに合わせ、サブドメインの例外は明示的に文書化します。- 同期されたパスキーはプラットフォームプロバイダーに依存し、アプリケーションでエクスポート可能な秘密ではないことをFIDO準拠のガイダンスとして示します。
- カウンター異常の処理はアサーション検証とは分離します。レスポンスはステップアップを要求したり、資格情報を一時停止したり、脅威プロファイルに応じてレビューを開くことがありますが、すべての変わらないカウンターがリプレイを証明するとは主張してはいけません。
passkey-states.yamlの状態をサポートツール用の可観測イベントにマッピングします。
失敗処理と安全策
- 検証失敗時に資格情報IDの存在を漏らさず、UI層では一般的なエラーを使用し、詳細コードはログに記録します。
- 認証器キャンセル時はサーバー側の失敗としてカウントせず、回復可能なクライアントエラーを返します。
- 紛失と侵害を1つのリカバリスイッチにまとめないでください。紛失のみのイベントは独立して保持される資格情報を保持し、疑わしいアカウントまたは認証器の侵害はすべての以前のパスキーとインシデントプロファイルで定義されたセッションを取り消すのがデフォルトです。
- 列挙や嫌がらせを遅らせるため、アカウントおよびIPごとに登録試行をレート制限します。
検証と運用
- セレモニーの成功、期限切れ、カウンター異常、ポリシー対応、リカバリ登録を監視します。
- CIで仮想認証器に対してハッピーパスとTTL期限切れの適合性テストを実行します。
- UX文言を四半期ごとにレビューし、パスキー秘密の回復を過剰に約束しないようにします。
採用前提
example.yamlの名前や数値は採用プロファイルであり、普遍的なデフォルトではありません。- チームは自分たちの脅威モデルに適した証明、ユーザー検証、リカバリポリシーを選択する必要があります。