TsgcWSAPIServer_WebAuthn コンポーネントは、HTTPS 上で WebAuthn プロトコルの依拠当事者 (relying party) 側を実装する Delphi/FPC サーバーモジュールです。TsgcWebSocketHTTPServer または TsgcWebSocketServer と統合し、登録と認証のための REST 風エンドポイントを公開します。
エンドポイントの仕組み
デフォルトでは、コンポーネントは /sgcWebAuthn 配下にルートを登録します。
| 目的 | デフォルトのエンドポイント | 説明 |
|---|---|---|
| 登録オプション | /Registration/Options | クライアントが navigator.credentials.create を呼び出す前に、チャレンジと依拠当事者情報を要求します |
| 登録の検証 | /Registration/Verify | ブラウザーが新しいクレデンシャル、アテステーションオブジェクト、クライアントデータをサーバー検証用に送信します |
| 認証オプション | /Authentication/Options | サーバーが許可されたクレデンシャル ID のリストとチャレンジを提供します |
| 認証の検証 | /Authentication/Verify | ブラウザーがアサーション (authenticatorData + 署名) を検証用に送信します |
| JavaScript ヘルパー | /Webauthn | 標準の WebAuthn ブラウザー呼び出しをラップするヘルパースクリプトを配信します |
| テストページ | /Test | 開発用に API を試すための簡易 HTML ページ |
エンドポイントは EndpointOptions を通じて再マッピングでき、既存のルーティングスキームに合わせられます。
主要なプロパティ
- RelyingParty (RPID / RPName) – クレデンシャルの論理ドメインを識別する必須の DNS 名です。アプリケーションの実効ドメインと一致させてください。
- Origins & TopOrigins – セミコロン区切りの有効なオリジンのリストです。
Originsは主要ドメインを対象とし、TopOriginsは iframe 埋め込み時に使用されます。 - AllowCrossOrigins –
Trueに設定すると、クロスオリジンの iframe が認証を要求できます。慎重に管理されたTopOriginsとサーバー側の検証が必要です。 - Algorithms – サポートする COSE アルゴリズム識別子 (例:
ES256、RS256、EdDSA) です。サーバーが受け付ける公開鍵の種類を制御します。 - TimeoutMS – WebAuthn 操作の完了についてクライアントに推奨するタイムアウトです。
- UserVerification – ユーザー検証のポリシー (
preferred、required、discouraged) です。 - Attestation – アテステーションが none、indirect、direct のいずれであるかを指定します。direct アテステーションではアテステーション証明書チェーンの検証が必要です。
- Metadata Service (MDS) – 有効にすると、コンポーネントは FIDO メタデータサービスファイルを参照して認証器モデルの信頼性を確認します。フィールド:
MDS_FileName– ローカルにキャッシュされた JSON メタデータ (FIDO からダウンロード)。RootCert_FileName– メタデータ署名を検証するためのルート証明書。
- ChallengeOptions – 生成されるチャレンジの長さやランダム性のソースをカスタマイズできます。
- CredentialStorage – 直接のプロパティではありませんが、コンポーネントはアプリケーションがクレデンシャル公開鍵、署名カウンター、ユーザーハンドルを永続化することを想定しています。
イベントのライフサイクル
登録
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): ユーザー名を検査し、無効なら中止するか、ユーザー情報を提供します。OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): クライアントに送信する前にチャレンジを変更したり、認証器選択基準を設定したりします。OnWebAuthnRegistrationVerify(Sender, Credential, var Success): カスタムのアテステーション検査を実施するか、登録を拒否します。OnWebAuthnRegistrationSuccessful(Sender, Credential): クレデンシャル ID、公開鍵、署名カウンター、ユーザーハンドルをデータベースに保存します。OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): より詳細なエラーをログに記録するか返却します。
認証
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): ユーザー名のクレデンシャル ID を検索し、許可するトランスポート (USB、NFC、BLE、internal) を決定します。OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response):UserVerificationをカスタマイズしたり、チャレンジ長を調整したり、追加メタデータを埋め込んだりします。OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): 署名カウンターの進行を検証し、アカウントの状態チェックを実施します。OnWebAuthnAuthenticationSuccessful(Sender, Credential): 署名カウンターを更新してセッショントークンを発行します。OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): レート制限、ロックアウトポリシー、監査を実装します。
これらのイベントにより、オプションの生成からアサーションの処理まで、プロトコルの各ステップを細かく制御できます。