From c9ffcd20e2895b7be08884ed2b782bcedc13274d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Roland=20V=C4=B1=CC=81zner?= <t-rvzner@microsoft.com>
Date: Mon, 31 Aug 2026 15:17:20 +0200
Subject: [PATCH] Fix outdated template references in the passkeys articles

---
 .../authentication/passkeys/blazor.md         |  29 ++--
 .../security/authentication/passkeys/index.md | 148 +++++++++++++++++-
 2 files changed, 159 insertions(+), 18 deletions(-)

diff --git a/aspnetcore/security/authentication/passkeys/blazor.md b/aspnetcore/security/authentication/passkeys/blazor.md
index 383e7c3a8dba..ba0c668065d4 100644
--- a/aspnetcore/security/authentication/passkeys/blazor.md
+++ b/aspnetcore/security/authentication/passkeys/blazor.md
@@ -1,10 +1,11 @@
 ---
 title: Implement passkeys in ASP.NET Core Blazor Web Apps
+ai-usage: ai-assisted
 author: guardrex
 description: Learn how to implement passkeys authentication in ASP.NET Core Blazor Web Apps.
 ms.author: wpickett
 monikerRange: '>= aspnetcore-10.0'
-ms.date: 10/30/2025
+ms.date: 08/31/2026
 uid: security/authentication/passkeys/blazor
 zone_pivot_groups: implementation
 ---
@@ -191,6 +192,12 @@ Add the following model classes to the project in the `Components/Account` folde
 * [`Components/Account/PasskeyInputModel.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/PasskeyInputModel.cs): Holds the JSON passkey credential for passkey sign-in operations (`Login` component) and adding passkeys (`Passkeys` component).
 * [`Components/Account/PasskeyOperation.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/PasskeyOperation.cs): Defines the authentication action to be performed (`PassKeySubmit` component), either registering a new passkey (`Create`/0) or authenticating with an existing passkey (`Request`/1).
 
