Orientamento delle passkey

Funzionalità web: Autenticazione web

Questa guida fornisce un orientamento ad alta densità e orientato all'azione per l'implementazione di un'autenticazione con passkey e una gestione delle credenziali sicure e indipendenti dal framework nelle applicazioni web moderne.

1. Prerequisiti fondamentali per le passkey

Le passkey si basano sull'API Web Authentication (WebAuthn), che impone rigidi vincoli di sicurezza trasversali che devono essere soddisfatti prima di qualsiasi tentativo di implementazione:

  • Contesti sicuri: i metodi WebAuthn (navigator.credentials.create e navigator.credentials.get) sono rigorosamente protetti da contesti sicuri. Le applicazioni DEVONO essere eseguite su https:// in produzione o su http://localhost per lo sviluppo locale.
  • ID della relying party (RP): ogni credenziale è associata a un ID RP (essenzialmente il nome di dominio dell'applicazione). L'ID RP passato nelle opzioni lato server DEVE corrispondere o essere un suffisso valido del nome di dominio dell'origine corrente (ad es. example.com è valido per login.example.com). Le mancate corrispondenze generano eccezioni SecurityError sul lato client.

2. Il caveat relativo alla UX dell'AAGUID

L'Authenticator Attestation Globally Unique Identifier (AAGUID) è un identificatore univoco a 128 bit restituito nei dati di attestazione della registrazione che rappresenta il modello/provider dell'autenticatore (ad es. Gestore delle password di Google, Portachiavi iCloud, 1Password).

  • Solo suggerimenti UX: le Relying Party DEVONO utilizzare l'AAGUID esclusivamente per i suggerimenti UX (ad esempio, per visualizzare il nome e l'icona del provider di passkey in un elenco di gestione per aiutare l'utente).
  • Nessuna dipendenza dalla sicurezza: le applicazioni NON DEVONO utilizzare l'AAGUID per la sicurezza crittografica o le decisioni di accesso. Le passkey della piattaforma al momento non forniscono l'attestazione crittografica per i loro AAGUID, il che significa che possono essere alterate o simulate dagli user agent.

3. Contenuti consigliati della raccolta disaccoppiati

Per la generazione delle opzioni FIDO2/WebAuthn di backend e la verifica della firma, gli sviluppatori DEVONO fare affidamento su librerie open source verificate per lingua anziché sulla crittografia manuale:

  • 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: libreria .NET per FIDO2 (github.com/abergs/fido2-net-lib)
  • Go: libreria Go WebAuthn (github.com/go-webauthn/webauthn)
  • Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP: WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. Matrice di riferimento dei casi d'uso

Identifica il caso d'uso corrispondente di seguito e recupera la guida all'implementazione completa. Ogni caso d'uso ha API critiche (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, mediazione condizionale, gestione di AAGUID e così via) documentate solo nella guida per caso d'uso. NON saltare questo passaggio di recupero e NON sostituire i wrapper delle librerie di terze parti (come startAuthentication/startRegistration di SimpleWebAuthn) sul client: chiama direttamente le API native del browser WebAuthn. I consigli sulle librerie nella Sezione 3 si applicano solo al lato server (verifica FIDO2 di backend).

I dettagli specifici dell'implementazione di passkey e WebAuthn sono mappati alle seguenti guide: