Merge pull request #34339 from dotnet/main

Author: guardrex

aspnetcore/blazor/fundamentals/index.md

@@ -69,6 +69,7 @@ Blazor documentation adopts several conventions for showing and discussing compo
 * [Component parameter](xref:blazor/components/index#component-parameters) values lead with a [Razor reserved `@` symbol](xref:mvc/views/razor#razor-syntax), but it isn't required. Literals (for example, boolean values), keywords (for example, `this`), and `null` as component parameter values aren't prefixed with `@`, but this is also merely a documentation convention. Your own code can prefix literals with `@` if you wish.
 * C# classes use the [`this` keyword](/dotnet/csharp/language-reference/keywords/this) and avoid prefixing fields with an underscore (`_`) that are assigned to in constructors, which differs from the [ASP.NET Core framework engineering guidelines](https://github.com/dotnet/aspnetcore/wiki/Engineering-guidelines).
 * In examples that use [primary constructors (C# 12 or later)](/dotnet/csharp/whats-new/tutorials/primary-constructors), primary constructor parameters are typically used directly by class members.
+In article examples, code lines are split to reduce horizontal scrolling. These breaks don't affect execution but can be removed when pasting into your project.
 
 Additional information on Razor component syntax is provided in the *Razor syntax* section of <xref:blazor/components/index#razor-syntax>.
 

aspnetcore/blazor/security/qrcodes-for-authenticator-apps.md

@@ -11,107 +11,62 @@ uid: blazor/security/qrcodes-for-authenticator-apps
 
 [!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)]
 
-This article explains how to configure an ASP.NET Core Blazor Web App with QR code generation for TOTP authenticator apps.
+This article explains how to configure an ASP.NET Core Blazor Web App for two-factor authentication (2FA) with QR codes generated by Time-based One-time Password Algorithm (TOTP) authenticator apps.
 
-For an introduction to two-factor authentication (2FA) with authenticator apps using a Time-based One-time Password Algorithm (TOTP), see <xref:security/authentication/identity-enable-qrcodes>.
+For an introduction to 2FA with TOTP authenticator apps, see <xref:security/authentication/identity-enable-qrcodes>.
 
-> [!WARNING]
-> An ASP.NET Core TOTP code should be kept secret because it can be used to authenticate successfully multiple times before it expires.
-
-## Scaffold the Enable Authenticator component into the app
-
-Follow the guidance in <xref:security/authentication/scaffold-identity#scaffold-identity-into-a-blazor-project> to scaffold `Pages\Manage\EnableAuthenticator` into the app.
-
-<!-- UPDATE 9.0 Update NOTE per followup on the issue -->
+The guidance in this article relies upon either creating the app with **Individual Accounts** for the new app's **Authentication type** or [scaffolding Identity into an existing app](xref:security/authentication/scaffold-identity#scaffold-identity-into-a-blazor-project). For guidance on using the .NET CLI instead of Visual Studio for scaffolding Identity into an existing app, see <xref:fundamentals/tools/dotnet-aspnet-codegenerator>.
 
-> [!NOTE]
-> Although only the `EnableAuthenticator` component is selected for scaffolding in this example, scaffolding currently adds all of the Identity components to the app. Additionally, exceptions may be thrown during the process of scaffolding into the app. If exceptions occur when database migrations occur, stop the app and restart the app on each exception. For more information, see [Scaffolding exceptions for Blazor Web App (`dotnet/Scaffolding` #2694)](https://github.com/dotnet/Scaffolding/issues/2694).
-
-Be patient while migrations are executed. Depending on the speed of the system, it can take up to a minute or two for database migrations to finish.
-
-For more information, see <xref:security/authentication/scaffold-identity>. For guidance on using the .NET CLI instead of Visual Studio, see <xref:fundamentals/tools/dotnet-aspnet-codegenerator>.
+> [!WARNING]
+> TOTP codes should be kept secret because they can be used to authenticate multiple times before they expire.
 
 ## Adding QR codes to the 2FA configuration page
 
-These instructions use [Shim Sangmin](https://hogangnono.com)'s [qrcode.js: Cross-browser QRCode generator for JavaScript](https://davidshimjs.github.io/qrcodejs/) ([`davidshimjs/qrcodejs` GitHub repository](https://github.com/davidshimjs/qrcodejs)).
-
-Download the [`qrcode.min.js`](https://davidshimjs.github.io/qrcodejs/) library to the `wwwroot` folder of the solution's server project. The library has no dependencies.
-
-In the `App` component (`Components/App.razor`), place a library script reference after [Blazor's `<script>` tag](xref:blazor/project-structure#location-of-the-blazor-script):
+A QR code generated by the app to set up 2FA with an TOTP authenticator app must be generated by a QR code library.
 
-```razor
-<script src="qrcode.min.js"></script>
-```
-
-The `EnableAuthenticator` component, which is part of the QR code system in the app and displays the QR code to users, adopts static server-side rendering (static SSR) with enhanced navigation. Therefore, normal scripts can't execute when the component loads or updates under enhanced navigation. Extra steps are required to trigger the QR code to load in the UI when the page is loaded. To accomplish loading the QR code, the approach explained in <xref:blazor/js-interop/ssr> is adopted.
-
-Add the following [JavaScript initializer](xref:blazor/fundamentals/startup#javascript-initializers) to the server project's `wwwroot` folder. The `{NAME}` placeholder must be the name of the app's assembly in order for Blazor to locate and load the file automatically. If the server app's assembly name is `BlazorSample`, the file is named `BlazorSample.lib.module.js`.
-
-`wwwroot/{NAME}.lib.module.js`:
+The guidance in this article uses [`manuelbl/QrCodeGenerator`](https://github.com/manuelbl/QrCodeGenerator), but you can use any QR code generation library.
 
-[!INCLUDE[](~/blazor/includes/js-interop/blazor-page-script.md)]
+Add a package reference for the [`Net.Codecrete.QrCodeGenerator`](https://www.nuget.org/packages/Net.Codecrete.QrCodeGenerator) NuGet package.
 
-Add the following shared `PageScript` component to the server app.
+[!INCLUDE[](~/includes/package-reference.md)]
 
-`Components/PageScript.razor`:
+Open the `EnableAuthenticator` component in the `Components/Account/Pages/Manage` folder. At the top of the file under the `@page` directive, add an `@using` directive for the QrCodeGenerator namespace:
 
 ```razor
-<page-script src="@Src"></page-script>
-
-@code {
-    [Parameter]
-    [EditorRequired]
-    public string Src { get; set; } = default!;
-}
-```
-
-Add the following [collocated JS file](xref:blazor/js-interop/javascript-location#load-a-script-from-an-external-javascript-file-js-collocated-with-a-component) for the `EnableAuthenticator` component, which is located at `Components/Account/Pages/Manage/EnableAuthenticator.razor`. The `onLoad` function creates the QR code with Sangmin's `qrcode.js` library using the QR code URI produced by the `GenerateQrCodeUri` method in the component's `@code` block.
-
-`Components/Account/Pages/Manage/EnableAuthenticator.razor.js`:
-
-```javascript
-export function onLoad() {
-  const uri = document.getElementById('qrCodeData').getAttribute('data-url');
-  new QRCode(document.getElementById('qrCode'), uri);
-}
+@using Net.Codecrete.QrCodeGenerator
 ```
 
-Under the `<PageTitle>` component in the `EnableAuthenticator` component, add the `PageScript` component with the path to the collocated JS file:
-
-```razor
-<PageScript Src="./Components/Account/Pages/Manage/EnableAuthenticator.razor.js" />
-```
-
-> [!NOTE]
-> An alternative to using the approach with the `PageScript` component is to use an event listener (`blazor.addEventListener("enhancedload", {CALLBACK})`) registered in an [`afterWebStarted` JS initializer](xref:blazor/fundamentals/startup#javascript-initializers) to listen for page updates caused by enhanced navigation. The callback (`{CALLBACK}` placeholder) performs the QR code initialization logic.
->
-> Using the callback approach with `enhancedload`, the code executes for every enhanced navigation, even when the QR code `<div>` isn't rendered. Therefore, additional code must be added to check for the presence of the `<div>` before executing the code that adds a QR code.
-
-
-Delete the `<div>` element that contains the QR code instructions:
+Delete the `<div>` element that contains the QR code instructions and the two `<div>` elements where the QR code should appear and where the QR code data is stored in the page:
 
 ```diff
 - <div class="alert alert-info">
 -     Learn how to <a href="https://go.microsoft.com/fwlink/?Linkid=852423">enable 
 -     QR code generation</a>.
 - </div>
+- <div></div>
+- <div data-url="@authenticatorUri"></div>
 ```
 
-Locate the two `<div>` elements where the QR code should appear and where the QR code data is stored in the page.
+Replace the deleted elements with the following markup:
 
-Make the following changes:
+```razor
+<div>
+    <svg xmlns="http://www.w3.org/2000/svg" height="300" width="300" stroke="none" 
+            version="1.1" viewBox="0 0 50 50">
+        <rect width="300" height="300" fill="#ffffff" />
+        <path d="@svgGraphicsPath" fill="#000000" />
+    </svg>
+</div>
+```
 
-* For the empty `<div>`, give the element an `id` of `qrCode`.
-* For the `<div>` with the `data-url` attribute, give the element an `id` of `qrCodeData`.
+Just inside the opening `@code` block, change the variable declaration for `authenticatorUri` to `svgGraphicsPath`:
 
 ```diff
-- <div></div>
-- <div data-url="@authenticatorUri"></div>
-+ <div id="qrCode"></div>
-+ <div id="qrCodeData" data-url="@authenticatorUri"></div>
+- private string? authenticatorUri;
++ private string? svgGraphicsPath;
 ```
 
-Change the site name in the `GenerateQrCodeUri` method of the `EnableAuthenticator` component. The default value is `Microsoft.AspNetCore.Identity.UI`. Change the value to a meaningful site name that users can identify easily in their authenticator app. Developers usually set a site name that matches the company's name. Examples: Yahoo, Amazon, Etsy, Microsoft, Zoho. We recommend limiting the site name length to 30 characters or less to allow the site name to display on narrow mobile device screens.
+Change the site name in the `GenerateQrCodeUri` method. The default value is `Microsoft.AspNetCore.Identity.UI`. Change the value to a meaningful site name that users can identify easily in their authenticator app. Developers usually set a site name that matches the company's name. We recommend limiting the site name length to 30 characters or less to allow the site name to display on narrow mobile device screens.
 
 In the following example, the default value `Microsoft.AspNetCore.Identity.UI` is changed to the company name `Weyland-Yutani Corporation` (&copy;1986 20th Century Studios [*Aliens*](https://www.20thcenturystudios.com/movies/aliens)).
 
@@ -122,6 +77,20 @@ In the `GenerateQrCodeUri` method:
 + UrlEncoder.Encode("Weyland-Yutani Corporation"),
 ```
 
+At the bottom of the `LoadSharedKeyAndQrCodeUriAsync` method, add the [`var` keyword](/dotnet/csharp/programming-guide/classes-and-structs/implicitly-typed-local-variables) to the line that sets `authenticatorUri`, making it an implicitly-typed local variable:
+
+```diff
+- authenticatorUri = GenerateQrCodeUri(email!, unformattedKey!);
++ var authenticatorUri = GenerateQrCodeUri(email!, unformattedKey!);
+```
+
+Add the following lines of code at the bottom of the `LoadSharedKeyAndQrCodeUriAsync` method:
+
+```csharp
+var qr = QrCode.EncodeText(authenticatorUri, QrCode.Ecc.Medium);
+svgGraphicsPath = qr.ToGraphicsPath();
+```
+
 Run the app and ensure that the QR code is scannable and that the code validates.
 
 > [!WARNING]

aspnetcore/blazor/security/webassembly/standalone-with-identity/account-confirmation-and-password-recovery.md

@@ -4,17 +4,19 @@ author: guardrex
 description: Learn how to configure an ASP.NET Core Blazor WebAssembly app with ASP.NET Core Identity with email confirmation and password recovery.
 ms.author: riande
 monikerRange: '>= aspnetcore-8.0'
-ms.date: 10/31/2024
+ms.date: 11/21/2024
 uid: blazor/security/webassembly/standalone-with-identity/account-confirmation-and-password-recovery
 ---
 # Account confirmation and password recovery in ASP.NET Core Blazor WebAssembly with ASP.NET Core Identity
 
+[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)]
+
 This article explains how to configure an ASP.NET Core Blazor WebAssembly app with ASP.NET Core Identity with email confirmation and password recovery.
 
 > [!NOTE]
 > This article only applies standalone Blazor WebAssembly apps with ASP.NET Core Identity. To implement email confirmation and password recovery for Blazor Web Apps, see <xref:blazor/security/account-confirmation-and-password-recovery>.
 
-## Namespace
+## Namespaces and article code examples
 
 The namespaces used by the examples in this article are:
 
@@ -156,15 +158,11 @@ Locate the line that calls <xref:Microsoft.Extensions.DependencyInjection.Identi
 In the client project's `Register` component (`Components/Identity/Register.razor`), change the message to users on a successful account registration to instruct them to confirm their account. The following example includes a link to trigger Identity on the server to resend the confirmation email.
 
 ```diff
-- <div class="alert alert-success">
--     You successfully registered. Now you can <a href="login">login</a>.
-- </div>
-+ <div class="alert alert-success">
-+     You successfully registered. You must now confirm your account by clicking 
-+     the link in the email that was sent to you. After confirming your account, 
-+     you can <a href="login">login</a> to the app. 
-+     <a href="resendConfirmationEmail">Resend confirmation email</a>
-+ </div>
+- You successfully registered and can <a href="login">login</a> to the app.
++ You successfully registered. You must now confirm your account by clicking 
++ the link in the email that was sent to you. After confirming your account, 
++ you can <a href="login">login</a> to the app. 
++ <a href="resendConfirmationEmail">Resend confirmation email</a>
 ```
 
 ## Update seed data code to confirm seeded accounts
@@ -222,52 +220,33 @@ public Task<FormResult> ResetPasswordAsync(string email, string resetCode,
 In the client project, add implementations for the preceding methods in the `CookieAuthenticationStateProvider` class (`Identity/CookieAuthenticationStateProvider.cs`):
 
 ```csharp
-/// <summary>
-/// Begin the password recovery process by issuing a POST request to the 
-/// '/forgotPassword' endpoint.
-/// </summary>
-/// <param name="email">The user's email address.</param>
-/// <returns>A <see cref="bool"/> indicating success or failure.</returns>
 public async Task<bool> ForgotPasswordAsync(string email)
 {
     try
     {
-        // make the request
         var result = await httpClient.PostAsJsonAsync(
             "forgotPassword", new
             {
                 email
             });
 
-        // successful?
         if (result.IsSuccessStatusCode)
         {
             return true;
         }
     }
     catch { }
 
-    // unknown error
     return false;
 }
 
-/// <summary>
-/// Reset the user's password by issuing a POST request to the 
-/// '/resetPassword' endpoint.
-/// </summary>
-/// <param name="email">The user's email address.</param>
-/// <param name="resetCode">The user's reset code.</param>
-/// <param name="newPassword">The user's new password.</param>
-/// <returns>The result serialized to a <see cref="FormResult"/>.
-/// </returns>
 public async Task<FormResult> ResetPasswordAsync(string email, string resetCode, 
     string newPassword)
 {
     string[] defaultDetail = ["An unknown error prevented resetting the password."];
 
     try
     {
-        // make the request
         var result = await httpClient.PostAsJsonAsync(
             "resetPassword", new
             {
@@ -276,13 +255,11 @@ public async Task<FormResult> ResetPasswordAsync(string email, string resetCode,
                 newPassword
             });
 
-        // successful?
         if (result.IsSuccessStatusCode)
         {
             return new FormResult { Succeeded = true };
         }
 
-        // body should contain details about why it failed
         var details = await result.Content.ReadAsStringAsync();
         var problemDetails = JsonDocument.Parse(details);
         var errors = new List<string>();
@@ -303,7 +280,6 @@ public async Task<FormResult> ResetPasswordAsync(string email, string resetCode,
             }
         }
 
-        // return the error list
         return new FormResult
         {
             Succeeded = false,
@@ -312,7 +288,6 @@ public async Task<FormResult> ResetPasswordAsync(string email, string resetCode,
     }
     catch { }
 
-    // unknown error
     return new FormResult
     {
         Succeeded = false,
@@ -323,9 +298,6 @@ public async Task<FormResult> ResetPasswordAsync(string email, string resetCode,
 
 In the client project, add the following `ForgotPassword` component.
 
-> [!NOTE]
-> Code lines in the following example are broken across two or more lines to eliminate or reduce horizontal scrolling in this article, but you can place the following code as shown into a test app. The code executes regardless of the artificial line breaks.
-
 `Components/Identity/ForgotPassword.razor`:
 
 ```razor
@@ -344,14 +316,15 @@ In the client project, add the following `ForgotPassword` component.
         @if (!passwordResetCodeSent)
         {
             <EditForm Model="Input" FormName="forgot-password" 
-                OnValidSubmit="OnValidSubmitStep1Async" method="post">
+                      OnValidSubmit="OnValidSubmitStep1Async" method="post">
                 <DataAnnotationsValidator />
                 <ValidationSummary class="text-danger" role="alert" />
 
                 <div class="form-floating mb-3">
-                    <InputText @bind-Value="Input.Email" id="Input.Email" 
-                        class="form-control" autocomplete="username" 
-                        aria-required="true" placeholder="[email protected]" />
+                    <InputText @bind-Value="Input.Email" 
+                        id="Input.Email" class="form-control" 
+                        autocomplete="username" aria-required="true" 
+                        placeholder="[email protected]" />
                     <label for="Input.Email" class="form-label">
                         Email
                     </label>
@@ -415,7 +388,8 @@ In the client project, add the following `ForgotPassword` component.
                             class="text-danger" />
                     </div>
                     <div class="form-floating mb-3">
-                        <InputText type="password" @bind-Value="Reset.ConfirmPassword" 
+                        <InputText type="password" 
+                            @bind-Value="Reset.ConfirmPassword" 
                             id="Reset.ConfirmPassword" class="form-control" 
                             autocomplete="new-password" aria-required="true" 
                             placeholder="password" />
@@ -435,8 +409,7 @@ In the client project, add the following `ForgotPassword` component.
 </div>
 
 @code {
-    private bool passwordResetCodeSent;
-    private bool passwordResetSuccess, errors;
+    private bool passwordResetCodeSent, passwordResetSuccess, errors;
     private string[] errorList = [];
 
     [SupplyParameterFromForm(FormName = "forgot-password")]
@@ -490,7 +463,7 @@ In the client project, add the following `ForgotPassword` component.
         [DataType(DataType.Password)]
         [Display(Name = "Confirm password")]
         [Compare("NewPassword", ErrorMessage = "The new password and confirmation " +
-            "password do not match.")]
+            "password don't match.")]
         public string ConfirmPassword { get; set; } = string.Empty;
     }
 }