+:::moniker range=">= aspnetcore-11.0"
+
+* [`Components/Account/PasskeyAuthenticators.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/PasskeyAuthenticators.cs): Maps Authenticator Attestation GUIDs (AAGUIDs) to friendly display names, so a new passkey from a known authenticator is named automatically instead of prompting the user.
+
+:::moniker-end
+
 ## Create the `PasskeySubmit` component
 
 Add the following `PasskeySubmit` component to handle passkey operations:
@@ -207,7 +214,7 @@ Add the following JavaScript file to handle WebAuthn API interactions:
 
 Update the `IdentityComponentsEndpointRouteBuilderExtensions.cs` file (or create the file if it doesn't exist and call `MapAdditionalIdentityEndpoints` in the [`Program` file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Program.cs#L129-L130)) to include the passkey-specific endpoints:
 
-[`/PasskeyCreationOptions` and `/PasskeyRequestOptions` endpoints](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/IdentityComponentsEndpointRouteBuilderExtensions.cs#L53-L90)
+[`/PasskeyCreationOptions` and `/PasskeyRequestOptions` endpoints](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/IdentityComponentsEndpointRouteBuilderExtensions.cs#L80-L132)
 
 ## Update the Login page
 
@@ -215,18 +222,6 @@ Replace the existing `Login` component with the following component and update t
 
 [`Components/Account/Pages/Login.razor`](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWebCSharp.1/Components/Account/Pages/Login.razor)
 
-## Add a redirect method to the `IdentityRedirectManager` class
-
-Add the following method to the `IdentityRedirectManager` class in `Components/Account/IdentityRedirectManager.cs`:
-
-```csharp
-public void RedirectToInvalidUser(
-    UserManager<ApplicationUser> userManager, HttpContext context) =>
-        RedirectToWithStatus("Account/InvalidUser",
-            $"Error: Unable to load user with ID '{userManager.GetUserId(context.User)}'.",
-            context);
-```
-
 ## Create passkey management pages for adding and renaming passkeys
 
 Add the following `Passkeys` component for managing passkeys and update the `BlazorWebCSharp._1.Data` namespace to match the app (for example: `Contoso.Components.Account.Data`):
@@ -254,13 +249,13 @@ In `Components/Account/Shared/ManageNavMenu.razor`, add the following [`NavLink`
 In the `App` component (`Components/App.razor`), locate the [Blazor script](xref:blazor/project-structure#location-of-the-blazor-script) tag:
 
 ```razor
-<script src="_framework/blazor.web.js"></script>
+<script src="@Assets["_framework/blazor.web.js"]"></script>
 ```
 
 Immediately after the Blazor script tag, add a reference to the `PasskeySubmit` JavaScript module:
 
 ```razor
-<script src="Components/Account/Shared/PasskeySubmit.razor.js" type="module"></script>
+<script src="@Assets["Components/Account/Shared/PasskeySubmit.razor.js"]" type="module"></script>
 ```
 
 :::zone-end
@@ -282,7 +277,7 @@ After a passkey is registered:
 1. Sign out of the app.
 1. On the login page, enter your email address.
 1. Select **Log in with a passkey**.
-4. Follow the browser's prompts to authenticate with your passkey.
+1. Follow the browser's prompts to authenticate with your passkey.
 1. Navigate to `Account/Manage/Passkeys` to add, rename, or delete passkeys.
 1. If the passkey supports passkey autofill (conditional UI) for login, test the passkey autofill feature by selecting the email input field when you have saved passkeys.
 
diff --git a/aspnetcore/security/authentication/passkeys/index.md b/aspnetcore/security/authentication/passkeys/index.md
index ada6a22590f8..0df5180b24c0 100644
--- a/aspnetcore/security/authentication/passkeys/index.md
+++ b/aspnetcore/security/authentication/passkeys/index.md
@@ -5,7 +5,7 @@ author: guardrex
 description: Discover how to enable Web Authentication API (WebAuthn) passkeys in ASP.NET Core apps.
 ms.author: wpickett
 monikerRange: '>= aspnetcore-10.0'
-ms.date: 08/07/2026
+ms.date: 08/31/2026
 uid: security/authentication/passkeys/index
 ---
 # Enable Web Authentication API (WebAuthn) passkeys
@@ -453,6 +453,8 @@ After registration is initiated, the browser must obtain creation options from t
 
 From the browser's perspective, this step involves making an HTTP request to the server:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function createCredential(headers, signal) {
   // Step 2: Request creation options from the server
@@ -469,6 +471,27 @@ async function createCredential(headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+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 });
+}
+```
+
+:::moniker-end
+
 The application should define an endpoint that generates these options:
 
 ```csharp
@@ -522,6 +545,8 @@ The <xref:Microsoft.AspNetCore.Identity.IdentityPasskeyOptions.UserVerificationR
 
 With the creation options available, the client-side JavaScript passes the options to the WebAuthn API to create a new credential:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function createCredential(headers, signal) {
   // Step 4: Parse the options and request a new credential from the authenticator
@@ -538,6 +563,27 @@ async function createCredential(headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+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 });
+}
+```
+
+:::moniker-end
+
 The `parseCreationOptionsFromJSON` function converts the JSON response into the format expected by the WebAuthn API, and `navigator.credentials.create()` initiates the credential creation process with the authenticator.
 
 ### Step 5: Authenticator interaction
@@ -548,6 +594,8 @@ At this point, the browser communicates with the authenticator to create the cre
 
 After the authenticator creates the credential, the browser must send the credential back to the server for verification and storage. The credential must be serialized to JSON before submission:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function createCredential(headers, signal) {
   // Step 6: The credential is returned from navigator.credentials.create()
@@ -565,6 +613,28 @@ async function createCredential(headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+async function createCredential(signal) {
+  // Step 6: The credential is returned from navigator.credentials.create()
+  // and is serialized to JSON for submission to 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 });
+}
+```
+
+:::moniker-end
+
 In the Blazor Web App template, the returned credential is automatically serialized and submitted through a form, but the exact submission mechanism varies by application.
 
 ### Step 7: Server verification and storage
@@ -643,6 +713,8 @@ Users typically initiate passkey authentication through a dedicated button or li
 
 The browser requests authentication options from the server to begin the authentication process. These options include a list of acceptable credentials and a new challenge to be signed:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function requestCredential(email, mediation, headers, signal) {
   // Step 2: Request authentication options from the server
@@ -659,6 +731,27 @@ async function requestCredential(email, mediation, headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+async function requestCredential(email, mediation, signal) {
+  // Step 2: Request authentication options from the server
+  const optionsResponse = 
+    await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${email}`, 
+    {
+      method: 'POST',
+      signal,
+    });
+  const optionsJson = await optionsResponse.json();
+  const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
+  return await navigator.credentials.get({ publicKey: options, mediation, signal });
+}
+```
+
+:::moniker-end
+
 The <xref:Microsoft.AspNetCore.Identity.SignInManager%601.MakePasskeyRequestOptionsAsync%2A> method generates these options. When you provide a specific user, it includes only that user's credentials in the allow list. When called without a user, it generates options suitable for conditional UI or username-less authentication:
 
 ```csharp
@@ -684,6 +777,8 @@ The server generates authentication options using the same <xref:Microsoft.AspNe
 
 The client-side JavaScript passes the authentication options to the WebAuthn API to request an assertion from the authenticator:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function requestCredential(email, mediation, headers, signal) {
   // Step 4: Parse the options and request an assertion from the authenticator
@@ -700,6 +795,27 @@ async function requestCredential(email, mediation, headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+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=${email}`, 
+    {
+      method: 'POST',
+      signal,
+    });
+  const optionsJson = await optionsResponse.json();
+  const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
+  return await navigator.credentials.get({ publicKey: options, mediation, signal });
+}
+```
+
+:::moniker-end
+
 The `navigator.credentials.get()` call initiates the authentication process with the authenticator, which prompts the user for verification.
 
 ### Step 5: Authenticator verification
@@ -710,6 +826,8 @@ The authenticator verifies the user's identity and signs the challenge with the
 
 After the authenticator creates the signed assertion, the browser serializes it to JSON and submits it to the server:
 
+:::moniker range="< aspnetcore-11.0"
+
 ```javascript
 async function requestCredential(email, mediation, headers, signal) {
   // Step 6: The assertion is returned from navigator.credentials.get()
@@ -727,6 +845,28 @@ async function requestCredential(email, mediation, headers, signal) {
 }
 ```
 
+:::moniker-end
+
+:::moniker range=">= aspnetcore-11.0"
+
+```javascript
+async function requestCredential(email, mediation, signal) {
+  // Step 6: The assertion is returned from navigator.credentials.get()
+  // and is serialized to JSON for submission to the server
+  const optionsResponse = 
+    await fetchWithErrorHandling(`/Account/PasskeyRequestOptions?username=${email}`, 
+    {
+      method: 'POST',
+      signal,
+    });
+  const optionsJson = await optionsResponse.json();
+  const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJson);
+  return await navigator.credentials.get({ publicKey: options, mediation, signal });
+}
+```
+
+:::moniker-end
+
 The submission mechanism varies by app but typically involves either a form submission or an API call.
 
 ### Step 7: Server verification
@@ -753,6 +893,12 @@ The <xref:Microsoft.AspNetCore.Identity.SignInManager%601.PasskeySignInAsync%2A>
 
 If all checks pass, the method signs in the user and returns a `SignInResult` indicating success.
 
+:::moniker range=">= aspnetcore-11.0"
+
+The method distinguishes between a recoverable user action and an app error. If the passkey session state is missing or expired, for example because the user took too long to respond to the authenticator, the method returns <xref:Microsoft.AspNetCore.Identity.SignInResult.Failed?displayProperty=nameWithType>. Calling the method without a preceding call to <xref:Microsoft.AspNetCore.Identity.SignInManager%601.MakePasskeyRequestOptionsAsync%2A> throws an <xref:System.InvalidOperationException>, because that indicates a problem in the app rather than something the user can retry.
+
+:::moniker-end
+
 For scenarios requiring more control, you can use <xref:Microsoft.AspNetCore.Identity.SignInManager%601.PerformPasskeyAssertionAsync%2A> directly to validate the assertion without immediately signing in the user:
 
 * <xref:Microsoft.AspNetCore.Identity.SignInManager%601.PerformPasskeyAssertionAsync%2A> returns a <xref:Microsoft.AspNetCore.Identity.PasskeyAssertionResult> containing the authenticated user and updated passkey information.