Blazor WASM security updates for 5.0 (#20138)

Author: guardrex

aspnetcore/blazor/debug.md

@@ -77,7 +77,7 @@ To debug a Blazor WebAssembly app in Visual Studio:
    > [!NOTE]
    > **Start Without Debugging** (<kbd>Ctrl</kbd>+<kbd>F5</kbd>) isn't supported. When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.
 
-1. In the *Client* app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
+1. In the `*Client*` app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
 1. In the browser, navigate to `Counter` page and select the **Click me** button to hit the breakpoint.
 1. In Visual Studio, inspect the value of the `currentCount` field in the **Locals** window.
 1. Press <kbd>F5</kbd> to continue execution.
@@ -164,7 +164,7 @@ For information on using a custom app base path for Blazor WebAssembly apps, see
 
 1. The standalone app is launched, and a debugging browser is opened.
 
-1. In the *Client* app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
+1. In the `*Client*` app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
 
 1. In the browser, navigate to `Counter` page and select the **Click me** button to hit the breakpoint.
 
@@ -269,7 +269,7 @@ To debug a Blazor WebAssembly app in Visual Studio for Mac:
    > [!IMPORTANT]
    > Google Chrome or Microsoft Edge must be the selected browser for the debugging session.
 
-1. In the *Client* app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
+1. In the `*Client*` app, set a breakpoint on the `currentCount++;` line in `Pages/Counter.razor`.
 1. In the browser, navigate to `Counter` page and select the **Click me** button to hit the breakpoint:
 1. In Visual Studio, inspect the value of the `currentCount` field in the **Locals** window.
 1. Press <kbd>&#8984;</kbd>+<kbd>&#8617;</kbd> to continue execution.

aspnetcore/blazor/security/webassembly/additional-scenarios.md

@@ -161,7 +161,7 @@ For a Blazor app based on the Blazor WebAssembly Hosted project template, <xref:
 
 ### Graph API example
 
-In the following example, a named <xref:System.Net.Http.HttpClient> for Graph API is used to obtain a user's mobile phone number to process a call. After adding the Microsoft Graph API `User.Read` permission in the AAD area of the Azure portal, the scope is configured for the named client in the standalone app or Client app of a hosted Blazor solution.
+In the following example, a named <xref:System.Net.Http.HttpClient> for Graph API is used to obtain a user's mobile phone number to process a call. After adding the Microsoft Graph API `User.Read` permission in the AAD area of the Azure portal, the scope is configured for the named client in the standalone app or *`Client`* app of a hosted Blazor solution.
 
 > [!NOTE]
 > The example in this section obtains Graph API data for the user in *component code*. To create user claims from Graph API, see the following resources:
@@ -1054,7 +1054,7 @@ After following the guidance in one of the hosted Blazor WebAssembly app topics,
 * Prerenders paths for which authorization isn't required.
 * Doesn't prerender paths for which authorization is required.
 
-In the Client app's `Program` class (`Program.cs`), factor common service registrations into a separate method (for example, `ConfigureCommonServices`):
+In the *`Client`* app's `Program` class (`Program.cs`), factor common service registrations into a separate method (for example, `ConfigureCommonServices`):
 
 ```csharp
 public class Program
@@ -1114,7 +1114,7 @@ app.UseEndpoints(endpoints =>
 });
 ```
 
-In the server app, create a `Pages` folder if it doesn't exist. Create a `_Host.cshtml` page inside the server app's `Pages` folder. Paste the contents from the Client app's `wwwroot/index.html` file into the `Pages/_Host.cshtml` file. Update the file's contents:
+In the server app, create a `Pages` folder if it doesn't exist. Create a `_Host.cshtml` page inside the server app's `Pages` folder. Paste the contents from the *`Client`* app's `wwwroot/index.html` file into the `Pages/_Host.cshtml` file. Update the file's contents:
 
 * Add `@page "_Host"` to the top of the file.
 * Replace the `<app>Loading...</app>` tag with the following:

aspnetcore/blazor/security/webassembly/azure-active-directory-groups-and-roles.md

@@ -33,7 +33,7 @@ The guidance in this article applies to the Blazor WebAssembly AAD deployment sc
 
 A [Microsoft Graph API](/graph/use-the-api) call is required for any app user with more than five AAD Administrator role and security group memberships.
 
-To permit Graph API calls, give the standalone or client app of a hosted Blazor solution any of the following [Graph API permissions](/graph/permissions-reference) in the Azure portal:
+To permit Graph API calls, give the standalone or *`Client`* app of a hosted Blazor solution any of the following [Graph API permissions](/graph/permissions-reference) in the Azure portal:
 
 * `Directory.Read.All`
 * `Directory.ReadWrite.All`
@@ -72,7 +72,7 @@ public class CustomUserAccount : RemoteUserAccount
 }
 ```
 
-In the standalone app or the client app of a hosted Blazor solution, create a custom <xref:Microsoft.AspNetCore.Components.WebAssembly.Authentication.AuthorizationMessageHandler> class. Use the correct scope (permission) for Graph API calls that obtain role and group information.
+In the standalone app or the *`Client`* app of a hosted Blazor solution, create a custom <xref:Microsoft.AspNetCore.Components.WebAssembly.Authentication.AuthorizationMessageHandler> class. Use the correct scope (permission) for Graph API calls that obtain role and group information.
 
 `GraphAPIAuthorizationMessageHandler.cs`:
 
@@ -234,7 +234,7 @@ There's no need to provide code to remove the original `groups` claim, if presen
 >
 > General coverage for this approach is found in the <xref:blazor/security/webassembly/additional-scenarios#custom-authorizationmessagehandler-class> article.
 
-Register the factory in `Program.Main` (`Program.cs`) of the standalone app or client app of a hosted Blazor solution. Consent to the `Directory.Read.All` permission scope as an additional scope for the app:
+Register the factory in `Program.Main` (`Program.cs`) of the standalone app or *`Client`* app of a hosted Blazor solution. Consent to the `Directory.Read.All` permission scope as an additional scope for the app:
 
 ```csharp
 builder.Services.AddMsalAuthentication<RemoteAuthenticationState, 
