Updates

Author: guardrex

aspnetcore/blazor/components/httpcontext.md

@@ -16,9 +16,9 @@ uid: blazor/components/httpcontext
 
 <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> generally should be avoided with interactive rendering because a valid <xref:Microsoft.AspNetCore.Http.HttpContext> isn't always available.
 
-<xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> can be used for components that are statically rendered on the server. **However, we recommend avoiding it if possible.** A valid use case for using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> during static server-side rendering is to [pass tokens to a server-side app](xref:blazor/security/additional-scenarios#pass-tokens-to-a-server-side-blazor-app).
+<xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> can be used for components that are statically rendered on the server. **However, we recommend avoiding it if possible.** A valid use case for using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> during static server-side rendering (static SSR) is to [pass tokens to a server-side app](xref:blazor/security/additional-scenarios#pass-tokens-to-a-server-side-blazor-app).
 
-<xref:Microsoft.AspNetCore.Http.HttpContext> can be used as a [cascading parameter](xref:Microsoft.AspNetCore.Components.CascadingParameterAttribute) only in *statically-rendered root components* for general tasks, such as inspecting and modifying headers or other properties in the `App` component (`Components/App.razor`). The value is always `null` for interactive rendering.
+<xref:Microsoft.AspNetCore.Http.HttpContext> can be used as a [cascading parameter](xref:Microsoft.AspNetCore.Components.CascadingParameterAttribute) only in *statically-rendered root components* or during static server-side rendering (static SSR) for general tasks, such as inspecting and modifying headers or other properties in the `App` component (`Components/App.razor`). The value is always `null` for interactive rendering.
 
 ```csharp
 [CascadingParameter]
@@ -30,7 +30,7 @@ For additional context in *advanced* edge cases&dagger;, see the discussion in t
 * [HttpContext is valid in Interactive Server Rendering Blazor page (`dotnet/AspNetCore.Docs` #34301)](https://github.com/dotnet/AspNetCore.Docs/issues/34301)
 * [Security implications of using IHttpContextAccessor in Blazor Server (`dotnet/aspnetcore` #45699)](https://github.com/dotnet/aspnetcore/issues/45699)
 
-&dagger;Most developers building and maintaining Blazor apps don't need to delve into advanced concepts when the general guidance in this article is followed.
+&dagger;Most developers building and maintaining Blazor apps don't need to delve into advanced concepts when the general guidance in this article is followed. The most important concept to keep in mind is that <xref:Microsoft.AspNetCore.Http.HttpContext> is fundamentally a server-based, request-response feature that is only generally available on the server during static SSR and only created when a user's circuit is established.
 
 :::moniker-end
 

aspnetcore/blazor/fundamentals/index.md

@@ -188,7 +188,7 @@ Samples apps in the repository:
 * Blazor Web App Movies tutorial sample (<xref:blazor/tutorials/movie-database-app/index>)
 * Blazor Web App with SignalR (<xref:blazor/tutorials/signalr-blazor>)
 * Two Blazor Web Apps and a Blazor WebAssembly app for calling web (server) APIs (<xref:blazor/call-web-api>)
-* Blazor Web App with OIDC (BFF and non-BFF patterns) (<xref:blazor/security/blazor-web-app-oidc>)
+* Blazor Web App with OIDC (<xref:blazor/security/blazor-web-app-oidc>)
 * Blazor Web App with Entra (<xref:blazor/security/blazor-web-app-entra>)
 * Blazor WebAssembly scopes-enabled logging (<xref:blazor/fundamentals/logging#client-side-log-scopes>)
 * Blazor WebAssembly with ASP.NET Core Identity (<xref:blazor/security/webassembly/standalone-with-identity/index>)

aspnetcore/blazor/security/additional-scenarios.md

@@ -23,27 +23,28 @@ This article explains how to configure server-side Blazor for additional securit
 
 *This section applies to Blazor Web Apps. For Blazor Server, view the [7.0 version of this article section](xref:blazor/security/additional-scenarios?view=aspnetcore-7.0&preserve-view=true#pass-tokens-to-a-server-side-blazor-app).*
 
-Tokens available outside of the Razor components in a Blazor Web App can be passed to interactive components with the approaches described in this section. The examples in this section focus on passing access tokens, but the approach is valid for other HTTP context state provided by <xref:Microsoft.AspNetCore.Http.HttpContext>.
+Tokens available outside of the Razor components in a Blazor Web App can be passed to interactive components with the approaches described in this section. The examples in this section focus on passing JWT access tokens for secure web API access, but the approaches are valid for other HTTP context state provided by <xref:Microsoft.AspNetCore.Http.HttpContext>.
 
-For a demonstration of the guidance in this section, see the following sample apps in the [Blazor samples]() repository:
+### Sample app demonstration
 
+For a demonstration of the guidance in this section, see the `BlazorWebAppOidcServer` sample app (.NET 8 or later) in the [Blazor samples](https://github.com/dotnet/blazor-samples) repository. The sample is a Blazor Web App with global Interactive Server interactivity that uses OIDC authentication with Microsoft Entra without using Entra-specific packages. The sample demonstrates how to pass a JWT access token to call a secure web API.
 
-
-> [!NOTE]
-> Passing the [anti-request forgery (CSRF/XSRF) token](xref:security/anti-request-forgery) to Razor components is useful in scenarios where components POST to Identity or other endpoints that require validation. However, don't follow the guidance in this section for processing form POST requests or web API requests with XSRF support. The Blazor framework provides built-in antiforgery support for forms and calling web APIs. For more information, see the following resources:
->
-> * General support for antiforgery: <xref:blazor/security/index#antiforgery-support>
-> * Antiforgery support for forms: <xref:blazor/forms/index#antiforgery-support>
-> * Antiforgery support for web API: <xref:blazor/call-web-api#antiforgery-support>
+### Reading tokens from `HttpContext`
 
 Reading tokens from the <xref:Microsoft.AspNetCore.Http.HttpContext> using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> is a reasonable approach for obtaining tokens during interactive server rendering. However, tokens aren't updated if the user authenticates after the circuit is established, since the <xref:Microsoft.AspNetCore.Http.HttpContext> is captured at the start of the SignalR connection. Also, the use of <xref:System.Threading.AsyncLocal%601> by <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> means that you must be careful not to lose the execution context before reading the <xref:Microsoft.AspNetCore.Http.HttpContext>.
 
-The following approach is aimed at attaching a user's access token to outgoing requests, specifically to make web API calls to separate web API apps. The approach is shown for a Blazor Web App that adopts global Interactive Server rendering, but the same general approach applies to Blazor Web Apps that adopt the global Interactive Auto render mode. The critical concern is that any attempt to access the <xref:Microsoft.AspNetCore.Http.HttpContext> using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> is only performed during static SSR.
+Also keep in mind that <xref:Microsoft.AspNetCore.Http.HttpContext> used as a [cascading parameter](xref:Microsoft.AspNetCore.Components.CascadingParameterAttribute) is only populated in statically-rendered root components or during static server-side component rendering (static SSR), which limits the usefulness of supplying <xref:Microsoft.AspNetCore.Http.HttpContext> as a cascading parameter when trying to pass tokens and other properties.
+
+For more information, see <xref:blazor/components/httpcontext>.
+
+### Example
+
+The following approach is aimed at attaching a user's access token to outgoing requests, specifically to make web API calls to separate web API apps. The approach is shown for a Blazor Web App that adopts global Interactive Server rendering, but the same general approach applies to Blazor Web Apps that adopt the global Interactive Auto render mode. The important concept to keep in mind is that accessing the <xref:Microsoft.AspNetCore.Http.HttpContext> using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> is only performed during static server-side rendering (static SSR).
 
 > [!NOTE]
-> [Microsoft identity platform](/entra/identity-platform/)/[Microsoft Identity Web packages](/entra/msal/dotnet/microsoft-identity-web/) for [Microsoft Entra ID](https://www.microsoft.com/security/business/microsoft-entra) provides a simple API to call web APIs from Blazor Web Apps. For more information, see <xref:blazor/security/blazor-web-app-entra> and the `BlazorWebAppEntra` sample app in the [Blazor samples GitHub repository](https://github.com/dotnet/blazor-samples) for .NET 9 or later (`9.0` sample folder or later in the repository).
+> [Microsoft identity platform](/entra/identity-platform/)/[Microsoft Identity Web packages](/entra/msal/dotnet/microsoft-identity-web/) for [Microsoft Entra ID](https://www.microsoft.com/security/business/microsoft-entra) provides a simple API to call web APIs from Blazor Web Apps. For more information, see <xref:blazor/security/blazor-web-app-entra> and the `BlazorWebAppEntra` and `BlazorWebAppEntraBff` sample apps (.NET 9 or later) in the [Blazor samples GitHub repository](https://github.com/dotnet/blazor-samples).
 
-Subclass <xref:System.Net.Http.DelegatingHandler> to attach a user's access token to outgoing requests. The token handler only executes during static server-side rendering (static SSR), so using <xref:Microsoft.AspNetCore.Http.HttpContext> is safe in this scenario.
+Subclass <xref:System.Net.Http.DelegatingHandler> to attach a user's access token to outgoing requests. The token handler only executes during static SSR, so using <xref:Microsoft.AspNetCore.Http.HttpContext> is safe in this scenario.
 
 `TokenHandler.cs`:
 
@@ -83,23 +84,53 @@ builder.Services.AddHttpClient("{HTTP CLIENT NAME}",
       .AddHttpMessageHandler<TokenHandler>();
 ```
 
-> [!NOTE]
-> You can supply the HTTP client base address from [configuration](xref:blazor/fundamentals/configuration) with `builder.Configuration["{CONFIGURATION KEY}"]`, where the `{CONFIGURATION KEY}` placeholder is the configuration key.
+Example:
+
+```csharp
+builder.Services.AddScoped<TokenHandler>();
+
+builder.Services.AddHttpClient("ExternalApi",
+      client => client.BaseAddress = new Uri("https://localhost:7277"))
+      .AddHttpMessageHandler<TokenHandler>();
+```
+
+You can supply the HTTP client base address from [configuration](xref:blazor/fundamentals/configuration) with `builder.Configuration["{CONFIGURATION KEY}"]`, where the `{CONFIGURATION KEY}` placeholder is the configuration key:
+
+```csharp
+new Uri(builder.Configuration["ExternalApiUri"] ?? throw new IOException("..."))
+```
+
+In `appsettings.json`:
+
+```json
+"ExternalApiUri": "https://localhost:7277"
+```
 
 An <xref:System.Net.Http.HttpClient> created by a component can make secure web API requests. In the following example, the `{REQUEST URI}` is the relative request URI, and the `{HTTP CLIENT NAME}` placeholder is the name of the <xref:System.Net.Http.HttpClient>:
 
 ```csharp
 var request = new HttpRequestMessage(HttpMethod.Get, "{REQUEST URI}");
 var client = ClientFactory.CreateClient("{HTTP CLIENT NAME}");
+var response = await client.SendAsync(request);
+```
+
+Example:
 
+```csharp
+var request = new HttpRequestMessage(HttpMethod.Get, "/weather-forecast");
+var client = ClientFactory.CreateClient("ExternalApi");
 var response = await client.SendAsync(request);
 ```
 
-### Blazor Web App that adopts global Interactive Auto rendering
+Additional features are planned for Blazor, which are tracked by [Access `AuthenticationStateProvider` in outgoing request middleware (`dotnet/aspnetcore` #52379)](https://github.com/dotnet/aspnetcore/issues/52379). [Problem providing Access Token to HttpClient in Interactive Server mode (`dotnet/aspnetcore` #52390)](https://github.com/dotnet/aspnetcore/issues/52390) is a closed issue that contains helpful discussion and potential workaround strategies for advanced use cases.
 
+### Passing the anti-request forgery (CSRF/XSRF) token
 
+Passing the [anti-request forgery (CSRF/XSRF) token](xref:security/anti-request-forgery) to Razor components is useful in scenarios where components POST to Identity or other endpoints that require validation. However, don't follow the guidance in this section for processing form POST requests or web API requests with XSRF support. The Blazor framework provides built-in antiforgery support for forms and calling web APIs. For more information, see the following resources:
 
-Additional features are planned for Blazor, which is tracked by [Access `AuthenticationStateProvider` in outgoing request middleware (`dotnet/aspnetcore` #52379)](https://github.com/dotnet/aspnetcore/issues/52379), which will probably be addressed for .NET 11 (late 2026). [Problem providing Access Token to HttpClient in Interactive Server mode (`dotnet/aspnetcore` #52390)](https://github.com/dotnet/aspnetcore/issues/52390) is a closed issue that contains helpful discussion and potential workaround strategies for advanced use cases.
+* General support for antiforgery: <xref:blazor/security/index#antiforgery-support>
+* Antiforgery support for forms: <xref:blazor/forms/index#antiforgery-support>
+* Antiforgery support for web API: <xref:blazor/call-web-api#antiforgery-support>
 
 :::moniker-end