From 84d323f7760ca2d1ec5c4340ec38fd3cba58a176 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Thu, 29 Feb 2024 11:26:23 -0500 Subject: [PATCH] Blazor troubleshooting guidance updates (#31937) --- .../security/includes/troubleshoot-server.md | 143 ++++++++++++++++++ .../{troubleshoot.md => troubleshoot-wasm.md} | 10 +- .../server/blazor-web-app-with-oidc.md | 4 + .../hosted-with-azure-active-directory-b2c.md | 2 +- .../hosted-with-identity-server.md | 2 +- .../hosted-with-microsoft-entra-id.md | 2 +- .../standalone-with-authentication-library.md | 2 +- ...ndalone-with-azure-active-directory-b2c.md | 2 +- .../standalone-with-microsoft-accounts.md | 2 +- .../standalone-with-microsoft-entra-id.md | 2 +- 10 files changed, 158 insertions(+), 13 deletions(-) create mode 100644 aspnetcore/blazor/security/includes/troubleshoot-server.md rename aspnetcore/blazor/security/includes/{troubleshoot.md => troubleshoot-wasm.md} (92%) diff --git a/aspnetcore/blazor/security/includes/troubleshoot-server.md b/aspnetcore/blazor/security/includes/troubleshoot-server.md new file mode 100644 index 000000000000..0ec5c40d2a9a --- /dev/null +++ b/aspnetcore/blazor/security/includes/troubleshoot-server.md @@ -0,0 +1,143 @@ +### Logging + +The server app is a standard ASP.NET Core app. See the [ASP.NET Core logging guidance](xref:fundamentals/logging/index) to enable a lower logging level in the server app. + +To enable debug or trace logging for Blazor WebAssembly authentication, see the *Client-side authentication logging* section of with the article version selector set to ASP.NET Core 7.0 or later. + +### Common errors + +* Misconfiguration of the app or Identity Provider (IP) + + The most common errors are caused by incorrect configuration. The following are a few examples: + + * Depending on the requirements of the scenario, a missing or incorrect Authority, Instance, Tenant ID, Tenant domain, Client ID, or Redirect URI prevents an app from authenticating clients. + * Incorrect request scopes prevent clients from accessing server web API endpoints. + * Incorrect or missing server API permissions prevent clients from accessing server web API endpoints. + * Running the app at a different port than is configured in the Redirect URI of the IP's app registration. Note that a port isn't required for Microsoft Entra ID and an app running at a `localhost` development testing address, but the app's port configuration and the port where the app is running must match for non-`localhost` addresses. + + Configuration coverage in this article shows examples of the correct configuration. Carefully check the configuration looking for app and IP misconfiguration. + + If the configuration appears correct: + + * Analyze application logs. + * Examine the network traffic between the client app and the IP or server app with the browser's developer tools. Often, an exact error message or a message with a clue to what's causing the problem is returned to the client by the IP or server app after making a request. Developer tools guidance is found in the following articles: + + * [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/network) (Google documentation) + * [Microsoft Edge](/microsoft-edge/devtools-guide-chromium/network/) + * [Mozilla Firefox](https://developer.mozilla.org/docs/Tools/Network_Monitor) (Mozilla documentation) + + The documentation team responds to document feedback and bugs in articles (open an issue from the **This page** feedback section) but is unable to provide product support. Several public support forums are available to assist with troubleshooting an app. We recommend the following: + + * [Stack Overflow (tag: `blazor`)](https://stackoverflow.com/questions/tagged/blazor) + * [ASP.NET Core Slack Team](https://join.slack.com/t/aspnetcore/shared_invite/zt-1mv5487zb-EOZxJ1iqb0A0ajowEbxByQ) + * [Blazor Gitter](https://gitter.im/aspnet/Blazor) + + *The preceding forums are not owned or controlled by Microsoft.* + + For non-security, non-sensitive, and non-confidential reproducible framework bug reports, [open an issue with the ASP.NET Core product unit](https://github.com/dotnet/aspnetcore/issues). Don't open an issue with the product unit until you've thoroughly investigated the cause of a problem and can't resolve it on your own and with the help of the community on a public support forum. The product unit isn't able to troubleshoot individual apps that are broken due to simple misconfiguration or use cases involving third-party services. If a report is sensitive or confidential in nature or describes a potential security flaw in the product that attackers may exploit, see [Reporting security issues and bugs (`dotnet/aspnetcore` GitHub repository)](https://github.com/dotnet/aspnetcore/blob/main/CONTRIBUTING.md#reporting-security-issues-and-bugs). + +* Unauthorized client for ME-ID + + > info: Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] + > Authorization failed. These requirements were not met: + > DenyAnonymousAuthorizationRequirement: Requires an authenticated user. + + Login callback error from ME-ID: + + * Error: `unauthorized_client` + * Description: `AADB2C90058: The provided application is not configured to allow public clients.` + + To resolve the error: + + 1. In the Azure portal, access the [app's manifest](/entra/identity-platform/reference-app-manifest). + 1. Set the [`allowPublicClient` attribute](/entra/identity-platform/reference-app-manifest#allowpublicclient-attribute) to `null` or `true`. + +### Cookies and site data + +Cookies and site data can persist across app updates and interfere with testing and troubleshooting. Clear the following when making app code changes, user account changes with the provider, or provider app configuration changes: + +* User sign-in cookies +* App cookies +* Cached and stored site data + +One approach to prevent lingering cookies and site data from interfering with testing and troubleshooting is to: + +* Configure a browser + * Use a browser for testing that you can configure to delete all cookie and site data each time the browser is closed. + * Make sure that the browser is closed manually or by the IDE for any change to the app, test user, or provider configuration. +* Use a custom command to open a browser in InPrivate or Incognito mode in Visual Studio: + * Open **Browse With** dialog box from Visual Studio's **Run** button. + * Select the **Add** button. + * Provide the path to your browser in the **Program** field. The following executable paths are typical installation locations for Windows 10. If your browser is installed in a different location or you aren't using Windows 10, provide the path to the browser's executable. + * Microsoft Edge: `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe` + * Google Chrome: `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` + * Mozilla Firefox: `C:\Program Files\Mozilla Firefox\firefox.exe` + * In the **Arguments** field, provide the command-line option that the browser uses to open in InPrivate or Incognito mode. Some browsers require the URL of the app. + * Microsoft Edge: Use `-inprivate`. + * Google Chrome: Use `--incognito --new-window {URL}`, where the placeholder `{URL}` is the URL to open (for example, `https://localhost:5001`). + * Mozilla Firefox: Use `-private -url {URL}`, where the placeholder `{URL}` is the URL to open (for example, `https://localhost:5001`). + * Provide a name in the **Friendly name** field. For example, `Firefox Auth Testing`. + * Select the **OK** button. + * To avoid having to select the browser profile for each iteration of testing with an app, set the profile as the default with the **Set as Default** button. + * Make sure that the browser is closed by the IDE for any change to the app, test user, or provider configuration. + +### App upgrades + +A functioning app may fail immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. In some cases, incoherent packages may break an app when performing major upgrades. Most of these issues can be fixed by following these instructions: + +1. Clear the local system's NuGet package caches by executing [`dotnet nuget locals all --clear`](/dotnet/core/tools/dotnet-nuget-locals) from a command shell. +1. Delete the project's `bin` and `obj` folders. +1. Restore and rebuild the project. +1. Delete all of the files in the deployment folder on the server prior to redeploying the app. + +> [!NOTE] +> Use of package versions incompatible with the app's target framework isn't supported. For information on a package, use the [NuGet Gallery](https://www.nuget.org) or [FuGet Package Explorer](https://www.fuget.org). + +### Run the server app + +When testing and troubleshooting Blazor Web App, make sure that you're running the app from the server project. + +### Inspect the user + +The following `UserClaims` component can be used directly in apps or serve as the basis for further customization. + +`UserClaims.razor`: + +```razor +@page "/user-claims" +@using System.Security.Claims +@using Microsoft.AspNetCore.Authorization +@attribute [Authorize] + +User Claims + +

User Claims

+ +@if (claims.Count() > 0) +{ + +} + +@code { + private IEnumerable claims = Enumerable.Empty(); + + [CascadingParameter] + private Task? AuthState { get; set; } + + protected override async Task OnInitializedAsync() + { + if (AuthState == null) + { + return; + } + + var authState = await AuthState; + claims = authState.User.Claims; + } +} +``` diff --git a/aspnetcore/blazor/security/includes/troubleshoot.md b/aspnetcore/blazor/security/includes/troubleshoot-wasm.md similarity index 92% rename from aspnetcore/blazor/security/includes/troubleshoot.md rename to aspnetcore/blazor/security/includes/troubleshoot-wasm.md index cc49bb772953..84e31fdcfc00 100644 --- a/aspnetcore/blazor/security/includes/troubleshoot.md +++ b/aspnetcore/blazor/security/includes/troubleshoot-wasm.md @@ -1,8 +1,6 @@ ### Logging -*This section applies to ASP.NET Core in .NET 7 or later.* - -To enable debug or trace logging for Blazor WebAssembly authentication, see . +To enable debug or trace logging for Blazor WebAssembly authentication, see the *Client-side authentication logging* section of with the article version selector set to ASP.NET Core 7.0 or later. ### Common errors @@ -11,9 +9,9 @@ To enable debug or trace logging for Blazor WebAssembly authentication, see ``` +## Troubleshoot + +[!INCLUDE[](~/blazor/security/includes/troubleshoot-server.md)] + ## Additional resources * [`AzureAD/microsoft-identity-web` GitHub repository](https://github.com/AzureAD/microsoft-identity-web/wiki): Helpful guidance on implementing Microsoft Identity Web for Microsoft Entra ID and Azure Active Directory B2C for ASP.NET Core apps, including links to sample apps and related Azure documentation. Currently, Blazor Web Apps aren't explicitly addressed by the Azure documentation, but the setup and configuration of a Blazor Web App for ME-ID and Azure hosting is the same as it is for any ASP.NET Core web app. diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md index 8a4c555dca1e..4632b0d85768 100644 --- a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md +++ b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md @@ -424,7 +424,7 @@ Due to changes in the framework across releases of ASP.NET Core, Razor markup fo ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md b/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md index 39a6c68fe096..92862c15507d 100644 --- a/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md +++ b/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md @@ -818,7 +818,7 @@ Get-ChildItem -path Cert:\CurrentUser\My -Recurse | Format-List DnsNameList, Sub ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md b/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md index b9b008c7e634..082b40b52274 100644 --- a/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md +++ b/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md @@ -490,7 +490,7 @@ Example App ID URI of `urn://custom-app-id-uri` and a scope name of `API.Access` ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-authentication-library.md b/aspnetcore/blazor/security/webassembly/standalone-with-authentication-library.md index 09e6be78d14b..4639162661c3 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-authentication-library.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-authentication-library.md @@ -212,7 +212,7 @@ For more information, see the following sections of the *Additional scenarios* a ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md index 09c4f60a2864..363b25d051fb 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-azure-active-directory-b2c.md @@ -215,7 +215,7 @@ For more information, see the following sections of the *Additional scenarios* a ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md index c5d75fdd59f0..d1a69bd41623 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-accounts.md @@ -192,7 +192,7 @@ For more information, see the following sections of the *Additional scenarios* a ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-entra-id.md b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-entra-id.md index e9be36b8c883..cc7e2d17e364 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-entra-id.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-microsoft-entra-id.md @@ -193,7 +193,7 @@ For more information, see the following resources: ## Troubleshoot -[!INCLUDE[](~/blazor/security/includes/troubleshoot.md)] +[!INCLUDE[](~/blazor/security/includes/troubleshoot-wasm.md)] ## Additional resources