Il componente TsgcWSAPIServer_WebAuthn è un modulo server Delphi/FPC che implementa il lato relying‑party del protocollo WebAuthn su HTTPS. Si integra con TsgcWebSocketHTTPServer o TsgcWebSocketServer ed espone endpoint REST‑like per la registrazione e l'autenticazione.
Funzionamento degli endpoint
Per impostazione predefinita, il componente registra le route sotto /sgcWebAuthn:
| Scopo | Endpoint predefinito | Descrizione |
|---|---|---|
| Opzioni di registrazione | /Registration/Options | Il client richiede una challenge e le informazioni della relying‑party prima di chiamare navigator.credentials.create |
| Verifica registrazione | /Registration/Verify | Il browser invia la nuova credenziale, l'attestation object e i client data per la convalida del server |
| Opzioni di autenticazione | /Authentication/Options | Il server fornisce un elenco di ID di credenziali consentite e una challenge |
| Verifica autenticazione | /Authentication/Verify | Il browser invia l'assertion (authenticatorData + firma) per la verifica |
| Helper JavaScript | /Webauthn | Fornisce uno script helper che incapsula le chiamate WebAuthn standard del browser |
| Pagina di test | /Test | Una pagina HTML rapida per provare l'API in fase di sviluppo |
Gli endpoint possono essere rimappati tramite EndpointOptions per adattarsi agli schemi di routing esistenti.
Proprietà principali
- RelyingParty (RPID / RPName) – Nome DNS obbligatorio che identifica il dominio logico delle credenziali. Assicurati che corrisponda al dominio effettivo della tua applicazione.
- Origins e TopOrigins – Elenchi separati da punto e virgola di origini valide.
Originscopre i domini principali;TopOriginssi usa quando il sito è incorporato in iframe. - AllowCrossOrigins – Se impostato a
True, gli iframe cross‑origin possono richiedere l'autenticazione. Ciò richiedeTopOriginscurati con attenzione e validazione lato server. - Algorithms – Identificatori di algoritmi COSE supportati (es.
ES256,RS256,EdDSA). Controlla quali tipi di chiave pubblica il server accetta. - TimeoutMS – Timeout suggerito al client per completare le operazioni WebAuthn.
- UserVerification – Policy per la verifica utente (
preferred,required,discouraged). - Attestation – Specifica se l'attestation è none, indirect o direct. L'attestation di tipo direct richiede la validazione della catena di certificati di attestation.
- Metadata Service (MDS) – Quando abilitato, il componente consulta i file del FIDO Metadata Service per confermare l'affidabilità del modello di authenticator. Campi:
MDS_FileName– Metadati JSON in cache locale (scaricati da FIDO).RootCert_FileName– Certificato root per verificare le firme dei metadati.
- ChallengeOptions – Permette lunghezza personalizzata e sorgente di casualità per le challenge generate.
- CredentialStorage – Pur non essendo una proprietà diretta, il componente si aspetta che l'applicazione persista le chiavi pubbliche delle credenziali, i sign counter e gli user handle.
Ciclo di vita degli eventi
Registrazione
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): ispeziona lo username, annulla se non valido o fornisci le informazioni utente.OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): modifica la challenge o imposta i criteri di selezione dell'authenticator prima dell'invio al client.OnWebAuthnRegistrationVerify(Sender, Credential, var Success): esegue controlli personalizzati di attestation o nega la registrazione.OnWebAuthnRegistrationSuccessful(Sender, Credential): memorizza nel database l'ID della credenziale, la chiave pubblica, il sign counter e l'user handle.OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): registra log o restituisci errori più descrittivi.
Autenticazione
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): cerca gli ID delle credenziali per lo username, decidi i transport consentiti (USB, NFC, BLE, internal).OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): personalizzaUserVerification, regola la lunghezza della challenge o incorpora metadati aggiuntivi.OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): convalida la progressione del sign counter e applica i controlli sullo stato dell'account.OnWebAuthnAuthenticationSuccessful(Sender, Credential): aggiorna il sign counter e genera i token di sessione.OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): implementa rate limiting, policy di blocco e audit.
Questi eventi consentono un controllo a grana fine su ogni fase del protocollo, dalla generazione delle opzioni al processamento delle assertion.