Secure an ASP.NET Core Blazor WebAssembly standalone app with the Authentication library
Note
This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 8 version of this article.
This article explains how to secure an ASP.NET Core Blazor WebAssembly standalone app with the Blazor WebAssembly Authentication library.
The Blazor WebAssembly Authentication library (Authentication.js
) only supports the Proof Key for Code Exchange (PKCE) authorization code flow via the Microsoft Authentication Library (MSAL, msal.js
). To implement other grant flows, access the MSAL guidance to implement MSAL directly, but we don't support or recommend the use of grant flows other than PKCE for Blazor apps.
For Microsoft Entra (ME-ID) and Azure Active Directory B2C (AAD B2C) guidance, don't follow the guidance in this topic. See Secure an ASP.NET Core Blazor WebAssembly standalone app with Microsoft Entra ID or Secure an ASP.NET Core Blazor WebAssembly standalone app with Azure Active Directory B2C.
For additional security scenario coverage after reading this article, see ASP.NET Core Blazor WebAssembly additional security scenarios.
Walkthrough
The subsections of the walkthrough explain how to:
- Register an app
- Create the Blazor app
- Run the app
Register an app
Register an app with an OpenID Connect (OIDC) Identity Provider (IP) following the guidance provided by the maintainer of the IP.
Record the following information:
- Authority (for example,
https://accounts.google.com/
). - Application (client) ID (for example,
2...7-e...q.apps.googleusercontent.com
). - Additional IP configuration (see the IP's documentation).
Note
The IP must use OIDC. For example, Facebook's IP isn't an OIDC-compliant provider, so the guidance in this topic doesn't work with the Facebook IP. For more information, see Secure ASP.NET Core Blazor WebAssembly.
Create the Blazor app
To create a standalone Blazor WebAssembly app that uses the Microsoft.AspNetCore.Components.WebAssembly.Authentication
library, follow the guidance for your choice of tooling. If adding support for authentication, see the Parts of the app section of this article for guidance on setting up and configuring the app.
To create a new Blazor WebAssembly project with an authentication mechanism:
After choosing the Blazor WebAssembly App template, set the Authentication type to Individual Accounts.
After choosing the Blazor WebAssembly App template, set the Authentication type to Individual Accounts. Confirm that the ASP.NET Core Hosted checkbox is not selected.
The Individual Accounts selection uses ASP.NET Core's Identity system. This selection adds authentication support and doesn't result in storing users in a database. The following sections of this article provide further details.
Configure the app
Configure the app following the IP's guidance. At a minimum, the app requires the Local:Authority
and Local:ClientId
configuration settings in the app's wwwroot/appsettings.json
file:
{
"Local": {
"Authority": "{AUTHORITY}",
"ClientId": "{CLIENT ID}"
}
}
Google OAuth 2.0 OIDC example for an app that runs on the localhost
address at port 5001:
{
"Local": {
"Authority": "https://accounts.google.com/",
"ClientId": "2...7-e...q.apps.googleusercontent.com",
"PostLogoutRedirectUri": "https://localhost:5001/authentication/logout-callback",
"RedirectUri": "https://localhost:5001/authentication/login-callback",
"ResponseType": "code"
}
}
The redirect URI (https://localhost:5001/authentication/login-callback
) is registered in the Google APIs console in Credentials > {NAME}
> Authorized redirect URIs, where {NAME}
is the app's client name in the OAuth 2.0 Client IDs app list of the Google APIs console.
Note
Supplying the port number for a localhost
redirect URI isn't required for some OIDC IPs per the OAuth 2.0 specification. Some IPs permit the redirect URI for loopback addresses to omit the port. Others allow the use of a wildcard for the port number (for example, *
). For additional information, see the IP's documentation.
Run the app
Use one of the following approaches to run the app:
- Visual Studio
- Select the Run button.
- Use Debug > Start Debugging from the menu.
- Press F5.
- .NET CLI command shell: Execute the
dotnet watch
(ordotnet run
) command from the app's folder.
Parts of the app
This section describes the parts of an app generated from the Blazor WebAssembly project template and how the app is configured. There's no specific guidance to follow in this section for a basic working application if you created the app using the guidance in the Walkthrough section. The guidance in this section is helpful for updating an app to authenticate and authorize users. However, an alternative approach to updating an app is to create a new app from the guidance in the Walkthrough section and moving the app's components, classes, and resources to the new app.
Authentication package
When an app is created to use Individual User Accounts, the app automatically receives a package reference for the Microsoft.AspNetCore.Components.WebAssembly.Authentication
package. The package provides a set of primitives that help the app authenticate users and obtain tokens to call protected APIs.
If adding authentication to an app, manually add the Microsoft.AspNetCore.Components.WebAssembly.Authentication
package to the app.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Authentication service support
Support for authenticating users using OpenID Connect (OIDC) is registered in the service container with the AddOidcAuthentication extension method provided by the Microsoft.AspNetCore.Components.WebAssembly.Authentication
package.
The AddOidcAuthentication method accepts a callback to configure the parameters required to authenticate an app using OIDC. The values required for configuring the app can be obtained from the OIDC-compliant IP. Obtain the values when you register the app, which typically occurs in their online portal.
For a new app, provide values for the {AUTHORITY}
and {CLIENT ID}
placeholders in the following configuration. Provide other configuration values that are required for use with the app's IP. The example is for Google, which requires PostLogoutRedirectUri
, RedirectUri
, and ResponseType
. If adding authentication to an app, manually add the following code and configuration to the app with values for the placeholders and other configuration values.
In the Program
file:
builder.Services.AddOidcAuthentication(options =>
{
builder.Configuration.Bind("Local", options.ProviderOptions);
});
wwwroot/appsettings.json
configuration
Configuration is supplied by the wwwroot/appsettings.json
file:
{
"Local": {
"Authority": "{AUTHORITY}",
"ClientId": "{CLIENT ID}"
}
}
Access token scopes
The Blazor WebAssembly template automatically configures default scopes for openid
and profile
.
The Blazor WebAssembly template doesn't automatically configure the app to request an access token for a secure API. To provision an access token as part of the sign-in flow, add the scope to the default token scopes of the OidcProviderOptions. If adding authentication to an app, manually add the following code and configure the scope URI.
In the Program
file:
builder.Services.AddOidcAuthentication(options =>
{
...
options.ProviderOptions.DefaultScopes.Add("{SCOPE URI}");
});
For more information, see the following sections of the Additional scenarios article:
Imports file
The Microsoft.AspNetCore.Components.Authorization namespace is made available throughout the app via the _Imports.razor
file:
@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@using Microsoft.JSInterop
@using {APPLICATION ASSEMBLY}
@using {APPLICATION ASSEMBLY}.Shared
Index page
The Index page (wwwroot/index.html
) page includes a script that defines the AuthenticationService
in JavaScript. AuthenticationService
handles the low-level details of the OIDC protocol. The app internally calls methods defined in the script to perform the authentication operations.
<script src="_content/Microsoft.AspNetCore.Components.WebAssembly.Authentication/AuthenticationService.js"></script>
App component
The App
component (App.razor
) is similar to the App
component found in Blazor Server apps:
- The AuthorizeRouteView component makes sure that the current user is authorized to access a given page or otherwise renders the
RedirectToLogin
component. - The
RedirectToLogin
component manages redirecting unauthorized users to the login page.
- The CascadingAuthenticationState component manages exposing the AuthenticationState to the rest of the app.
- The AuthorizeRouteView component makes sure that the current user is authorized to access a given page or otherwise renders the
RedirectToLogin
component. - The
RedirectToLogin
component manages redirecting unauthorized users to the login page.
Due to changes in the framework across releases of ASP.NET Core, Razor markup for the App
component (App.razor
) isn't shown in this section. To inspect the markup of the component for a given release, use either of the following approaches:
Create an app provisioned for authentication from the default Blazor WebAssembly project template for the version of ASP.NET Core that you intend to use. Inspect the
App
component (App.razor
) in the generated app.Inspect the
App
component (App.razor
) in reference source. Select the version from the branch selector, and search for the component in theProjectTemplates
folder of the repository because it has moved over the years.Note
Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).
RedirectToLogin component
The RedirectToLogin
component (RedirectToLogin.razor
):
- Manages redirecting unauthorized users to the login page.
- The current URL that the user is attempting to access is maintained by so that they can be returned to that page if authentication is successful using:
- Navigation history state in ASP.NET Core in .NET 7 or later.
- A query string in ASP.NET Core in .NET 6 or earlier.
Inspect the RedirectToLogin
component in reference source. The location of the component changed over time, so use GitHub search tools to locate the component.
Note
Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).
LoginDisplay component
The LoginDisplay
component (LoginDisplay.razor
) is rendered in the MainLayout
component (MainLayout.razor
) and manages the following behaviors:
- For authenticated users:
- Displays the current user name.
- Offers a link to the user profile page in ASP.NET Core Identity.
- Offers a button to log out of the app.
- For anonymous users:
- Offers the option to register.
- Offers the option to log in.
Due to changes in the framework across releases of ASP.NET Core, Razor markup for the LoginDisplay
component isn't shown in this section. To inspect the markup of the component for a given release, use either of the following approaches:
Create an app provisioned for authentication from the default Blazor WebAssembly project template for the version of ASP.NET Core that you intend to use. Inspect the
LoginDisplay
component in the generated app.Inspect the
LoginDisplay
component in reference source. The location of the component changed over time, so use GitHub search tools to locate the component. The templated content forHosted
equal totrue
is used.Note
Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).
Authentication component
The page produced by the Authentication
component (Pages/Authentication.razor
) defines the routes required for handling different authentication stages.
The RemoteAuthenticatorView component:
- Is provided by the
Microsoft.AspNetCore.Components.WebAssembly.Authentication
package. - Manages performing the appropriate actions at each stage of authentication.
@page "/authentication/{action}"
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication
<RemoteAuthenticatorView Action="@Action" />
@code {
[Parameter]
public string? Action { get; set; }
}
Note
Nullable reference types (NRTs) and .NET compiler null-state static analysis is supported in ASP.NET Core in .NET 6 or later. Prior to the release of ASP.NET Core in .NET 6, the string
type appears without the null type designation (?
).
Troubleshoot
Logging
To enable debug or trace logging for Blazor WebAssembly authentication, see the Client-side authentication logging section of ASP.NET Core Blazor logging 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 sections of this article's guidance show examples of the correct configuration. Carefully check each section of the article 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 (Google documentation)
- Microsoft Edge
- Mozilla Firefox (Mozilla documentation)
For releases of Blazor where a JSON Web Token (JWT) is used, decode the contents of the token used for authenticating a client or accessing a server web API, depending on where the problem is occurring. For more information, see Inspect the content of a JSON Web Token (JWT).
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:
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. 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).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:
- In the Azure portal, access the app's manifest.
- Set the
allowPublicClient
attribute tonull
ortrue
.
- Error:
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
- Microsoft Edge:
- 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{URL}
placeholder is the URL to open (for example,https://localhost:5001
). - Mozilla Firefox: Use
-private -url {URL}
, where the{URL}
placeholder is the URL to open (for example,https://localhost:5001
).
- Microsoft Edge: Use
- 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:
- Clear the local system's NuGet package caches by executing
dotnet nuget locals all --clear
from a command shell. - Delete the project's
bin
andobj
folders. - Restore and rebuild the project.
- 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 or FuGet Package Explorer.
Run the Server
app
When testing and troubleshooting a hosted Blazor WebAssembly solution, make sure that you're running the app from the Server
project.
Inspect the user
The following User
component can be used directly in apps or serve as the basis for further customization.
User.razor
:
@page "/user"
@attribute [Authorize]
@using System.Text.Json
@using System.Security.Claims
@inject IAccessTokenProvider AuthorizationService
<h1>@AuthenticatedUser?.Identity?.Name</h1>
<h2>Claims</h2>
@foreach (var claim in AuthenticatedUser?.Claims ?? Array.Empty<Claim>())
{
<p class="claim">@(claim.Type): @claim.Value</p>
}
<h2>Access token</h2>
<p id="access-token">@AccessToken?.Value</p>
<h2>Access token claims</h2>
@foreach (var claim in GetAccessTokenClaims())
{
<p>@(claim.Key): @claim.Value.ToString()</p>
}
@if (AccessToken != null)
{
<h2>Access token expires</h2>
<p>Current time: <span id="current-time">@DateTimeOffset.Now</span></p>
<p id="access-token-expires">@AccessToken.Expires</p>
<h2>Access token granted scopes (as reported by the API)</h2>
@foreach (var scope in AccessToken.GrantedScopes)
{
<p>Scope: @scope</p>
}
}
@code {
[CascadingParameter]
private Task<AuthenticationState> AuthenticationState { get; set; }
public ClaimsPrincipal AuthenticatedUser { get; set; }
public AccessToken AccessToken { get; set; }
protected override async Task OnInitializedAsync()
{
await base.OnInitializedAsync();
var state = await AuthenticationState;
var accessTokenResult = await AuthorizationService.RequestAccessToken();
if (!accessTokenResult.TryGetToken(out var token))
{
throw new InvalidOperationException(
"Failed to provision the access token.");
}
AccessToken = token;
AuthenticatedUser = state.User;
}
protected IDictionary<string, object> GetAccessTokenClaims()
{
if (AccessToken == null)
{
return new Dictionary<string, object>();
}
// header.payload.signature
var payload = AccessToken.Value.Split(".")[1];
var base64Payload = payload.Replace('-', '+').Replace('_', '/')
.PadRight(payload.Length + (4 - payload.Length % 4) % 4, '=');
return JsonSerializer.Deserialize<IDictionary<string, object>>(
Convert.FromBase64String(base64Payload));
}
}
Inspect the content of a JSON Web Token (JWT)
To decode a JSON Web Token (JWT), use Microsoft's jwt.ms tool. Values in the UI never leave your browser.
Example encoded JWT (shortened for display):
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1j ... bQdHBHGcQQRbW7Wmo6SWYG4V_bU55Ug_PW4pLPr20tTS8Ct7_uwy9DWrzCMzpD-EiwT5IjXwlGX3IXVjHIlX50IVIydBoPQtadvT7saKo1G5Jmutgq41o-dmz6-yBMKV2_nXA25Q
Example JWT decoded by the tool for an app that authenticates against Azure AAD B2C:
{
"typ": "JWT",
"alg": "RS256",
"kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
"exp": 1610059429,
"nbf": 1610055829,
"ver": "1.0",
"iss": "https://mysiteb2c.b2clogin.com/5cc15ea8-a296-4aa3-97e4-226dcc9ad298/v2.0/",
"sub": "5ee963fb-24d6-4d72-a1b6-889c6e2c7438",
"aud": "70bde375-fce3-4b82-984a-b247d823a03f",
"nonce": "b2641f54-8dc4-42ca-97ea-7f12ff4af871",
"iat": 1610055829,
"auth_time": 1610055822,
"idp": "idp.com",
"tfp": "B2C_1_signupsignin"
}.[Signature]
Additional resources
- ASP.NET Core Blazor WebAssembly additional security scenarios
- Unauthenticated or unauthorized web API requests in an app with a secure default client
- Configure ASP.NET Core to work with proxy servers and load balancers: Includes guidance on:
- Using Forwarded Headers Middleware to preserve HTTPS scheme information across proxy servers and internal networks.
- Additional scenarios and use cases, including manual scheme configuration, request path changes for correct request routing, and forwarding the request scheme for Linux and non-IIS reverse proxies.