Skip to Content

Passkey / WebAuthn

Le Passkey sono credenziali FIDO2/WebAuthn che consentono agli utenti di autenticarsi con la biometria del dispositivo (Face ID, Touch ID, Windows Hello), chiavi di sicurezza hardware (YubiKey) o autenticatori di piattaforma — senza password.

Le passkey sono resistenti al phishing poiché sono legate al dominio dell’applicazione e non possono essere usate su siti falsi. Non vengono mai trasmesse al server, eliminando i rischi legati alla condivisione di segreti.

Supporto Browser

BrowserVersione MinimaAutenticatore PiattaformaChiavi Hardware
Chrome108✅✅
Firefox119✅✅
Safari16.4✅✅
Edge108✅✅
Opera94✅✅
Samsung Internet22✅✅

Le passkey sono sincronizzate tra dispositivi tramite il portachiavi iCloud (Apple), Google Password Manager o Windows Hello for Business. Gli utenti che impostano una passkey su iPhone possono usarla anche su Mac e viceversa.

Configurazione nella Console

Abilita WebAuthn

Vai su Console → Impostazioni → Autenticazione → Metodi Passwordless e abilita Passkey / WebAuthn.

Configura l’Origine

Assicurati che il tuo dominio sia registrato come URL autorizzato nelle impostazioni dell’applicazione. L’origine WebAuthn deve corrispondere esattamente al dominio della tua app (es. https://tuaapp.com).

Flusso di Registrazione

Avvia la Registrazione

La tua app richiede le opzioni di registrazione dal server Auris.

import { startRegistration } from '@simplewebauthn/browser'
 
const options = await fetch('/api/auth/webauthn/register/challenge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${accessToken}` },
}).then(r => r.json())

Richiedi le Credenziali al Browser

const registration = await startRegistration(options)

Il browser mostra il prompt di biometria/passkey all’utente.

Verifica sul Server

const { verified } = await fetch('/api/auth/webauthn/register/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify(registration),
}).then(r => r.json())
 
if (verified) {
  console.log('Passkey registrata!')
}

Flusso di Autenticazione

Avvia l’Autenticazione

import { startAuthentication } from '@simplewebauthn/browser'
 
const options = await fetch('/api/auth/webauthn/authenticate/challenge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]' }),
}).then(r => r.json())

Ottieni le Credenziali dal Browser

const authentication = await startAuthentication(options)

Il browser mostra il prompt di biometria/passkey all’utente.

Verifica e Ottieni i Token

const { tokens, user } = await fetch('/api/auth/webauthn/authenticate/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(authentication),
}).then(r => r.json())
 
console.log('Autenticato:', user)

Libreria Client

Auris è compatibile con @simplewebauthn/browser per gestire la complessità del WebAuthn lato client:

npm install @simplewebauthn/browser

Questa libreria gestisce la serializzazione/deserializzazione dei buffer, la compatibilità cross-browser e la gestione degli errori.

WebAuthn come Secondo Fattore (2FA)

Le passkey possono essere usate anche come secondo fattore dopo il login con email/password. In questo caso, la registrazione della passkey richiede una sessione attiva e la verifica avviene come step aggiuntivo nel flusso MFA.

Abilitalo da Console → Impostazioni → MFA → Metodi MFA → Passkey / WebAuthn.

Endpoint API

POST/api/auth/webauthn/register/challengeRequires: authenticated

Genera le opzioni per la registrazione WebAuthn. Richiede una sessione autenticata. Restituisce le opzioni di PublicKeyCredentialCreationOptions.

POST/api/auth/webauthn/register/verifyRequires: authenticated

Verifica e salva la nuova credenziale WebAuthn. Corpo richiesta: l’oggetto RegistrationResponseJSON di SimpleWebAuthn.

POST/api/auth/webauthn/authenticate/challenge

Genera le opzioni per l’autenticazione WebAuthn. Accetta facoltativamente email per recuperare le credenziali registrate dell’utente.

POST/api/auth/webauthn/authenticate/verify

Verifica l’assertion WebAuthn e restituisce i token di autenticazione. Corpo richiesta: l’oggetto AuthenticationResponseJSON di SimpleWebAuthn.

DELETE/api/auth/webauthn/credentials/{id}Requires: authenticated

Rimuove una passkey/credenziale WebAuthn registrata dall’account dell’utente.

Sicurezza

  • Resistenza al phishing: Le credenziali WebAuthn sono associate al dominio dell’origine. Una credenziale registrata su tuaapp.com non può essere usata su tuaapp-fake.com
  • Nessun segreto condiviso: La chiave privata non lascia mai il dispositivo dell’utente. Il server memorizza solo la chiave pubblica
  • Protezione dalla clonazione: Il contatore delle firme (sign_count) aumenta a ogni utilizzo. Auris valida il contatore e avvisa in caso di possibile clonazione delle credenziali
  • Binding all’utente: Le credenziali WebAuthn sono associate a uno specifico utente e non possono essere usate per autenticare un altro utente

Se un utente perde l’accesso a tutti i suoi dispositivi con passkey registrate, potrebbe non riuscire ad accedere. Assicurati di fornire metodi di recupero dell’account alternativi (email di recupero, codici di backup).

Guide Correlate

Architettura