Présentation des clés d'accès

Fonctionnalités Web : Authentification Web

Ce guide fournit des instructions denses et orientées action pour implémenter une authentification par clé d'accès et une gestion des identifiants sécurisées et indépendantes du framework dans les applications Web modernes.

1. Prérequis essentiels pour les clés d'accès

Les clés d'accès s'appuient sur l'API Web Authentication (WebAuthn), qui impose des contraintes de sécurité transversales strictes à respecter avant toute tentative d'implémentation :

  • Contextes sécurisés : les méthodes WebAuthn (navigator.credentials.create et navigator.credentials.get) sont strictement limitées aux contextes sécurisés. Les applications DOIVENT s'exécuter sur https:// en production ou sur http://localhost pour le développement local.
  • ID de partie de confiance (RP) : chaque identifiant est associé à un ID de RP (essentiellement le nom de domaine de l'application). L'ID de RP transmis dans les options côté serveur DOIT correspondre au nom de domaine de l'origine actuelle ou en être un suffixe valide (par exemple, example.com est valide pour login.example.com). Les non-correspondances entraînent des exceptions SecurityError côté client.

2. Avertissement concernant l'expérience utilisateur de l'AAGUID

L'identifiant unique global d'attestation de l'authentificateur (AAGUID) est un identifiant de 128 bits renvoyé dans les données d'attestation d'enregistrement qui représente le modèle/fournisseur de l'authentificateur (par exemple, le Gestionnaire de mots de passe de Google, le trousseau iCloud, 1Password).

  • Indication d'UX uniquement : les tiers de confiance DOIVENT utiliser l'AAGUID exclusivement pour les indications d'UX (par exemple, pour afficher le nom et l'icône du fournisseur de clé d'accès dans une liste de gestion afin d'aider l'utilisateur).
  • Aucune dépendance de sécurité : les applications NE DOIVENT PAS utiliser l'AAGUID pour la sécurité cryptographique ou les décisions d'accès. Les clés d'accès de plate-forme ne fournissent actuellement pas d'attestation cryptographique pour leurs AAGUID, ce qui signifie qu'elles peuvent être modifiées ou simulées par les user-agents.

3. Recommandations de bibliothèques dissociées

Pour la génération d'options FIDO2/WebAuthn de backend et la validation de signature, les développeurs DOIVENT s'appuyer sur des bibliothèques Open Source validées par langage au lieu de créer manuellement la cryptographie :

  • JavaScript/TypeScript : SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python : py_webauthn (github.com/duo-labs/py_webauthn)
  • Java : Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET : bibliothèque .NET pour FIDO2 (github.com/abergs/fido2-net-lib)
  • Go : bibliothèque WebAuthn Go (github.com/go-webauthn/webauthn)
  • Ruby : WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP : WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. Matrice de référence des cas d'utilisation

Identifiez le cas d'utilisation correspondant ci-dessous et récupérez son guide d'implémentation complet. Chaque cas d'utilisation comporte des API critiques (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, médiation conditionnelle, gestion des AAGUID, etc.) qui ne sont documentées que dans le guide correspondant. Ne sautez PAS cette étape de récupération et ne remplacez PAS les wrappers de bibliothèque tiers (comme startAuthentication/startRegistration de SimpleWebAuthn) sur le client. Appelez directement les API de navigateur WebAuthn natives. Les recommandations de bibliothèques de la section 3 ne s'appliquent qu'au côté serveur (validation FIDO2 du backend).

Les détails d'implémentation spécifiques des clés d'accès et de WebAuthn sont décrits dans les guides suivants :