Deep Dive into sgcWebSockets WebAuthn Server

Endpoint Mechanics

By default, the component registers routes under /sgcWebAuthn:

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.