Die Komponente TsgcWSAPIServer_WebAuthn ist ein Delphi/FPC-Servermodul, das die Relying-Party-Seite des WebAuthn-Protokolls über HTTPS umsetzt. Sie integriert sich in TsgcWebSocketHTTPServer oder TsgcWebSocketServer und stellt REST-ähnliche Endpunkte für Registrierung und Authentifizierung bereit.
Funktionsweise der Endpunkte
Standardmäßig registriert die Komponente Routen unter /sgcWebAuthn:
| Zweck | Standard-Endpunkt | Beschreibung |
|---|---|---|
| Registrierungsoptionen | /Registration/Options | Der Client fordert eine Challenge und Relying-Party-Informationen an, bevor er navigator.credentials.create aufruft. |
| Registrierungsprüfung | /Registration/Verify | Der Browser sendet die neuen Anmeldedaten, das Attestation-Objekt und die Client-Daten zur Serverüberprüfung. |
| Authentifizierungsoptionen | /Authentication/Options | Der Server liefert eine Liste zulässiger Credential-IDs und eine Challenge. |
| Authentifizierungsprüfung | /Authentication/Verify | Der Browser sendet die Assertion (authenticatorData + Signatur) zur Verifizierung. |
| JavaScript-Helfer | /Webauthn | Liefert ein Hilfsskript, das die WebAuthn-Standardaufrufe des Browsers kapselt. |
| Testseite | /Test | Eine einfache HTML-Seite, um die API während der Entwicklung auszuprobieren. |
Endpunkte lassen sich über EndpointOptions umbenennen, um zu bestehenden Routing-Schemata zu passen.
Wichtige Eigenschaften
- RelyingParty (RPID / RPName) – Pflichtangabe: DNS-Name, der die logische Domain für Anmeldedaten identifiziert. Achte darauf, dass er zur effektiven Domain deiner Anwendung passt.
- Origins & TopOrigins – Mit Semikolon getrennte Listen gültiger Origins.
Originsdeckt primäre Domains ab;TopOriginswird beim Einbetten in iFrames verwendet. - AllowCrossOrigins – Wenn auf
Truegesetzt, dürfen cross-origin iFrames eine Authentifizierung anfordern. Das erfordert eine sorgfältig gepflegteTopOrigins-Liste und serverseitige Validierung. - Algorithms – Unterstützte COSE-Algorithmus-Kennungen (z. B.
ES256,RS256,EdDSA). Damit legst du fest, welche Public-Key-Typen der Server akzeptiert. - TimeoutMS – Timeout-Empfehlung an den Client für den Abschluss von WebAuthn-Operationen.
- UserVerification – Richtlinie für die Benutzerverifizierung (
preferred,required,discouraged). - Attestation – Gibt an, ob keine, indirekte oder direkte Attestation verwendet wird. Direkte Attestation erfordert die Validierung der Attestation-Zertifikatskette.
- Metadata Service (MDS) – Ist diese Option aktiviert, zieht die Komponente FIDO-Metadata-Service-Dateien heran, um die Vertrauenswürdigkeit des Authenticator-Modells zu bestätigen. Felder:
MDS_FileName– Lokal gecachte JSON-Metadaten (von FIDO heruntergeladen).RootCert_FileName– Root-Zertifikat zur Verifizierung der Metadaten-Signaturen.
- ChallengeOptions – Ermöglicht eine eigene Länge und Zufallsquelle für die erzeugten Challenges.
- CredentialStorage – Zwar keine direkte Eigenschaft, doch erwartet die Komponente, dass die Anwendung Public Keys, Sign-Counter und User-Handles dauerhaft speichert.
Ereignis-Lebenszyklus
Registrierung
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Benutzernamen prüfen, bei Ungültigkeit abbrechen oder Benutzerinformationen liefern.OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Die Challenge anpassen oder Auswahlkriterien für den Authenticator festlegen, bevor sie an den Client gesendet werden.OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Eigene Attestation-Prüfungen durchführen oder die Registrierung ablehnen.OnWebAuthnRegistrationSuccessful(Sender, Credential): Credential-ID, Public Key, Sign-Counter und User-Handle in deiner Datenbank ablegen.OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Fehler protokollieren oder ausführlichere Fehlermeldungen zurückgeben.
Authentifizierung
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Credential-IDs zum Benutzernamen suchen und die zulässigen Transports (USB, NFC, BLE, intern) festlegen.OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response):UserVerificationanpassen, Challenge-Länge ändern oder zusätzliche Metadaten einbetten.OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Fortschritt des Sign-Counters prüfen und Kontostatus-Kontrollen erzwingen.OnWebAuthnAuthenticationSuccessful(Sender, Credential): Sign-Counter aktualisieren und Session-Tokens erzeugen.OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Rate-Limiting, Sperrrichtlinien und Audit umsetzen.
Diese Ereignisse ermöglichen feingranulare Kontrolle über jeden Schritt des Protokolls — von der Erzeugung der Optionen bis zur Verarbeitung der Assertions.