Passkeys et WebAuthn en 2026 : Guide pratique d'implémentation pour les développeurs web
Les passkeys promettent une connexion sans mot de passe sans stocker de secrets de mot de passe, mais implémenter WebAuthn correctement requiert plus que d'appeler une API navigateur. Apprenez comment l'enregistrement, l'authentification, la vérification côté serveur, les identifiants découvrables et la récupération de compte s'intègrent dans une application web sécurisée.
Les mots de passe ont été le mécanisme d'authentification par défaut des applications web pendant des décennies. Ils sont également une source persistante de problèmes de sécurité.
Les utilisateurs les réutilisent. Les attaquants les volent par hameçonnage. Les serveurs doivent protéger les empreintes de mot de passe, gérer les réinitialisations et se défendre contre les attaques de bourrage d'identifiants.
Les passkeys offrent une approche fondamentalement différente.
Au lieu de demander aux utilisateurs de se souvenir d'un secret partagé, les passkeys utilisent la cryptographie à clé publique et un authentificateur contrôlé par l'utilisateur. Le navigateur fournit une interface standard via WebAuthn, tandis que le serveur vérifie la preuve cryptographique que le bon identifiant a été utilisé.
La technologie n'est plus expérimentale. WebAuthn est largement disponible dans les navigateurs modernes, et ses méthodes de commodité JSON ont considérablement simplifié l'intégration.
Mais la création d'une connexion passkey sécurisée nécessite toujours une conception minutieuse du backend.
Ce guide explique l'architecture, démontre les flux du côté navigateur et identifie les vérifications du côté serveur que les développeurs ne doivent pas négliger.
1. Qu'est-ce qu'une passkey exactement ?
Une passkey est un identifiant FIDO découvrable utilisé pour authentifier un utilisateur via la cryptographie à clé publique.
Lors de l'enregistrement, un authentificateur crée une paire de clés cryptographiques.
La clé privée reste protégée par l'authentificateur ou son écosystème de gestion d'identifiants. Le site web reçoit la clé publique correspondante et l'associe au compte de l'utilisateur.
Lors de l'authentification, le serveur émet un défi frais. L'authentificateur signe des données associées à ce défi, et le serveur vérifie la signature à l'aide de la clé publique stockée.
Il n'y a aucun mot de passe réutilisable envoyé au site web.
Un authentificateur peut être un smartphone, un ordinateur utilisant Windows Hello, une clé de sécurité matérielle ou un gestionnaire d'identifiants prenant en charge les passkeys synchronisés.
Toutes les passkeys ne sont pas synchronisées entre les appareils. Certains identifiants restent liés à l'appareil, tandis que d'autres peuvent être sauvegardés en toute sécurité et rendus disponibles via un fournisseur d'identifiants.
Les spécifications FIDO sont conçues pour résister au hameçonnage en liant les identifiants au domaine de la partie dépendante. Les données biométriques, lorsqu'elles sont utilisées, sont traitées localement par l'appareil plutôt qu'envoyées au site web.
2. WebAuthn est l'API navigateur derrière les passkeys
WebAuthn est l'API de la plateforme web qui permet aux sites web de créer et d'utiliser des identifiants à clé publique.
Deux méthodes navigateur constituent le fondement :
navigator.credentials.create()
navigator.credentials.get()
La première crée un identifiant. La deuxième demande une authentification à l'aide d'un identifiant existant.
Ces deux méthodes fonctionnent avec l'option publicKey et requièrent un contexte sécurisé, normalement HTTPS.
Importantement, le navigateur ne décide pas si l'utilisateur est authentifié. Il retourne des données que le backend doit vérifier.
Une invite navigateur réussie n'est pas la preuve qu'une connexion doit être acceptée.
Le serveur reste responsable de la vérification du défi, de l'origine, de l'identifiant de la partie dépendante et de la preuve cryptographique.
3. Comprendre l'architecture complète
Une implémentation typique contient quatre composants :
- L'application web frontend, qui invoque WebAuthn.
- Le backend applicatif, qui génère des défis et vérifie les réponses.
- L'authentificateur ou fournisseur de passkeys, qui protège la clé privée.
- La base de données, qui stocke les métadonnées d'identifiant et les clés publiques.
Le flux d'enregistrement est : l'application web demande des options d'enregistrement ; le backend génère un défi et des données utilisateur ; le navigateur et l'authentificateur créent un identifiant et une paire de clés ; et le backend vérifie le résultat et stocke la clé publique.
Le serveur ne doit jamais faire confiance aux données d'enregistrement simplement parce qu'elles ont été retournées par le navigateur.
Un client malveillant peut soumettre des requêtes HTTP arbitraires sans utiliser le frontend attendu du tout.
C'est pourquoi la vérification appartient au serveur.
4. Générer les options d'enregistrement sur le serveur
Avant d'appeler WebAuthn, le backend génère un défi d'enregistrement et des options.
Un objet options représentatif ressemble à ceci :
{
"rp": {
"name": "Example Application",
"id": "example.com"
},
"user": {
"id": "dXNlci0xMjM",
"name": "alex@example.com",
"displayName": "Alex"
},
"challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"timeout": 300000
}
Il s'agit d'un JSON illustratif, et non d'une réponse de production complète.
Plusieurs champs sont importants.
rp.id identifie la partie dépendante. Par exemple, example.com peut être utilisé pour les sous-domaines appropriés de ce domaine, sous réserve des règles de validation de l'ID de partie dépendante de WebAuthn.
user.id doit être un identifiant de compte stable et opaque encodé en base64url pour le transport JSON. Il ne doit pas exposer d'informations personnelles inutiles.
challenge doit être généré à l'aide d'une source aléatoire cryptographiquement sécurisée sur le serveur.
residentKey: "required" demande un identifiant découvrable, nécessaire à l'expérience passkey.
userVerification: "required" demande une vérification utilisateur locale, telle qu'un code PIN d'appareil ou une authentification biométrique. Le backend doit ensuite vérifier que la vérification a effectivement eu lieu.
Le guide d'enregistrement côté serveur de Google décrit ces champs et recommande d'utiliser une bibliothèque WebAuthn maintenue pour générer et valider les données d'enregistrement.
5. Créer la passkey en JavaScript
Les navigateurs modernes fournissent une méthode utile :
PublicKeyCredential.parseCreationOptionsFromJSON()
Elle convertit une représentation JSON contenant des champs binaires encodés en base64url dans la structure attendue par WebAuthn.
Cela évite d'écrire une logique de conversion base64url-vers-ArrayBuffer personnalisée pour chaque champ.
Voici une fonction d'enregistrement côté navigateur simplifiée :
async function registerPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/register/options',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
}
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start registration');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseCreationOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.create({
publicKey
});
if (!credential) {
throw new Error('No credential was created');
}
const verifyResponse = await fetch(
'/api/passkeys/register/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Registration verification failed');
}
return await verifyResponse.json();
}
La variable csrfToken représente un jeton anti-CSRF fourni par l'application. Le serveur doit le valider. L'exemple suppose également que la page est déjà associée à un utilisateur authentifié de manière sécurisée.
credential.toJSON() fournit une représentation JSON-friendly de l'identifiant retourné, évitant une autre couche de sérialisation binaire manuelle.
Ces commodités sont disponibles dans les navigateurs actuels, bien que les applications prenant en charge les anciennes versions de navigateurs doivent fournir une gestion de compatibilité.
Le code ci-dessus n'est que le côté navigateur. Ce n'est pas une implémentation d'authentification complète.
6. Ce que le serveur doit vérifier lors de l'enregistrement
Lorsque le navigateur retourne le nouvel identifiant, le backend doit le valider avant de stocker quoi que ce soit.
Au minimum, le processus de vérification doit établir que :
- Le défi retourné correspond à celui généré pour cette tentative d'enregistrement.
- Le défi est frais et n'a pas déjà été consommé.
- L'origine signalée correspond à une origine d'application explicitement approuvée.
- Les données de l'authentificateur correspondent à l'ID de partie dépendante attendu.
- Les conditions de présence utilisateur et de vérification utilisateur requises sont satisfaites.
- La clé publique et l'identifiant de l'identifiant peuvent être extraits et validés.
- L'enregistrement est associé au compte authentifié correct.
Selon la politique de l'application, des vérifications supplémentaires peuvent inclure les algorithmes pris en charge, l'unicité de l'identifiant et les exigences d'attestation.
Un enregistrement réussi stocke généralement :
| Champ | But |
|---|---|
credential_id |
Identifie l'identifiant |
user_id |
Le lie à un compte |
public_key |
Vérifie les signatures futures |
sign_count |
Suit les données de compteur de l'authentificateur |
transports |
Indices de transport d'authentificateur optionnels |
created_at |
Horodatage d'enregistrement |
last_used_at |
Gestion de compte et audit |
backup_eligible / backup_state |
Métadonnées de sauvegarde optionnelles |
La représentation exacte de la base de données dépend de la bibliothèque de vérification et de l'application.
N'implémentez pas l'analyse CBOR, la vérification d'attestation ou la validation de signature cryptographique from scratch à moins d'avoir une raison convaincante et l'expertise pour le maintenir.
La spécification W3C définit des procédures détaillées de vérification d'enregistrement et d'authentification.
7. Authentifier un utilisateur existant
L'authentification suit une structure similaire mais ne crée pas une nouvelle paire de clés.
Le serveur génère un nouveau défi et envoie des options d'authentification au navigateur.
Pour une connexion passkey découvrable, ces options pourraient contenir :
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
Le navigateur peut ensuite demander un identifiant :
async function authenticateWithPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/login/options',
{
credentials: 'same-origin'
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start authentication');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseRequestOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.get({
publicKey
});
if (!credential) {
throw new Error('Authentication was cancelled');
}
const verifyResponse = await fetch(
'/api/passkeys/login/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Authentication failed');
}
return await verifyResponse.json();
}
Cet exemple suppose que le backend associe le défi émis à une transaction de connexion anonyme de courte durée, applique une limitation de débit appropriée et établit une nouvelle session authentifiée uniquement après vérification réussie.
Le serveur doit rechercher l'identifiant de l'identifiant, vérifier l'assertion signée avec la clé publique stockée, confirmer le défi et l'origine, et appliquer sa politique de vérification utilisateur.
Ce n'est qu'alors qu'il devrait établir la session de l'utilisateur.
parseRequestOptionsFromJSON() fait partie de l'API WebAuthn moderne et supprime le besoin de décoder manuellement les champs binaires dans les intégrations côté navigateur courantes.
8. Ajouter des passkeys aux formulaires de connexion existants avec médiation conditionnelle
L'une des fonctionnalités WebAuthn les plus utiles est la médiation conditionnelle, parfois appelée autofill passkey.
Au lieu d'afficher immédiatement une boîte de dialogue passkey séparée, le navigateur peut proposer un passkey disponible aux côtés des autres identifiants enregistrés lorsque l'utilisateur interagit avec un champ de connexion.
L'input HTML peut utiliser :
<input
type="text"
name="username"
autocomplete="username webauthn"
>
L'application peut vérifier la prise en charge :
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Lors de l'appel de navigator.credentials.get(), l'application utilise :
{
publicKey,
mediation: 'conditional'
}
Pour l'autofill d'identifiants découvrables, les options du serveur ne doivent pas restreindre la requête à une liste spécifique d'identifiants d'identifiants.
La médiation conditionnelle est particulièrement utile lors d'une migration progressive depuis les mots de passe car les utilisateurs n'ont pas besoin de se rappeler si un compte particulier possède un passkey.
Le navigateur peut présenter des options appropriées dans l'expérience de connexion familière.
9. Pourquoi les vérifications de défi et d'origine sont essentielles
Les passkeys sont résistantes au hameçonnage, mais cela ne signifie pas qu'une application peut ignorer son protocole d'authentification.
Le défi protège contre les attaques par rejeu.
Sans un défi frais et imprévisible, un attaquant pourrait tenter de réutiliser des données d'authentification d'une session précédente.
Les vérifications d'origine et d'ID de partie dépendante garantissent que les identifiants sont utilisés dans le contexte de site web prévu.
Par exemple, un passkey créé pour example.com ne peut pas simplement être réutilisé par un site de hameçonnage ressemblant tel que examp1e.com.
Le navigateur et l'authentificateur appliquent des parties importantes de cette liaison de domaine, tandis que le backend valide indépendamment les preuves résultantes.
Une bonne implémentation utilise des défis de courte durée, consomme chaque défi une seule fois et n'accepte jamais des origines arbitraires simplement parce qu'elles partagent un nom d'hôte d'apparence familière.
MDN recommande de générer des défis dans un environnement de confiance et de les invalider après une courte période, généralement pas plus d'environ dix minutes.
10. Ne pas mal interpréter les compteurs de signature
Les authentificateurs WebAuthn peuvent inclure un compteur de signature.
Historiquement, les compteurs aidaient à détecter les authentificateurs potentiellement clonés. Si un compteur cesse de manière inattendue d'augmenter, la partie dépendante peut le considérer comme un signal de risque.
Cependant, tous les authentificateurs ne maintiennent pas un compteur significatif.
Certains identifiants rapportent toujours zéro. Les identifiants synchronisés peuvent également compliquer l'interprétation du compteur car plusieurs appareils peuvent utiliser des copies du même identifiant.
La spécification W3C traite explicitement le comportement inattendu du compteur comme un signal possible, et non comme une preuve définitive de clonage.
Par conséquent, les développeurs ne doivent pas rejeter aveuglément chaque connexion dont le compteur est zéro ou inchangé.
Utilisez le compteur en fonction du comportement de l'authentificateur, des conseils de la bibliothèque de vérification WebAuthn et de la politique de sécurité de l'application.
11. La récupération de compte fait partie de la sécurité des passkeys
Une implémentation de passkey est incomplète sans une stratégie de récupération.
Que se passe-t-il lorsqu'un utilisateur perd un appareil ?
Et s'il supprime son seul passkey ?
Et s'il change de fournisseur d'identifiants ou ne peut pas accéder à un identifiant synchronisé ?
Une conception sensée permet aux utilisateurs d'enregistrer plusieurs passkeys et de les gérer depuis leurs paramètres de compte.
L'interface de gestion doit afficher des noms d'identifiants reconnaissables, des dates de création et des informations d'utilisation récentes lorsque disponibles.
Les utilisateurs doivent pouvoir révoquer les identifiants auxquels ils ne font plus confiance.
Mais le mécanisme de récupération mérite une attention particulière.
Si un attaquant peut contourner l'authentification passkey en utilisant un processus de récupération par email faible, le compte global n'est sécurisé qu'autant que ce chemin de récupération.
Pour les comptes à haut risque, envisagez une vérification de récupération plus forte, des codes de récupération, des authentificateurs supplémentaires enregistrés et des notifications concernant les changements de compte sensibles.
Les conseils UX passkey de Google recommandent d'établir une méthode de récupération et de prendre en charge plusieurs passkeys lorsque cela est approprié.
12. Erreurs d'implémentation courantes
Plusieurs erreurs sapent à plusieurs reprises des intégrations passkey par ailleurs prometteuses.
Traiter le succès navigateur comme une authentification serveur. Une promesse navigator.credentials.get() résolue ne remplace pas la vérification cryptographique côté serveur.
Générer des défis en JavaScript. Les défis doivent provenir d'un serveur de confiance et être liés à la transaction d'authentification appropriée.
Utiliser le mauvais ID de partie dépendante. Le scoping de domaine est une fonctionnalité de sécurité, pas un paramètre cosmétique. Les environnements de production, de staging et de développement local nécessitent une configuration délibérée.
Supposer que tous les passkeys se synchronisent. Les identifiants liés à l'appareil restent une partie importante de l'écosystème.
Oublier la révocation d'identifiants. Les utilisateurs ont besoin d'un moyen de supprimer un authentificateur perdu ou compromis de leur compte.
Créer une solution de secours faible. Une connexion résistante au hameçonnage perd une grande partie de sa valeur si la récupération de compte peut être exploitée facilement.
Ignorer les anciens navigateurs. Les méthodes de commodité JSON modernes réduisent la complexité, mais les applications avec des exigences de navigateurs plus anciens peuvent encore avoir besoin de code de compatibilité.
Sauter la protection CSRF et session. Les opérations d'enregistrement et de gestion d'identifiants sont des changements de compte sensibles. Elles nécessitent les mêmes protections que les autres actions de compte à fort impact.
Écrire une vérification cryptographique personnalisée inutilement. Une bibliothèque serveur WebAuthn maintenue est généralement un choix plus sûr que d'implémenter la spécification directement.
13. Chaque site web doit-il remplacer les mots de passe immédiatement ?
Pas nécessairement.
Les passkeys peuvent améliorer à la fois la convivialité et la sécurité, mais la stratégie de migration est importante.
Pour une nouvelle application, l'enregistrement sans mot de passe peut être un défaut raisonnable si le produit dispose d'un flux de récupération bien conçu et prend en charge ses plateformes cibles.
Pour une application existante avec des milliers d'utilisateurs, l'adoption incrémentale est souvent plus sûre.
Commencez par permettre aux utilisateurs authentifiés d'enregistrer des passkeys dans les paramètres de compte.
Ajoutez ensuite la connexion passkey aux côtés du système d'authentification existant.
Introduisez la médiation conditionnelle là où elle est prise en charge.
Mesurez le taux de réussite d'enregistrement, les échecs d'authentification, la compatibilité des appareils et les demandes de récupération.
Enfin, envisagez de faire des passkeys la méthode d'authentification préférée une fois que l'expérience utilisateur et les mécanismes de récupération sont suffisamment matures.
Un déploiement par phases facilite également l'identification des problèmes spécifiques aux navigateurs sans verrouiller les utilisateurs légitimes à l'extérieur.
14. Checklist de préparation pour la production
Avant d'activer les passkeys en production, vérifiez les points suivants :
- Toutes les opérations WebAuthn s'exécutent dans un contexte sécurisé approprié.
- Les ID de partie dépendante et les origines approuvées sont explicitement configurés.
- Les défis sont cryptographiquement aléatoires, de courte durée et à usage unique.
- L'enregistrement nécessite une autorisation de compte appropriée.
- La vérification côté serveur suit la spécification WebAuthn.
- Les clés publiques et les identificateurs d'identifiants sont stockés en toute sécurité.
- La connexion établit une session uniquement après vérification réussie.
- Les exigences de vérification utilisateur sont appliquées côté serveur.
- La suppression d'identifiants et la récupération de compte sont protégées.
- Plusieurs identifiants par compte sont pris en charge lorsque cela est approprié.
- Les échecs d'authentification et les changements de compte sensibles sont surveillés.
- Les scénarios mobile, bureau, inter-appareils et clé matérielle sont testés.
Ces vérifications sont plus importantes que de savoir si le frontend peut afficher une invite de connexion biométrique attrayante.
Conclusion : les passkeys sont une architecture d'authentification, pas seulement une fonctionnalité navigateur
WebAuthn rend l'authentification à clé publique accessible aux applications web ordinaires.
Les API navigateur modernes ont supprimé une grande partie du travail de sérialisation qui rendait auparavant l'intégration des passkeys fastidieuse.
Mais le navigateur n'est qu'une partie du système.
Le vrai travail d'implémentation réside dans la gestion des défis, la vérification côté serveur, le stockage des identifiants, la configuration de domaine, la récupération de compte et les parcours utilisateur sécurisés.
Pour les développeurs créant des applications modernes en PHP, JavaScript, Python ou d'autres environnements backend, les passkeys valent de plus en plus la peine d'être considérés comme une alternative pratique aux mots de passe traditionnels.
Le meilleur point de départ n'est pas de remplacer tout un système d'authentification du jour au lendemain.
C'est d'implémenter un flux complet d'enregistrement et de connexion correctement vérifié, puis de construire une stratégie de migration sécurisée autour de celui-ci.