Le composant TsgcWSAPIServer_WebAuthn est un module serveur Delphi/FPC qui implémente le côté relying-party du protocole WebAuthn sur HTTPS. Il s'intègre avec TsgcWebSocketHTTPServer ou TsgcWebSocketServer, et expose des endpoints de type REST pour l'enregistrement et l'authentification.
Mécanique des endpoints
Par défaut, le composant enregistre des routes sous /sgcWebAuthn :
| Objectif | Endpoint par défaut | Description |
|---|---|---|
| Options d'enregistrement | /Registration/Options | Le client demande un challenge et les infos du relying-party avant d'appeler navigator.credentials.create |
| Vérification d'enregistrement | /Registration/Verify | Le navigateur poste la nouvelle credential, l'objet d'attestation et les données client pour validation côté serveur |
| Options d'authentification | /Authentication/Options | Le serveur fournit une liste d'identifiants de credentials autorisés et un challenge |
| Vérification d'authentification | /Authentication/Verify | Le navigateur poste l'assertion (authenticatorData + signature) pour vérification |
| Helper JavaScript | /Webauthn | Fournit un script utilitaire qui encapsule les appels standard WebAuthn du navigateur |
| Page de test | /Test | Une page HTML rapide pour tester l'API en développement |
Les endpoints peuvent être remappés via EndpointOptions pour s'adapter aux schémas de routage existants.
Propriétés principales
- RelyingParty (RPID / RPName) – Nom DNS obligatoire identifiant le domaine logique des credentials. Assure-toi qu'il corresponde au domaine effectif de ton application.
- Origins & TopOrigins – Listes d'origines valides séparées par des points-virgules.
Originscouvre les domaines principaux ;TopOriginsest utilisé lors de l'intégration dans des iframes. - AllowCrossOrigins – Si défini à
True, les iframes cross-origin peuvent demander l'authentification. Cela nécessite desTopOriginssoigneusement contrôlés et une validation côté serveur. - Algorithms – Identifiants d'algorithmes COSE pris en charge (par ex.
ES256,RS256,EdDSA). Cela contrôle les types de clés publiques que le serveur acceptera. - TimeoutMS – Délai suggéré au client pour terminer les opérations WebAuthn.
- UserVerification – Politique de vérification de l'utilisateur (
preferred,required,discouraged). - Attestation – Spécifie si l'attestation est none, indirect ou direct. L'attestation directe nécessite la validation de la chaîne de certificats d'attestation.
- Metadata Service (MDS) – Quand activé, le composant consulte les fichiers FIDO Metadata Service pour confirmer la fiabilité du modèle d'authentificateur. Champs :
MDS_FileName– Métadonnées JSON locales en cache (téléchargées depuis FIDO).RootCert_FileName– Certificat racine pour vérifier les signatures des métadonnées.
- ChallengeOptions – Permet de personnaliser la longueur et la source d'aléatoire des challenges générés.
- CredentialStorage – Bien que ce ne soit pas une propriété directe, le composant s'attend à ce que l'application stocke les clés publiques des credentials, les compteurs de signature et les identifiants utilisateur.
Cycle de vie des événements
Enregistrement
OnWebAuthnRegistrationOptionsRequest(Sender, Request, Response): Inspecte le nom d'utilisateur, annule s'il est invalide ou fournit les informations utilisateur.OnWebAuthnRegistrationOptionsResponse(Sender, Request, Response): Modifie le challenge ou définit les critères de sélection de l'authentificateur avant l'envoi au client.OnWebAuthnRegistrationVerify(Sender, Credential, var Success): Effectue des vérifications d'attestation personnalisées ou bloque l'enregistrement.OnWebAuthnRegistrationSuccessful(Sender, Credential): Stocke l'identifiant de credential, la clé publique, le compteur de signature et l'identifiant utilisateur dans ta base de données.OnWebAuthnRegistrationError(Sender, ErrorCode, ErrorMsg): Journalise ou renvoie des erreurs plus descriptives.
Authentification
OnWebAuthnAuthenticationOptionsRequest(Sender, Request, Response): Recherche les identifiants de credentials pour le nom d'utilisateur, décide des transports autorisés (USB, NFC, BLE, internal).OnWebAuthnAuthenticationOptionsResponse(Sender, Request, Response): PersonnaliseUserVerification, ajuste la longueur du challenge ou intègre des métadonnées supplémentaires.OnWebAuthnAuthenticationVerify(Sender, Credential, var Success): Valide la progression du compteur de signature, applique les contrôles d'état du compte.OnWebAuthnAuthenticationSuccessful(Sender, Credential): Met à jour le compteur de signature et produit des jetons de session.OnWebAuthnAuthenticationError(Sender, ErrorCode, ErrorMsg): Implémente la limitation de débit, les politiques de verrouillage et l'audit.
Ces événements offrent un contrôle fin sur chaque étape du protocole, de la génération des options au traitement des assertions.