Szczegółowe spojrzenie na serwer WebAuthn sgcWebSockets

Komponent TsgcWSAPIServer_WebAuthn to moduł serwerowy dla Delphi/FPC, który implementuje stronę relying-party protokołu WebAuthn po HTTPS. Integruje się z TsgcWebSocketHTTPServer lub TsgcWebSocketServer i udostępnia punkty końcowe w stylu REST do rejestracji i uwierzytelniania. 

Mechanika punktów końcowych

Domyślnie komponent rejestruje trasy pod /sgcWebAuthn:

Punkty końcowe można przemapować przez EndpointOptions, aby dopasować je do istniejących schematów routingu. 

Główne właściwości

1. RelyingParty (RPID / RPName) – Obowiązkowa nazwa DNS identyfikująca logiczną domenę dla poświadczeń. Upewnij się, że odpowiada efektywnej domenie twojej aplikacji.
2. Origins i TopOrigins – Listy prawidłowych origins oddzielone średnikiem. Origins obejmuje domeny główne; TopOrigins jest używane przy osadzaniu w iframes.
3. AllowCrossOrigins – Jeśli ustawione na True, iframes z innym origin mogą żądać uwierzytelnienia. Wymaga to starannie dobranych TopOrigins i walidacji po stronie serwera.
4. Algorithms – Obsługiwane identyfikatory algorytmów COSE (np. ES256, RS256, EdDSA). Określa, jakie typy kluczy publicznych zaakceptuje serwer.
5. TimeoutMS – Timeout sugerowany klientowi do ukończenia operacji WebAuthn.
6. UserVerification – Polityka weryfikacji użytkownika (preferred, required, discouraged).
7. Attestation – Określa, czy attestation jest none, indirect czy direct. Direct attestation wymaga walidacji łańcucha certyfikatów attestation.
8. Metadata Service (MDS) – Gdy włączone, komponent korzysta z plików FIDO Metadata Service, aby potwierdzić wiarygodność modelu authenticatora. Pola:
   • MDS_FileName – Lokalnie zbuforowane metadane JSON (pobierane z FIDO).
   • RootCert_FileName – Certyfikat główny do weryfikacji podpisów metadanych.
9. ChallengeOptions – Umożliwia ustawienie niestandardowej długości i źródła losowości dla generowanych challenges.
10. CredentialStorage – Choć nie jest bezpośrednią właściwością, komponent oczekuje, że aplikacja będzie trwale przechowywać klucze publiczne poświadczeń, liczniki podpisów oraz uchwyty użytkowników.

Cykl życia zdarzeń

Rejestracja

• OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Sprawdź nazwę użytkownika, przerwij operację, jeśli jest nieprawidłowa, lub dostarcz informacje o użytkowniku.
• OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Zmodyfikuj challenge lub ustaw kryteria wyboru authenticatora przed wysłaniem do klienta.
• OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Wykonaj niestandardowe sprawdzenia attestation lub odrzuć rejestrację.
• OnWebAuthnRegistrationSuccessful(Sender, Credential): Zapisz ID poświadczenia, klucz publiczny, licznik podpisów oraz uchwyt użytkownika w bazie danych.
• OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Loguj lub zwracaj bardziej opisowe błędy.

Uwierzytelnianie

• OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Wyszukaj ID poświadczeń dla nazwy użytkownika, zdecyduj o dozwolonych transportach (USB, NFC, BLE, wewnętrzny).
• OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): Dostosuj UserVerification, zmień długość challenge lub osadź dodatkowe metadane.
• OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Zweryfikuj postęp licznika podpisów, wymuś kontrolę statusu konta.
• OnWebAuthnAuthenticationSuccessful(Sender, Credential): Zaktualizuj licznik podpisów i wygeneruj tokeny sesji.
• OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Wdroż rate limiting, polityki blokady oraz audyt.

Te zdarzenia umożliwiają szczegółową kontrolę nad każdym krokiem protokołu, od generowania opcji po przetwarzanie assertions.