Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
I passkey offrono un metodo di autenticazione moderno e resistente al phishing basato sugli standard Web Authentication API (WebAuthn) e FIDO2 . Sono un'alternativa sicura alle password, usando la crittografia a chiave pubblica e l'autenticazione basata su dispositivo. Questo articolo illustra come configurare un'app ASP.NET Core per l'uso di passkey per autenticare gli utenti.
Per indicazioni specifiche per le nuove ed esistenti app Blazor Web App, vedi Implementare le passkey nelle app ASP.NET Core Blazor Web App dopo aver letto questo articolo.
Che cosa sono i passkey?
Le passkey sono una sostituzione delle password che usano coppie di chiavi crittografiche. La chiave privata viene archiviata in modo sicuro nel dispositivo dell'utente, ad esempio in un modulo di sicurezza hardware, nell'autenticatore della piattaforma (esempi: Windows Hello, Touch ID, Face ID) o in un gestore password, mentre la chiave pubblica viene archiviata dall'app Web. Durante l'autenticazione, l'utente dimostra il possesso della chiave privata senza mai uscire dal dispositivo.
I vantaggi principali dei passkey includono:
- Resistenza al phishing: i passkey sono associati a siti Web specifici e non possono essere usati su siti falsi.
- Nessun segreto condiviso: il server archivia solo le chiavi pubbliche, eliminando il rischio di violazioni del database delle password.
- Praticità utente: la semplice verifica biometrica o PIN sostituisce i requisiti complessi delle password.
- Sincronizzazione tra dispositivi: molti provider passkey sincronizzano le credenziali tra i dispositivi di un utente.
Per altre informazioni, vedere Web Authentication API (documentazione mdn).
Passkey in ASP.NET Core Identity
ASP.NET Core Identity include il supporto integrato per la registrazione e l'autenticazione tramite passkey:
- Integrazione senza problemi con l'infrastruttura Identity .
- Supporto dell'autenticazione utente per gli scenari WebAuthn più comuni.
- Integrato nel modello di Blazor Web App progetto, quindi è necessaria solo la configurazione dello sviluppatore.
Importante
L'implementazione delle passkey in ASP.NET Core Identity è deliberatamente limitata agli scenari di autenticazione. Non è destinato a una libreria WebAuthn per utilizzo generico. Gli sviluppatori che richiedono una funzionalità WebAuthn completa devono prendere in considerazione librerie della community che forniscono supporto completo per i protocolli.
Scenari supportati
L'implementazione passkey di ASP.NET Core Identity supporta gli scenari principali seguenti:
- Aggiunta di passkey agli account esistenti: gli utenti con account basati su password possono registrare passkey come metodo di autenticazione aggiuntivo.
- Creazione di account senza password: gli utenti possono creare account senza password registrando una passkey per la creazione dell'account.
- Accesso senza password: gli utenti possono eseguire l'autenticazione usando solo la passkey senza immettere una password.
Limitazioni
L'implementazione corrente presenta le limitazioni seguenti:
- Limitato ad ASP.NET Core Identity: Le API sono progettate specificamente per Identity gli scenari di autenticazione.
- Nessuna validazione predefinita dell'attestazione: l'implementazione non valida le dichiarazioni di attestazione per impostazione predefinita.
- Supporto per i modelli: solo il modello Blazor Web App supporta le chiavi di accesso.
- Nessun supporto 2FA predefinito: le passkey vengono considerate come un fattore di autenticazione primario, non come secondo fattore.
Concetti principali
Due processi fondamentali sono alla base delle operazioni passkey: attestazione e asserzione.
Attestazione (registrazione)
L'attestazione è il processo di creazione e registrazione di una nuova passkey. Durante l'attestazione, il server genera una richiesta univoca che l'autenticatore deve includere nella credenziale restituita. L'autenticatore crea una nuova coppia di chiavi e restituisce la chiave pubblica insieme ai dati di attestazione che dimostrano l'origine della chiave. Il server verifica quindi questa attestazione e archivia la chiave pubblica per i tentativi di autenticazione futuri.
Asserzione (autenticazione)
L'asserzione è il processo di autenticazione con una passkey esistente. Il server genera una richiesta univoca, che l'autenticatore firma usando la chiave privata. L'autenticatore restituisce questa asserzione firmata al server, che verifica la firma usando la chiave pubblica archiviata in precedenza. Se la firma è valida, l'utente viene autenticato.
Prerequisiti
- .NET SDK (.NET 10 o versione successiva)
- Web browser moderno che supporta WebAuthn.
- Un dispositivo con un autenticatore della piattaforma, ad esempio Windows Hello o Apple secure enclave o una chiave di sicurezza.
Considerazioni sulla sicurezza
Quando si implementano passkey in ASP.NET Core Identity, assicurarsi che l'app soddisfi i requisiti di sicurezza descritti in questa sezione.
Validazione dell'intestazione Host
L'implementazione deduce l'ID relying party dall'intestazione host quando ServerDomain non è configurato in modo esplicito. L'ambiente di hosting deve convalidare gli header Host per prevenire attacchi di delimitazione dell'ambito delle credenziali, che consistono nell'uso di credenziali utente compromesse o rubate (nomi utente, password, token) per ottenere accesso non autorizzato.
Mitigazione: configurare esplicitamente ServerDomain in IdentityPasskeyOptions oppure assicurarsi che l'ambiente di hosting (Kestrel, IIS, proxy inverso) convalidi gli header host. Per informazioni dettagliate sulla configurazione, vedere la documentazione della piattaforma di hosting. Inoltre, se si utilizza il middleware per le intestazioni inoltrate, configurare AllowedHosts in modo esplicito.
Sicurezza del sottodominio
L'implementazione delle passkey di ASP.NET Core gestisce la sicurezza dei sottodomini tramite l'opzione di configurazione ServerDomain. Quando ServerDomain non viene specificato in modo esplicito, l'implementazione usa l'intestazione host per determinare il dominio. Ciò significa che la pagina in cui è stata registrata la passkey controlla il dominio per tale credenziale.
Per esempio:
- Se un passkey è registrato in
app.contoso.com, funziona anche su*.app.contoso.com. - Se registrato in
contoso.com, funziona anche su*.contoso.com. - Il browser applica che i passkey possono essere usati solo nel dominio (e nei sottodomini) in cui sono stati registrati.
Requisito: le app che richiedono un controllo di dominio rigoroso devono essere impostate ServerDomain in modo esplicito anziché basarsi sull'intestazione host. Non fornire contenuto non attendibile in alcun sottodominio all'interno dell'ambito ServerDomain . Se non puoi garantirlo, implementa la convalida personalizzata dell'origine per limitare l'uso delle passkey a origini specifiche.
Requisito HTTPS
Tutte le operazioni passkey richiedono HTTPS. L'implementazione archivia i dati di autenticazione in cookie crittografati e firmati che potrebbero essere intercettati su connessioni non crittografate.
Requisito: usare sempre HTTPS nell'ambiente di produzione. Configurare il protocollo HTTP Strict Transport Security (HSTS) per impedire attacchi di downgrade del protocollo.
Ripristino dell'account
Il ripristino dell'account è principalmente un problema per le app che consentono passkey come unico meccanismo di autenticazione. Il modello di progetto predefinito Blazor Web App richiede già agli utenti di configurare un metodo di autenticazione di backup (password o provider esterno) durante la creazione di un account, quindi il ripristino dell'account viene gestito tramite questi meccanismi esistenti.
Raccomandazioni:
Per le applicazioni che implementano l'autenticazione passkey-only, prendere in considerazione:
- Codici di ripristino generati durante la creazione dell'account.
- Flussi di ripristino basati sulla posta elettronica.
- Registrazione obbligatoria di più passkey.
- Monitoraggio del flag IsBackedUp su UserPasskeyInfo per invitare gli utenti ad aggiungere credenziali aggiuntive.
Controlli amministrativi
Quando viene individuato un modello di autenticazione per avere vulnerabilità di sicurezza, potrebbe essere necessario revocare le credenziali interessate. L'implementazione archivia l'oggetto di attestazione completo con ogni credenziale, incluso il GUID di attestazione dell'autenticatore (AAGUID), che è un identificatore a 128 bit che indica il tipo di chiave.
Implementazione: estrarre AAGUID da oggetti di attestazione archiviati, confrontarsi con modelli compromessi noti e revocare le credenziali interessate. L'affidabilità di AAGUID dipende dal fatto che l'app valida le dichiarazioni di attestazione. Per integrare una logica personalizzata per la convalida dell'istruzione di attestazione, vedere Convalida dell'istruzione di attestazione personalizzata. Le librerie di terze parti sono disponibili per la convalida dell'attestazione, ad esempio Passkeys - FIDO2 .NET Library (WebAuthn) (passwordless-lib/fido2-net-lib repository GitHub)†.
Avvertimento
† Librerie di terze parti, tra cui passwordless-lib/fido2-net-lib, non sono di proprietà o gestite da Microsoft e non sono coperte da alcun Contratto di supporto o licenza Microsoft. Prestare attenzione quando si adotta una libreria di terze parti, in particolare per le funzionalità di sicurezza. Verificare che la libreria segua le specifiche ufficiali e adotta le procedure consigliate per la sicurezza. Mantenere aggiornata la versione della libreria per ottenere le correzioni di bug più recenti.
Limiti delle risorse
Per evitare attacchi di esaurimento del database, le app devono applicare limiti alla registrazione passkey, ad esempio:
- Numero massimo di passkey per account utente.
- Lunghezza massima per i nomi visualizzati delle passkey.
Il Blazor Web App modello applica questi limiti per impostazione predefinita a livello di applicazione. Per esempi, vedere i seguenti componenti Razor nel modello di progetto Blazor Web App:
Annotazioni
In genere, i collegamenti della documentazione alla sorgente di riferimento .NET caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, utilizzare il menu a tendina Seleziona rami o tag.
Configura le opzioni della chiave di accesso
ASP.NET Core Identity offre varie opzioni per configurare il comportamento passkey tramite la IdentityPasskeyOptions classe , tra cui:
- AuthenticatorTimeout: Ottiene o imposta il tempo per cui il browser deve attendere che l'autenticatore fornisca una chiave di accesso come TimeSpan. Questa opzione si applica sia alla creazione di una nuova passkey che alla richiesta di una passkey esistente. Questa opzione viene considerata come hint per il browser e il browser può ignorare l'opzione . Il valore predefinito è 5 minuti.
- ChallengeSize: Ottiene o imposta la dimensione, in byte, della challenge inviata al client durante l'attestazione e l'asserzione. Questa opzione si applica sia alla creazione di una nuova passkey che alla richiesta di una passkey esistente. Il valore predefinito è 32 byte.
-
ServerDomain: ottiene o imposta l'ID relying party (dominio) effettivo del server. Deve essere univoco e verrà usato come identità per il server. Questa opzione si applica sia alla creazione di una nuova passkey che alla richiesta di una passkey esistente. Se
null, ovvero il valore predefinito, viene usata l'origine del server. Per ulteriori informazioni, consultare Identificatore della relying party (RP ID).
Configurazione di esempio:
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
options.ServerDomain = "contoso.com";
options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
options.ChallengeSize = 64;
});
Per un elenco completo delle opzioni di configurazione, vedere IdentityPasskeyOptions. Per le impostazioni predefinite del browser più up-to-date, vedere la specifica W3C WebAuthn.
Annotazioni
I collegamenti della documentazione al codice sorgente di riferimento di .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la prossima versione di anteprima di .NET. Per selezionare un tag per una versione specifica, utilizzare il menu a tendina Seleziona rami o tag.
Validazione della dichiarazione di attestazione personalizzata
Per impostazione predefinita, ASP.NET Core Identity non convalida le istruzioni di attestazione. Questa opzione è adatta per la maggior parte degli scenari di autenticazione consumer. Se l'app richiede la verifica delle proprietà dell'autenticatore o se si vuole impedire l'uso di autenticatori specifici, ad esempio in ambienti aziendali che richiedono un livello di sicurezza superiore, è possibile implementare la convalida dell'attestazione personalizzata:
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
options.VerifyAttestationStatement = async (context) =>
{
// Custom attestation validation logic
// Return 'true' if the attestation is valid
// Return 'false' if the attestation is invalid
return true;
};
});
Avvertimento
La convalida dell'attestazione è complessa e richiede la gestione degli archivi attendibili per i certificati di autenticazione. Implementare la convalida personalizzata solo se l'app richiede la verifica di proprietà di autenticatori specifiche.
Convalida dell'origine personalizzata
La convalida dell'origine predefinita consente le richieste da sottodomini e non consente iframe tra le origini. Per personalizzare questo comportamento:
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
options.ValidateOrigin = async (context) =>
{
// Custom origin validation logic
// Access the origin via 'context.Origin'
// Access the HTTP context via 'context.HttpContext'
// Return 'true' if the origin is valid
// Return 'false' if the origin is invalid
return true;
};
});
Personalizza il gestore delle passkey
IPasskeyHandler<TUser> è il servizio che genera opzioni passkey ed esegue l'attestazione e l'asserzione. ASP.NET Core Identity registra PasskeyHandler<TUser> come implementazione predefinita e SignInManager<TUser> lo richiama. L'interfaccia ha quattro metodi:
- MakeCreationOptionsAsync: genera le opzioni di creazione e lo stato di attestazione per la registrazione di una passkey.
- MakeRequestOptionsAsync: genera le opzioni di richiesta e lo stato dell'asserzione per l'autenticazione con una passkey esistente.
- PerformAttestationAsync: convalida le credenziali restituite dal browser durante la registrazione.
- PerformAssertionAsync: convalida le credenziali restituite dal browser durante l'autenticazione.
La maggior parte delle app deve usare i SignInManager<TUser> metodi mostrati nelle sezioni Flusso di registrazione e Flusso di autenticazione anziché chiamare direttamente il gestore. Questi metodi gestiscono lo stato temporaneo richiesto dalle cerimonie di registrazione e autenticazione a due richieste e proteggono tale stato per conto dell'app.
Quando implementare IPasskeyHandler<TUser>
Per la maggior parte delle personalizzazioni, utilizzare i callback IdentityPasskeyOptions descritti nelle sezioni Convalida dell'istruzione di attestazione personalizzata e Convalida personalizzata dell'origine. Implementare IPasskeyHandler<TUser> solo per gli scenari che le opzioni non possono esprimere, ad esempio:
- Opzioni delle chiavi di accesso variabili in base alla richiesta o al tenant.
- Risoluzione degli utenti da un'origine diversa da UserManager<TUser>.
- Aggiungere controlli che vengono eseguiti prima o dopo la verifica WebAuthn integrata.
L'implementazione dell'interfaccia da zero implica la ripetizione dei passaggi di verifica WebAuthn, che è soggetta a errori. Se possibile, implementare l'interfaccia come wrapper che delega a un'istanza interna PasskeyHandler<TUser> e aggiunge solo il comportamento richiesto.
Avvertimento
Un'app che chiama IPasskeyHandler<TUser> direttamente, anziché tramite SignInManager<TUser>, diventa responsabile dell'archiviazione sicura dello stato di attestazione. Un'app che non riesce a farlo consente a un utente malintenzionato di registrare una passkey in un account di cui non sono proprietari.
Stato dell'attestazione
La registrazione di una passkey si estende su due richieste. La prima richiesta ottiene le opzioni di creazione e la seconda invia le nuove credenziali. Lo stato di attestazione è le informazioni che il server memorizza tra le due richieste.
MakeCreationOptionsAsync restituisce un oggetto PasskeyCreationOptionsResult con due parti:
-
CreationOptionsJson: inviato al browser e passato a
navigator.credentials.create(). - AttestationState: mantenuto dall'app e fornito a AttestationState quando vengono inviate le credenziali.
Lo stato prodotto dal gestore predefinito contiene la challenge e l'PasskeyUserEntity che identifica l'account a cui è associata la passkey. Lo stato viene serializzato come JSON senza firma o crittografia, quindi non fornisce alcuna protezione di integrità propria.
Lo stato è l'unico luogo in cui viene registrate l'account. Una risposta di attestazione proveniente dal browser contiene una nuova chiave pubblica e la challenge firmata, ma non contiene alcun elemento che identifichi un utente, quindi PerformAttestationAsync riporta l'utente ricavato dallo stato in UserEntity. Se lo stato viene modificato prima dell'invio della credenziale, la passkey viene registrata nell'account indicato dallo stato modificato.
Convalidare l'integrità e la proprietà
Un'app che gestisce lo stato di attestazione deve soddisfare i tre requisiti seguenti.
Integrità: il client non deve essere in grado di modificare lo stato. Non posizionare lo stato in un campo modulo nascosto, in un corpo della richiesta o in uno spazio di archiviazione del browser non protetto. Un attaccante che modifica l'ID utente nel parametro state completa normalmente la registrazione e il suo autenticatore viene archiviato nell'account indicato dal parametro state alterato, ottenendo così l'accesso a tale account. Mantenere lo stato nel server o proteggerlo con le API di protezione dei dati ASP.NET Core prima di inviarlo al browser.
Proprietà: lo stato deve essere associato alla sessione che ha richiesto le opzioni di creazione e l'associazione deve essere controllata quando viene inviata la credenziale. Confrontare UserEntity con l'utente connesso prima di archiviare la passkey. Il gestore non esegue questo controllo perché non dispone di alcun record indipendente dell'utente da confrontare.
Uso singolo e scadenza: rimuovere lo stato dopo averlo letto e assegnargli una durata breve. Uno stato che rimane valido può essere riprodotto.
Per riferimento, SignInManager<TUser> soddisfa questi requisiti in base a:
- Archiviazione dello stato in un'autenticazione cookie protetta dalle API di protezione dei dati, che il browser non può leggere o modificare.
- Invalidare lo stato non appena viene letto, limitandolo a un solo utilizzo.
- Registrare se lo stato è stato creato per l'attestazione o per l'asserzione e rifiutare eventuali incongruenze.
Esempio di registrazione
L'esempio seguente chiama IPasskeyHandler<TUser> direttamente e mantiene lo stato di attestazione in un cookie protetto tramite dati. Entrambi gli endpoint richiedono un utente autenticato perché la passkey viene aggiunta all'account connesso:
const string AttestationStateCookieName = "PasskeyAttestationState";
const string AttestationStatePurpose = "Contoso.Passkeys.AttestationState.v1";
app.MapPost("/Account/PasskeyCreationOptions", async (
HttpContext context,
UserManager<ApplicationUser> userManager,
IPasskeyHandler<ApplicationUser> passkeyHandler,
IDataProtectionProvider dataProtectionProvider) =>
{
var user = await userManager.GetUserAsync(context.User);
if (user is null)
{
return Results.Unauthorized();
}
var userId = await userManager.GetUserIdAsync(user);
var userName = await userManager.GetUserNameAsync(user) ?? "User";
var options = await passkeyHandler.MakeCreationOptionsAsync(new()
{
Id = userId,
Name = userName,
DisplayName = userName
}, context);
var attestationState = options.AttestationState
?? throw new InvalidOperationException("No attestation state was created.");
var protector =
dataProtectionProvider.CreateProtector(AttestationStatePurpose);
context.Response.Cookies.Append(
AttestationStateCookieName,
protector.Protect(attestationState),
new CookieOptions
{
HttpOnly = true,
Secure = true,
SameSite = SameSiteMode.Strict,
MaxAge = TimeSpan.FromMinutes(5)
});
return TypedResults.Content(options.CreationOptionsJson,
contentType: "application/json");
}).RequireAuthorization();
Il codice precedente:
- Protegge lo stato di attestazione con le API di protezione dei dati prima che lo stato raggiunga il browser, in modo che il client non possa leggerlo o modificarlo.
- Limita l'oggetto cookie a una durata di cinque minuti, che limita per quanto tempo una registrazione può rimanere aperta.
Quando arrivano le credenziali, l'app ripristina lo stato, verifica che l'attestazione appartenga all'utente connesso e archivia solo la passkey:
app.MapPost("/Account/PasskeyRegistration", async (
PasskeyRegistrationRequest request,
HttpContext context,
UserManager<ApplicationUser> userManager,
IPasskeyHandler<ApplicationUser> passkeyHandler,
IDataProtectionProvider dataProtectionProvider) =>
{
var user = await userManager.GetUserAsync(context.User);
if (user is null)
{
return Results.Unauthorized();
}
if (!context.Request.Cookies.TryGetValue(AttestationStateCookieName,
out var protectedState))
{
return Results.BadRequest("No passkey registration is underway");
}
context.Response.Cookies.Delete(AttestationStateCookieName);
var protector =
dataProtectionProvider.CreateProtector(AttestationStatePurpose);
string attestationState;
try
{
attestationState = protector.Unprotect(protectedState);
}
catch (CryptographicException)
{
return Results.BadRequest("The passkey registration state isn't valid");
}
var attestationResult = await passkeyHandler.PerformAttestationAsync(new()
{
HttpContext = context,
CredentialJson = request.CredentialJson,
AttestationState = attestationState
});
if (!attestationResult.Succeeded)
{
return Results.BadRequest($"Error: {attestationResult.Failure.Message}");
}
var userId = await userManager.GetUserIdAsync(user);
if (!string.Equals(attestationResult.UserEntity.Id, userId,
StringComparison.Ordinal))
{
return Results.BadRequest("The passkey isn't registered to the current user");
}
var addResult =
await userManager.AddOrUpdatePasskeyAsync(user, attestationResult.Passkey);
if (!addResult.Succeeded)
{
return Results.BadRequest("Failed to store passkey");
}
return Results.Ok();
}).RequireAuthorization();
Il codice precedente:
- Elimina lo stato cookie prima dell'uso dello stato, quindi lo stato è valido per una singola registrazione.
- Rifiuta la richiesta quando lo stato non può essere protetto, che si verifica quando il valore è stato manomesso o protetto con una chiave diversa.
- Conferma che il risultato dell'attestazione identifica l'utente che ha effettuato l'accesso prima che la passkey venga archiviata. Il gestore accetta l'account dallo stato di attestazione, quindi questo controllo impedisce l'associazione di una passkey a un altro account.
Il PasskeyRegistrationRequest tipo contiene le credenziali serializzate dal browser:
public record PasskeyRegistrationRequest(string CredentialJson);
Registrare un gestore personalizzato
AddSignInManager registra il gestore predefinito con AddScoped anziché TryAddScoped, quindi un gestore personalizzato deve essere registrato dopo i servizi Identity affinché sia l'implementazione che viene risolta:
builder.Services.AddIdentityCore<ApplicationUser>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddSignInManager();
builder.Services
.AddScoped<IPasskeyHandler<ApplicationUser>, CustomPasskeyHandler>();
Flusso di registrazione
Questa sezione illustra ogni passaggio del processo di registrazione passkey, spiegando come ASP.NET Core Identity facilita la creazione e l'archiviazione delle credenziali passkey.
sequenceDiagram
participant Authenticator
participant User
participant Browser
participant Server
User->>Browser: Click "Add passkey"
Browser->>Server: Request creation options
Server->>Browser: Return creation options
Browser->>Authenticator: Request new credential
Authenticator->>User: Verify identity (biometric/PIN)
User->>Authenticator: Approve
Authenticator->>Browser: Return credential
Browser->>Server: Submit credential
Server->>Server: Verify and store
Server->>Browser: Registration complete
Browser->>User: Success message
Passaggio 1: Avvio della registrazione
Il processo di registrazione inizia quando un utente decide di aggiungere una passkey al proprio account. Questo avviene in genere tramite un pulsante o un collegamento nell'interfaccia utente dell'app. Quando questa opzione è selezionata, questo elemento attiva il codice JavaScript per orchestrare il flusso di registrazione.
L'implementazione lato client varia in modo significativo tra le app.
Blazor Web App Nel modello è possibile trovare un esempio completo in PasskeySubmit.razor.js, che mostra come un componente Web personalizzato gestisce l'avvio della registrazione e gestisce le successive chiamate API WebAuthn.
Passaggio 2: Richiesta di opzioni di creazione
Dopo l'avvio della registrazione, il browser deve ottenere le opzioni di creazione dal server. Queste opzioni indicano al browser il tipo di credenziale da creare e includere parametri di sicurezza importanti, ad esempio la richiesta di verifica che deve essere firmata.
Dal punto di vista del browser, questo passaggio comporta l'esecuzione di una richiesta HTTP al server:
async function createCredential(signal) {
// Step 2: Request creation options from the server
const optionsResponse =
await fetchWithErrorHandling('/Account/PasskeyCreationOptions',
{
method: 'POST',
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);
return await navigator.credentials.create({ publicKey: options, signal });
}
async function createCredential(headers, signal) {
// Step 2: Request creation options from the server
const optionsResponse =
await fetchWithErrorHandling('/Account/PasskeyCreationOptions',
{
method: 'POST',
headers,
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);
return await navigator.credentials.create({ publicKey: options, signal });
}
L'applicazione deve definire un endpoint che genera queste opzioni:
app.MapPost("/Account/PasskeyCreationOptions", async (
HttpContext context,
UserManager<ApplicationUser> userManager,
SignInManager<ApplicationUser> signInManager) =>
{
var user = await userManager.GetUserAsync(context.User);
if (user is null)
{
return Results.NotFound();
}
var userId = await userManager.GetUserIdAsync(user);
var userName = await userManager.GetUserNameAsync(user) ?? "User";
var optionsJson = await signInManager.MakePasskeyCreationOptionsAsync(new()
{
Id = userId,
Name = userName,
DisplayName = userName
});
return TypedResults.Content(optionsJson, contentType: "application/json");
});
Il MakePasskeyCreationOptionsAsync metodo è fondamentale per questo processo. Il metodo accetta un PasskeyUserEntity oggetto che descrive l'utente per il quale viene creata la passkey. Questa entità contiene l'ID dell'utente, il nome utente (in genere un indirizzo di posta elettronica) e un nome visualizzato leggibile. Il metodo restituisce una stringa JSON conforme allo schema WebAuthn PublicKeyCredentialCreationOptions , usato dal browser nel passaggio successivo. In background, questo metodo archivia anche lo stato temporaneo in un'autenticazione cookie per garantire che la risposta dal browser corrisponda a queste opzioni specifiche. Le app che gestiscono questo stato devono proteggerlo, come descritto nella sezione Personalizzare il gestore passkey .
Passaggio 3: Il server genera le opzioni
Quando MakePasskeyCreationOptionsAsync viene eseguito, usa la configurazione dell'app IdentityPasskeyOptions per determinare i parametri specifici per la creazione delle credenziali. Queste opzioni controllano vari aspetti del processo di creazione passkey.
È possibile personalizzare queste opzioni durante l'avvio dell'applicazione. Per esempio:
builder.Services.Configure<IdentityPasskeyOptions>(options =>
{
options.ServerDomain = "contoso.com";
options.AuthenticatorTimeout = TimeSpan.FromMinutes(3);
options.UserVerificationRequirement = "required";
options.ResidentKeyRequirement = "preferred";
});
L'opzione UserVerificationRequirement determina se l'autenticatore deve verificare l'identità dell'utente (tramite metodi biometrici o PIN), mentre ResidentKeyRequirement indica se le credenziali devono essere individuabili, consentendo l'autenticazione senza fornire prima un nome utente. Per altre informazioni, vedere IdentityPasskeyOptions.
Passaggio 4: Credenziali richieste client
Con le opzioni di creazione disponibili, JavaScript sul lato client passa le opzioni all'API WebAuthn per creare una nuova credenziale:
async function createCredential(signal) {
// Step 4: Parse the options and request a new credential from the authenticator
const optionsResponse =
await fetchWithErrorHandling('/Account/PasskeyCreationOptions',
{
method: 'POST',
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);
return await navigator.credentials.create({ publicKey: options, signal });
}
async function createCredential(headers, signal) {
// Step 4: Parse the options and request a new credential from the authenticator
const optionsResponse =
await fetchWithErrorHandling('/Account/PasskeyCreationOptions',
{
method: 'POST',
headers,
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJson);
return await navigator.credentials.create({ publicKey: options, signal });
}
La parseCreationOptionsFromJSON funzione converte la risposta JSON nel formato previsto dall'API WebAuthn e navigator.credentials.create() avvia il processo di creazione delle credenziali con l'autenticatore.
Passaggio 5: Interazione dell'autenticatore
A questo punto, il browser comunica con l'autenticatore per creare le credenziali. L'autenticatore richiede all'utente la verifica, che potrebbe comportare l'analisi di un'impronta digitale, l'immissione di un PIN o l'uso del riconoscimento facciale. Questa interazione viene gestita interamente dal browser e dall'autenticatore, che non richiede codice dell'app. L'esperienza utente varia a seconda del tipo di autenticatore e delle funzionalità della piattaforma.
Passaggio 6: Invio di credenziali
Dopo che l'autenticatore crea le credenziali, il browser deve inviare nuovamente le credenziali al server per la verifica e l'archiviazione. Le credenziali devono essere serializzate in JSON prima dell'invio:
async function createCredentialJson(signal) {
const credential = await createCredential(signal);
return JSON.stringify(credential);
}
async function createCredentialJson(headers, signal) {
const credential = await createCredential(headers, signal);
return JSON.stringify(credential);
}
Blazor Web App Nel modello, le credenziali restituite vengono serializzate e inviate automaticamente tramite un modulo, ma il meccanismo di invio esatto varia in base all'applicazione.
Passaggio 7: Verifica e archiviazione del server
Quando il server riceve le credenziali, deve verificarne la validità e archiviare la chiave pubblica per l'autenticazione futura. È qui che le API passkey di ASP.NET Core Identity diventano cruciali.
Il PerformPasskeyAttestationAsync metodo convalida la risposta di attestazione dal client. Questo processo di convalida completo:
- Verifica che il tipo di credenziale corrisponda alle aspettative.
- Convalida il codice JSON dei dati client, inclusa l'origine e la richiesta di verifica.
- Controlla i flag dei dati dell’autenticatore relativi alla presenza e alla verifica dell’utente
- Estrae e convalida la chiave pubblica.
Se tutti i controlli vengono superati, il metodo restituisce un oggetto PasskeyAttestationResult contenente le informazioni passkey verificate.
Dopo aver verificato l'attestazione, l'app usa AddOrUpdatePasskeyAsync per archiviare la passkey nel database:
var attestationResult =
await signInManager.PerformPasskeyAttestationAsync(credentialJson);
if (!attestationResult.Succeeded)
{
return Results.BadRequest($"Error: {attestationResult.Failure.Message}");
}
var addResult =
await userManager.AddOrUpdatePasskeyAsync(user, attestationResult.Passkey);
if (!addResult.Succeeded)
{
return Results.BadRequest("Failed to store passkey");
}
L'oggetto memorizzato UserPasskeyInfo contiene tutte le informazioni necessarie per l'autenticazione futura, inclusi l'ID della credenziale, la chiave pubblica, il contatore delle firme per la protezione dai replay e i flag che indicano se la passkey dispone di un backup o è idonea al backup.
Passaggio 8: Attività successive alla registrazione
Dopo aver registrato correttamente una passkey, le app spesso eseguono attività aggiuntive per migliorare l'esperienza utente. Un modello comune consiste nel richiedere agli utenti di specificare un nome descrittivo per la passkey, semplificando l'identificazione tra più credenziali. La UserPasskeyInfo.Name proprietà archivia questo nome descrittivo, che può essere aggiornato usando lo stesso AddOrUpdatePasskeyAsync metodo:
passkey.Name = "My iPhone";
await userManager.AddOrUpdatePasskeyAsync(user, passkey);
Flusso di autenticazione
Questa sezione illustra come gli utenti eseguono l'autenticazione con i passkey, dall'avvio del processo di accesso alla definizione di una sessione autenticata.
sequenceDiagram
participant Authenticator
participant User
participant Browser
participant Server
User->>Browser: Click "Sign in with passkey"
Browser->>Server: Request authentication options
Server->>Browser: Return authentication options
Browser->>Authenticator: Request assertion
Authenticator->>User: Verify identity
User->>Authenticator: Approve
Authenticator->>Browser: Return signed assertion
Browser->>Server: Submit assertion
Server->>Server: Verify signature
Server->>Browser: Authentication complete
Browser->>User: Redirect to app
Passaggio 1: Avvio dell'autenticazione
Gli utenti in genere avviano l'autenticazione passkey tramite un pulsante dedicato o un collegamento nella pagina di accesso. Alcune app supportano anche l'interfaccia utente condizionale, in cui i passkey vengono visualizzati come suggerimenti per il riempimento automatico nel campo nome utente. Il metodo di avvio attiva il codice JavaScript che gestisce il flusso di autenticazione, simile al processo di registrazione.
Passaggio 2: Richiesta di opzioni di autenticazione
Il browser richiede opzioni di autenticazione dal server per avviare il processo di autenticazione. Queste opzioni includono un elenco di credenziali accettabili e una nuova richiesta di firma:
async function requestCredential(email, mediation, signal) {
// Step 2: Request authentication options from the server
const optionsResponse =
await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${encodeURIComponent(email)}`,
{
method: 'POST',
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
return await navigator.credentials.get({ publicKey: options, mediation, signal });
}
async function requestCredential(email, mediation, headers, signal) {
// Step 2: Request authentication options from the server
const optionsResponse =
await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${encodeURIComponent(email)}`,
{
method: 'POST',
headers,
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
return await navigator.credentials.get({ publicKey: options, mediation, signal });
}
Il MakePasskeyRequestOptionsAsync metodo genera queste opzioni. Quando si specifica un utente specifico, include solo le credenziali dell'utente nell'elenco elementi consentiti. Quando viene chiamato senza un utente, genera opzioni adatte per l'interfaccia utente condizionale o l'autenticazione senza nome utente:
app.MapPost("/Account/PasskeyRequestOptions", async (
SignInManager<ApplicationUser> signInManager,
string? username) =>
{
var user = string.IsNullOrEmpty(username)
? null
: await userManager.FindByNameAsync(username);
var optionsJson = await signInManager.MakePasskeyRequestOptionsAsync(user);
return TypedResults.Content(optionsJson, contentType: "application/json");
});
Passaggio 3: Il server genera le opzioni
Il server genera opzioni di autenticazione usando la stessa IdentityPasskeyOptions configurazione usata durante la registrazione. Deve ServerDomain corrispondere al dominio in cui la passkey è stata registrata originariamente oppure l'autenticazione ha esito negativo. UserVerificationRequirement Determina se l'autenticatore deve verificare l'identità dell'utente durante l'autenticazione.
Passaggio 4: Il client richiede un'asserzione
JavaScript sul lato client passa le opzioni di autenticazione all'API WebAuthn per richiedere un'asserzione dall'autenticatore:
async function requestCredential(email, mediation, signal) {
// Step 4: Parse the options and request an assertion from the authenticator
const optionsResponse =
await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${encodeURIComponent(email)}`,
{
method: 'POST',
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
return await navigator.credentials.get({ publicKey: options, mediation, signal });
}
async function requestCredential(email, mediation, headers, signal) {
// Step 4: Parse the options and request an assertion from the authenticator
const optionsResponse =
await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${encodeURIComponent(email)}`,
{
method: 'POST',
headers,
signal,
});
const optionsJson = await optionsResponse.json();
const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
return await navigator.credentials.get({ publicKey: options, mediation, signal });
}
La navigator.credentials.get() chiamata avvia il processo di autenticazione con l'autenticatore, che richiede all'utente la verifica.
Passaggio 5: Verifica dell'autenticatore
L'autenticatore verifica l'identità dell'utente e firma la richiesta con la chiave privata. Questo processo viene gestito interamente dal browser e dall'autenticatore, simile al passaggio di verifica durante la registrazione. L'esperienza utente dipende dal tipo di autenticatore e può comportare la verifica biometrica o l'immissione del PIN.
Passaggio 6: Invio di asserzioni
Dopo che l'autenticatore crea l'asserzione firmata, il browser lo serializza in JSON e lo invia al server:
async function requestCredentialJson(email, mediation, signal) {
const credential = await requestCredential(email, mediation, signal);
return JSON.stringify(credential);
}
async function requestCredentialJson(email, mediation, headers, signal) {
const credential = await requestCredential(email, mediation, headers, signal);
return JSON.stringify(credential);
}
Il meccanismo di invio varia in base all'app, ma in genere implica un invio di modulo o una chiamata API.
Passaggio 7: Verifica del server
Il server verifica l'asserzione per autenticare l'utente. ASP.NET Core Identity fornisce il PasskeySignInAsync metodo , che esegue il flusso di autenticazione completo in una singola chiamata:
var result = await signInManager.PasskeySignInAsync(credentialJson);
if (result.Succeeded)
{
return Results.Ok("Authentication successful");
}
return Results.Unauthorized();
Il PasskeySignInAsync metodo chiama PerformPasskeyAssertionAsync internamente a:
- Convalidare la firma dell'asserzione usando la chiave pubblica archiviata.
- Verificare che la richiesta corrisponda a quella inviata in origine.
- Controllare i flag di autenticazione per la presenza e la verifica dell'utente.
- Aggiornare il contatore della firma per impedire attacchi di riproduzione.
Se tutti i controlli hanno esito positivo, il metodo esegue l'accesso dell'utente e restituisce un SignInResult che indica il successo.
Il metodo distingue tra un'azione utente ripristinabile e un errore dell'app. Se lo stato della sessione passkey è mancante o scaduto, ad esempio perché l'utente ha impiegato troppo tempo per rispondere all'autenticatore, il metodo restituisce SignInResult.Failed. Chiamare il metodo senza una precedente chiamata a MakePasskeyRequestOptionsAsync solleva un'eccezione InvalidOperationException perché indica un problema nell'applicazione anziché qualcosa che l'utente può riprovare.
Per gli scenari che richiedono un maggiore controllo, è possibile usare PerformPasskeyAssertionAsync direttamente per convalidare l'asserzione senza accedere immediatamente all'utente:
- PerformPasskeyAssertionAsync restituisce un oggetto PasskeyAssertionResult contenente l'utente autenticato e le informazioni passkey aggiornate.
- Poiché il conteggio degli accessi e i flag dell'autenticatore della passkey potrebbero essere cambiati dall'ultima asserzione e la passkey aggiornata non viene archiviata automaticamente quando si chiama PerformPasskeyAssertionAsync, chiamare UserManager<TUser>.AddOrUpdatePasskeyAsync con il valore PasskeyAssertionResult restituito.
Passaggio 8: Definizione della sessione
Al termine dell'autenticazione, ASP.NET Core Identity stabilisce una sessione autenticata per l'utente. Il PasskeySignInAsync metodo gestisce automaticamente questa operazione, creando i cookie e le attestazioni di autenticazione necessari. L'app reindirizza quindi l'utente a risorse protette o visualizza contenuto personalizzato.
Attenuare l'errore PublicKeyCredential.toJSON (TypeError: Illegal invocation)
Il PublicKeyCredential.toJSON metodo restituisce una rappresentazione JSON di un oggetto PublicKeyCredential. Il metodo viene richiamato dal gestore delle password quando l'app tenta di serializzare un PublicKeyCredential oggetto chiamando JSON.stringify durante la registrazione o l'autenticazione di un utente.
Alcuni gestori di password non implementano correttamente il metodo PublicKeyCredential.toJSON, il quale è necessario affinché JSON.stringify possa funzionare durante la serializzazione delle credenziali passkey. Durante la registrazione o l'autenticazione di un utente con un'app basata sul Blazor Web App modello di progetto, l'errore seguente viene generato da alcuni gestori delle password quando si tenta di aggiungere una passkey:
Error: Could not add a passkey: Illegal invocation
Fino a quando la gestione password selezionata non viene aggiornata per implementare correttamente il PublicKeyCredential.toJSON metodo, apportare le modifiche seguenti all'app. Il codice seguente serializza manualmente JSON il PublicKeyCredential.
Components/Account/Shared/PasskeySubmit.razor.js Nel file individuare il blocco di codice di definizione dell'elemento passkey-submit personalizzato:
customElements.define('passkey-submit', class extends HTMLElement {
...
});
Aggiungere la funzione seguente convertToBase64 al blocco di codice:
convertToBase64(o) {
if (!o) {
return undefined;
}
// Normalize Array to Uint8Array
if (Array.isArray(o)) {
o = Uint8Array.from(o);
}
// Normalize ArrayBuffer to Uint8Array
if (o instanceof ArrayBuffer) {
o = new Uint8Array(o);
}
// Convert Uint8Array to base64
if (o instanceof Uint8Array) {
let str = '';
for (let i = 0; i < o.byteLength; i++) {
str += String.fromCharCode(o[i]);
}
o = window.btoa(str);
}
if (typeof o !== 'string') {
throw new Error("Could not convert to base64 string");
}
// Convert base64 to base64url
o = o.replace(/\+/g, "-").replace(/\//g, "_").replace(/=*$/g, "");
return o;
}
obtainAndSubmitCredential Nella funzione del blocco di codice individuare la riga che chiama JSON.stringify con le credenziali dell'utente e rimuovere la riga:
- const credentialJson = JSON.stringify(credential);
Sostituire la riga precedente con il codice seguente:
const credentialJson = JSON.stringify({
authenticatorAttachment: credential.authenticatorAttachment,
clientExtensionResults: credential.getClientExtensionResults(),
id: credential.id,
rawId: this.convertToBase64(credential.rawId),
response: {
attestationObject: this.convertToBase64(credential.response.attestationObject),
authenticatorData: this.convertToBase64(credential.response.authenticatorData ??
credential.response.getAuthenticatorData?.() ?? undefined),
clientDataJSON: this.convertToBase64(credential.response.clientDataJSON),
publicKey: this.convertToBase64(credential.response.getPublicKey?.() ?? undefined),
publicKeyAlgorithm: credential.response.getPublicKeyAlgorithm?.() ?? undefined,
transports: credential.response.getTransports?.() ?? undefined,
signature: this.convertToBase64(credential.response.signature),
userHandle: this.convertToBase64(credential.response.userHandle),
},
type: credential.type,
});
La soluzione alternativa precedente è necessaria solo fino a quando il gestore delle password non viene aggiornato per implementare correttamente il PublicKeyCredential.toJSON metodo. È consigliabile tenere traccia delle note sulla versione del gestore delle password e ripristinare le modifiche precedenti dopo l'aggiornamento del gestore delle password.