El componente TsgcWSAPIServer_WebAuthn es un módulo de servidor Delphi/FPC que implementa el lado de relying party del protocolo WebAuthn sobre HTTPS. Se integra con TsgcWebSocketHTTPServer o TsgcWebSocketServer, y expone endpoints tipo REST para registro y autenticación.
Mecánica de los endpoints
Por defecto, el componente registra rutas bajo /sgcWebAuthn:
| Propósito | Endpoint por defecto | Descripción |
|---|---|---|
| Opciones de registro | /Registration/Options | El cliente solicita un challenge e información de la relying party antes de llamar a navigator.credentials.create |
| Verificación de registro | /Registration/Verify | El navegador envía la nueva credencial, el objeto de attestation y los datos del cliente para que el servidor los valide |
| Opciones de autenticación | /Authentication/Options | El servidor proporciona una lista de IDs de credencial permitidos y un challenge |
| Verificación de autenticación | /Authentication/Verify | El navegador envía la assertion (authenticatorData + firma) para su verificación |
| Helper de JavaScript | /Webauthn | Entrega un script auxiliar que envuelve las llamadas estándar de WebAuthn del navegador |
| Página de prueba | /Test | Una página HTML rápida para ejercitar la API durante el desarrollo |
Los endpoints pueden remapearse mediante EndpointOptions para ajustarse a esquemas de enrutado existentes.
Propiedades principales
- RelyingParty (RPID / RPName) – Mandatory DNS name identifying the logical domain for credentials. Ensure it matches the effective domain of your application.
- Origins & TopOrigins – Semi‑colon separated lists of valid origins.
Originscovers primary domains;TopOriginsis used when embedding in iframes. - AllowCrossOrigins – If set
True, cross‑origin iframes may request authentication. This requires carefully curatedTopOriginsand server‑side validation. - Algorithms – Supported COSE algorithm identifiers (e.g.,
ES256,RS256,EdDSA). This controls which public key types the server will accept. - TimeoutMS – Timeout suggested to the client for completing WebAuthn operations.
- UserVerification – Policy for user verification (
preferred,required,discouraged). - Attestation – Specifies whether attestation is none, indirect, or direct. Direct attestation requires validating the attestation certificate chain.
- 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.
- ChallengeOptions – Allows custom length and randomness source for generated challenges.
- CredentialStorage – While not a direct property, the component expects the application to persist credential public keys, sign counters, and user handles.
Ciclo de vida de eventos
Registro
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Inspecciona el username, aborta si no es válido o proporciona la información del usuario.OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Modifica el challenge o establece los criterios de selección del authenticator antes de enviarlos al cliente.OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Realiza comprobaciones de attestation personalizadas o veta el registro.OnWebAuthnRegistrationSuccessful(Sender, Credential): Almacena el ID de credencial, la clave pública, el contador de firma y el handle de usuario en tu base de datos.OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Registra o devuelve errores más descriptivos.
Autenticación
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Busca los IDs de credencial para el username, decide los transports permitidos (USB, NFC, BLE, internal).OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): PersonalizaUserVerification, ajusta la longitud del challenge o incrusta metadatos adicionales.OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Valida la progresión del contador de firma, aplica comprobaciones del estado de la cuenta.OnWebAuthnAuthenticationSuccessful(Sender, Credential): Actualiza el contador de firma y produce tokens de sesión.OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Implementa rate limiting, políticas de bloqueo y auditoría.
Estos eventos permiten un control de grano fino sobre cada paso del protocolo, desde la generación de opciones hasta el procesamiento de assertions.