El componente TsgcWSServer_API_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 EndpointsOptions 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 (
WebAuthnOptions.Algorithms) – Supported COSE algorithm identifiers (e.g.,ES256,RS256,EdDSA). This controls which public key types the server will accept. - Timeout – Timeout suggested to the client for completing WebAuthn operations.
- UserVerification (
WebAuthnOptions.DefaultOptions.Registration.UserVerification/.Authentication.UserVerification) – Policy for user verification (preferred,required,discouraged). - Attestation (
WebAuthnOptions.DefaultOptions.Registration.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.
- Challenge – Se genera internamente como 32 bytes aleatorios criptográficamente seguros, codificados en hexadecimal; no existe una longitud ni una fuente de aleatoriedad configurables. Una aplicación puede sobrescribir
Response.ChallengedesdeOnWebAuthnRegistrationOptionsResponse/OnWebAuthnAuthenticationOptionsResponseantes de enviarlo al cliente. - 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, var Accept): 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.OnWebAuthnRegistrationValidateCertificate(Sender, Request, Validate, var Accept): Realiza comprobaciones de attestation personalizadas o veta el registro.OnWebAuthnRegistrationSuccessful(Sender, Registration, CredentialRecord, var Accept): 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, Request, Registration, Error): Registra o devuelve errores más descriptivos.
Autenticación
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, var CredentialRecords, var Accept): 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.OnWebAuthnAuthenticationSuccessful(Sender, Request, Authentication, var Accept): Valida la progresión del contador de firma, aplica comprobaciones del estado de la cuenta.OnWebAuthnAuthenticationSuccessful(Sender, Request, Authentication, var Accept): Actualiza el contador de firma y produce tokens de sesión.OnWebAuthnAuthenticationError(Sender, Request, Error): 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.