@@ -635,9 +635,9 @@ The following example assumes that an app is configured with two roles:
 
 The single `roles` claim sent by AAD presents the user-defined roles as the `appRoles`'s `value`s in a JSON array. The app must convert the JSON array of roles into individual `role` claims.
 
-The `CustomUserFactory` shown in the [User-defined groups and AAD Administrator Roles](#user-defined-groups-and-administrator-roles) section is set up to act on a `roles` claim with a JSON array value. Add and register the `CustomUserFactory` in the standalone app or client app of a hosted Blazor solution as shown in the [User-defined groups and AAD Administrator Roles](#user-defined-groups-and-administrator-roles) section. There's no need to provide code to remove the original `roles` claim because it's automatically removed by the framework.
+The `CustomUserFactory` shown in the [User-defined groups and AAD Administrator Roles](#user-defined-groups-and-administrator-roles) section is set up to act on a `roles` claim with a JSON array value. Add and register the `CustomUserFactory` in the standalone app or *`Client`* app of a hosted Blazor solution as shown in the [User-defined groups and AAD Administrator Roles](#user-defined-groups-and-administrator-roles) section. There's no need to provide code to remove the original `roles` claim because it's automatically removed by the framework.
 
-In `Program.Main` of the standalone app or client app of a hosted Blazor solution, specify the claim named "`role`" as the role claim:
+In `Program.Main` of the standalone app or *`Client`* app of a hosted Blazor solution, specify the claim named "`role`" as the role claim:
 
 ```csharp
 builder.Services.AddMsalAuthentication(options =>

aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md

@@ -31,7 +31,7 @@ Follow the guidance in [Tutorial: Register an application in Azure Active Direct
 1. Provide a **Name** for the app (for example, **Blazor Server AAD B2C**).
 1. For **Supported account types**, select the multi-tenant option: **Accounts in any organizational directory or any identity provider. For authenticating users with Azure AD B2C.**
 1. The *Server API app* doesn't require a **Redirect URI** in this scenario, so leave the drop down set to **Web** and don't enter a redirect URI.
-1. Confirm that **Permissions** > **Grant admin consent to openid and offline_access permissions** is enabled.
+1. Confirm that **Permissions** > **Grant admin consent to openid and offline_access permissions** is selected.
 1. Select **Register**.
 
 Record the following information:
@@ -58,13 +58,35 @@ The App ID URI might require a special configuration in the client app, which is
 
 ### Register a client app
 
-Follow the guidance in [Tutorial: Register an application in Azure Active Directory B2C](/azure/active-directory-b2c/tutorial-register-applications) again to register an AAD app for the *Client app* and then do the following:
+Follow the guidance in [Tutorial: Register an application in Azure Active Directory B2C](/azure/active-directory-b2c/tutorial-register-applications) again to register an AAD app for the *`Client`* app and then do the following:
+
+::: moniker range=">= aspnetcore-5.0"
 
 1. In **Azure Active Directory** > **App registrations**, select **New registration**.
 1. Provide a **Name** for the app (for example, **Blazor Client AAD B2C**).
 1. For **Supported account types**, select the multi-tenant option: **Accounts in any organizational directory or any identity provider. For authenticating users with Azure AD B2C.**
-1. Leave the **Redirect URI** drop down set to **Web** and provide the following redirect URI: `https://localhost:{PORT}/authentication/login-callback`. The default port for an app running on Kestrel is 5001. If the app is run on a different Kestrel port, use the app's port. For IIS Express, the randomly generated port for the app can be found in the Server app's properties in the **Debug** panel. Since the app doesn't exist at this point and the IIS Express port isn't known, return to this step after the app is created and update the redirect URI. A remark appears in the [Create the app](#create-the-app) section to remind IIS Express users to update the redirect URI.
-1. Confirm that **Permissions** > **Grant admin consent to openid and offline_access permissions** is enabled.
+1. Set the **Redirect URI** drop down to **Single-page application (SPA)** and provide the following redirect URI: `https://localhost:{PORT}/authentication/login-callback`. The default port for an app running on Kestrel is 5001. If the app is run on a different Kestrel port, use the app's port. For IIS Express, the randomly generated port for the app can be found in the *`Server`* app's properties in the **Debug** panel. Since the app doesn't exist at this point and the IIS Express port isn't known, return to this step after the app is created and update the redirect URI. A remark appears in the [Create the app](#create-the-app) section to remind IIS Express users to update the redirect URI.
+1. Confirm that **Permissions** > **Grant admin consent to openid and offline_access permissions** is selected.
+1. Select **Register**.
+
+1. Record the Application (client) ID (for example, `4369008b-21fa-427c-abaa-9b53bf58e538`).
+
+In **Authentication** > **Platform configurations** > **Single-page application (SPA)**:
+
+1. Confirm the **Redirect URI** of `https://localhost:{PORT}/authentication/login-callback` is present.
+1. For **Implicit grant**, ensure that the check boxes for **Access tokens** and **ID tokens** are **not** selected.
+1. The remaining defaults for the app are acceptable for this experience.
+1. Select the **Save** button.
+
+::: moniker-end
+
+::: moniker range="< aspnetcore-5.0"
+
+1. In **Azure Active Directory** > **App registrations**, select **New registration**.
+1. Provide a **Name** for the app (for example, **Blazor Client AAD B2C**).
+1. For **Supported account types**, select the multi-tenant option: **Accounts in any organizational directory or any identity provider. For authenticating users with Azure AD B2C.**
+1. Leave the **Redirect URI** drop down set to **Web** and provide the following redirect URI: `https://localhost:{PORT}/authentication/login-callback`. The default port for an app running on Kestrel is 5001. If the app is run on a different Kestrel port, use the app's port. For IIS Express, the randomly generated port for the app can be found in the *`Server`* app's properties in the **Debug** panel. Since the app doesn't exist at this point and the IIS Express port isn't known, return to this step after the app is created and update the redirect URI. A remark appears in the [Create the app](#create-the-app) section to remind IIS Express users to update the redirect URI.
+1. Confirm that **Permissions** > **Grant admin consent to openid and offline_access permissions** is selected.
 1. Select **Register**.
 
 Record the Application (client) ID (for example, `4369008b-21fa-427c-abaa-9b53bf58e538`).
@@ -76,6 +98,8 @@ In **Authentication** > **Platform configurations** > **Web**:
 1. The remaining defaults for the app are acceptable for this experience.
 1. Select the **Save** button.
 
+::: moniker-end
+
 In **API permissions**:
 
 1. Select **Add a permission** followed by **My APIs**.
@@ -105,7 +129,7 @@ dotnet new blazorwasm -au IndividualB2C --aad-b2c-instance "{AAD B2C INSTANCE}"
 | ----------------------------- | ----------------------------------------------------- | -------------------------------------- |
 | `{AAD B2C INSTANCE}`          | Instance                                              | `https://contoso.b2clogin.com/`        |
 | `{APP NAME}`                  | &mdash;                                               | `BlazorSample`                         |
-| `{CLIENT APP CLIENT ID}`      | Application (client) ID for the *Client app*          | `4369008b-21fa-427c-abaa-9b53bf58e538` |
+| `{CLIENT APP CLIENT ID}`      | Application (client) ID for the *`Client`* app          | `4369008b-21fa-427c-abaa-9b53bf58e538` |
 | `{DEFAULT SCOPE}`             | Scope name                                            | `API.Access`                           |
 | `{SERVER API APP CLIENT ID}`  | Application (client) ID for the *Server API app*      | `41451fa7-82d9-4673-8fa5-69eff5a761fd` |
 | `{SERVER API APP ID URI}`     | Application ID URI ([see note](#access-token-scopes)) | `41451fa7-82d9-4673-8fa5-69eff5a761fd` |
@@ -117,16 +141,22 @@ The output location specified with the `-o|--output` option creates a project fo
 > [!NOTE]
 > Pass the App ID URI to the `app-id-uri` option, but note a configuration change might be required in the client app, which is described in the [Access token scopes](#access-token-scopes) section.
 >
-> Additionally, the scope set up by the Hosted Blazor template might have the App ID URI host repeated. Confirm that the scope configured for the `DefaultAccessTokenScopes` collection is correct in `Program.Main` (`Program.cs`) of the *Client app*.
+> Additionally, the scope set up by the Hosted Blazor template might have the App ID URI host repeated. Confirm that the scope configured for the `DefaultAccessTokenScopes` collection is correct in `Program.Main` (`Program.cs`) of the *`Client`* app.
+
+::: moniker range=">= aspnetcore-5.0"
+
+[!INCLUDE[](~/includes/blazor-security/additional-scopes-hosted-nonAAD.md)]
+
+::: moniker-end
 
 > [!NOTE]
-> In the Azure portal, the *Client app's* **Authentication** > **Platform configurations** > **Web** > **Redirect URI** is configured for port 5001 for apps that run on the Kestrel server with default settings.
+> In the Azure portal, the *`Client`* app's platform configuration **Redirect URI** is configured for port 5001 for apps that run on the Kestrel server with default settings.
 >
-> If the *Client app* is run on a random IIS Express port, the port for the app can be found in the *Server API app's* properties in the **Debug** panel.
+> If the *`Client`* app is run on a random IIS Express port, the port for the app can be found in the *Server API app's* properties in the **Debug** panel.
 >
-> If the port wasn't configured earlier with the *Client app's* known port, return to the *Client app's* registration in the Azure portal and update the redirect URI with the correct port.
+> If the port wasn't configured earlier with the *`Client`* app's known port, return to the *`Client`* app's registration in the Azure portal and update the redirect URI with the correct port.
 
-## Server app configuration
+## *`Server`* app configuration
 
 *This section pertains to the solution's **`Server`** app.*
 
@@ -227,7 +257,7 @@ public class WeatherForecastController : ControllerBase
 }
 ```
 
-## Client app configuration
+## *`Client`* app configuration
 
 *This section pertains to the solution's **`Client`** app.*
 
@@ -318,6 +348,12 @@ builder.Services.AddMsalAuthentication(options =>
 });
 ```
 
+Specify additional scopes with `AdditionalScopesToConsent`:
+
+```csharp
+options.ProviderOptions.AdditionalScopesToConsent.Add("{ADDITIONAL SCOPE URI}");
+```
+
 [!INCLUDE[](~/includes/blazor-security/azure-scope.md)]
 
 For more information, see the following sections of the *Additional scenarios* article: