The TsgcWSAPIServer_WebAuthn component is a Delphi/FPC server module that implements the relying‑party side of the WebAuthn protocol over HTTPS. It integrates with TsgcWebSocketHTTPServer or TsgcWebSocketServer, and it exposes REST‑like endpoints for registration and authentication. 

Endpoint Mechanics

By default, the component registers routes under /sgcWebAuthn:

PurposeDefault EndpointDescription
Registration Options/Registration/OptionsClient requests a challenge and relying‑party info before calling navigator.credentials.create
Registration Verify/Registration/VerifyBrowser posts the new credential, attestation object, and client data for server validation
Authentication Options/Authentication/OptionsServer provides a list of allowed credential IDs and a challenge
Authentication Verify/Authentication/VerifyBrowser posts the assertion (authenticatorData + signature) for verification
JavaScript Helper/WebauthnDelivers a helper script that wraps standard WebAuthn browser calls
Test Page/TestA quick HTML page to exercise the API for development


Endpoints can be remapped through EndpointOptions to fit existing routing schemes. 

Core Properties

  1. RelyingParty (RPID / RPName) – Mandatory DNS name identifying the logical domain for credentials. Ensure it matches the effective domain of your application.
  2. Origins & TopOrigins – Semi‑colon separated lists of valid origins. Origins covers primary domains; TopOrigins is used when embedding in iframes.
  3. AllowCrossOrigins – If set True, cross‑origin iframes may request authentication. This requires carefully curated TopOrigins and server‑side validation.
  4. Algorithms – Supported COSE algorithm identifiers (e.g., ES256, RS256, EdDSA). This controls which public key types the server will accept.
  5. TimeoutMS – Timeout suggested to the client for completing WebAuthn operations.
  6. UserVerification – Policy for user verification (preferred, required, discouraged).
  7. Attestation – Specifies whether attestation is none, indirect, or direct. Direct attestation requires validating the attestation certificate chain.
  8. Metadata Service (MDS) – When enabled, the component consults FIDO Metadata Service files to confirm authenticator model trustworthiness. Fields:
    • MDS_FileName – Local cached JSON metadata (downloaded from FIDO).
    • RootCert_FileName – Root certificate for verifying metadata signatures.
  9. ChallengeOptions – Allows custom length and randomness source for generated challenges.
  10. CredentialStorage – While not a direct property, the component expects the application to persist credential public keys, sign counters, and user handles.

Event Lifecycle

Registration

  • OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Inspect username, abort if invalid, or supply user information.
  • OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Modify the challenge or set authenticator selection criteria before sending to client.
  • OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Perform custom attestation checks or veto registration.
  • OnWebAuthnRegistrationSuccessful(Sender, Credential): Store credential ID, public key, sign counter, and user handle in your database.
  • OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Log or return more descriptive errors.

Authentication

  • OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Lookup credential IDs for the username, decide allowed transports (USB, NFC, BLE, internal).
  • OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): Customize UserVerification, adjust challenge length, or embed additional metadata.
  • OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Validate sign counter progression, enforce account status checks.
  • OnWebAuthnAuthenticationSuccessful(Sender, Credential): Update sign counter and produce session tokens.
  • OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Implement rate limiting, lockout policies, and auditing.

These events allow fine‑grained control over every step of the protocol, from generating options to processing assertions.