Diepe duik in sgcWebSockets WebAuthn-server

Het TsgcWSAPIServer_WebAuthn-component is een Delphi/FPC-servermodule die de relying-party-kant van het WebAuthn-protocol over HTTPS implementeert. Het integreert met TsgcWebSocketHTTPServer of TsgcWebSocketServer, en biedt REST-achtige endpoints voor registratie en authenticatie. 

Werking van de endpoints

Standaard registreert het component routes onder /sgcWebAuthn:

Endpoints kunnen via EndpointOptions opnieuw worden toegewezen om aan te sluiten op bestaande routing-schema's. 

Belangrijkste eigenschappen

1. RelyingParty (RPID / RPName) – Verplichte DNS-naam die het logische domein voor credentials identificeert. Zorg dat deze overeenkomt met het effectieve domein van je toepassing.
2. Origins & TopOrigins – Met puntkomma's gescheiden lijsten met geldige origins. Origins dekt de hoofd-domeinen; TopOrigins wordt gebruikt bij inbedding in iframes.
3. AllowCrossOrigins – Als deze op True staat, mogen cross-origin-iframes authenticatie aanvragen. Dit vereist zorgvuldig samengestelde TopOrigins en server-side validatie.
4. Algorithms – Ondersteunde COSE-algoritme-identifiers (bijv. ES256, RS256, EdDSA). Dit bepaalt welke typen publieke sleutels de server accepteert.
5. TimeoutMS – Time-out die aan de client wordt voorgesteld voor het voltooien van WebAuthn-bewerkingen.
6. UserVerification – Beleid voor gebruikersverificatie (preferred, required, discouraged).
7. Attestation – Bepaalt of attestation none, indirect of direct is. Directe attestation vereist validatie van de attestation-certificaatketen.
8. Metadata Service (MDS) – Indien ingeschakeld raadpleegt het component bestanden van de FIDO Metadata Service om de betrouwbaarheid van het authenticator-model te bevestigen. Velden:
   • MDS_FileName – Lokaal gecachte JSON-metadata (gedownload van FIDO).
   • RootCert_FileName – Hoofdcertificaat voor het verifiëren van handtekeningen op metadata.
9. ChallengeOptions – Maakt een aangepaste lengte en willekeurigheidsbron mogelijk voor gegenereerde challenges.
10. CredentialStorage – Hoewel dit geen directe eigenschap is, verwacht het component dat de toepassing publieke sleutels van credentials, sign-counters en user handles bewaart.

Levenscyclus van events

Registratie

• OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Inspecteer de gebruikersnaam, breek af bij ongeldige invoer of lever gebruikersinformatie aan.
• OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Pas de challenge aan of stel selectiecriteria voor de authenticator in voordat deze naar de client wordt gestuurd.
• OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Voer aangepaste attestation-controles uit of weiger registratie.
• OnWebAuthnRegistrationSuccessful(Sender, Credential): Sla credential-ID, publieke sleutel, sign-counter en user handle op in je database.
• OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Log of retourneer meer beschrijvende fouten.

Authenticatie

• OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Zoek credential-ID's op voor de gebruikersnaam en bepaal de toegestane transports (USB, NFC, BLE, intern).
• OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): Pas UserVerification aan, wijzig de challenge-lengte of voeg extra metadata toe.
• OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Valideer de progressie van de sign-counter en handhaaf controles op accountstatus.
• OnWebAuthnAuthenticationSuccessful(Sender, Credential): Werk de sign-counter bij en maak sessietokens aan.
• OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Implementeer rate-limiting, lock-outbeleid en auditing.

Deze events bieden gedetailleerde controle over elke stap van het protocol, van het genereren van opties tot het verwerken van assertions.