Secure ASP.NET Core Blazor WebAssembly

Blazor WebAssembly apps are secured in the same manner as single-page applications (SPAs). There are several approaches for authenticating users to SPAs, but the most common and comprehensive approach is to use an implementation based on the OAuth 2.0 protocol, such as OpenID Connect (OIDC).

Authentication library

Blazor WebAssembly supports authenticating and authorizing apps using OIDC via the Microsoft.AspNetCore.Components.WebAssembly.Authentication library. The library provides a set of primitives for seamlessly authenticating against ASP.NET Core backends. The library integrates ASP.NET Core Identity with API authorization support built on top of Duende Identity Server. The library can authenticate against any third-party Identity Provider (IP) that supports OIDC, which are called OpenID Providers (OP).

Important

Duende Software might require you to pay a license fee for production use of Duende Identity Server. For more information, see Migrate from ASP.NET Core 5.0 to 6.0.

The authentication support in Blazor WebAssembly is built on top of the oidc-client.js library, which is used to handle the underlying authentication protocol details.

Other options for authenticating SPAs exist, such as the use of SameSite cookies. However, the engineering design of Blazor WebAssembly is settled on OAuth and OIDC as the best option for authentication in Blazor WebAssembly apps. Token-based authentication based on JSON Web Tokens (JWTs) was chosen over cookie-based authentication for functional and security reasons:

• Using a token-based protocol offers a smaller attack surface area, as the tokens aren't sent in all requests.
• Server endpoints don't require protection against Cross-Site Request Forgery (CSRF) because the tokens are sent explicitly. This allows you to host Blazor WebAssembly apps alongside MVC or Razor pages apps.
• Tokens have narrower permissions than cookies. For example, tokens can't be used to manage the user account or change a user's password unless such functionality is explicitly implemented.
• Tokens have a short lifetime, one hour by default, which limits the attack window. Tokens can also be revoked at any time.
• Self-contained JWTs offer guarantees to the client and server about the authentication process. For example, a client has the means to detect and validate that the tokens it receives are legitimate and were emitted as part of a given authentication process. If a third party attempts to switch a token in the middle of the authentication process, the client can detect the switched token and avoid using it.
• Tokens with OAuth and OIDC don't rely on the user agent behaving correctly to ensure that the app is secure.
• Token-based protocols, such as OAuth and OIDC, allow for authenticating and authorizing hosted and standalone apps with the same set of security characteristics.

Important

Prerendering isn't supported for authentication endpoints (/authentication/ path segment). For more information, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Authentication process with OIDC

The Microsoft.AspNetCore.Components.WebAssembly.Authentication library offers several primitives to implement authentication and authorization using OIDC. In broad terms, authentication works as follows:

• When an anonymous user selects the login button or requests a page with the [Authorize] attribute applied, the user is redirected to the app's login page (/authentication/login).
• In the login page, the authentication library prepares for a redirect to the authorization endpoint. The authorization endpoint is outside of the Blazor WebAssembly app and can be hosted at a separate origin. The endpoint is responsible for determining whether the user is authenticated and for issuing one or more tokens in response. The authentication library provides a login callback to receive the authentication response.
  • If the user isn't authenticated, the user is redirected to the underlying authentication system, which is usually ASP.NET Core Identity.
  • If the user was already authenticated, the authorization endpoint generates the appropriate tokens and redirects the browser back to the login callback endpoint (/authentication/login-callback).
• When the Blazor WebAssembly app loads the login callback endpoint (/authentication/login-callback), the authentication response is processed.
  • If the authentication process completes successfully, the user is authenticated and optionally sent back to the original protected URL that the user requested.
  • If the authentication process fails for any reason, the user is sent to the login failed page (/authentication/login-failed), and an error is displayed.

Authentication component

The Authentication component (Pages/Authentication.razor) handles remote authentication operations and permits the app to:

• Configure app routes for authentication states.
• Set UI content for authentication states.
• Manage authentication state.

Authentication actions, such as registering or signing in a user, are passed to the Blazor framework's RemoteAuthenticatorViewCore<TAuthenticationState> component, which persists and controls state across authentication operations.

For more information and examples, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Authorization

In Blazor WebAssembly apps, authorization checks can be bypassed because all client-side code can be modified by users. The same is true for all client-side app technologies, including JavaScript SPA frameworks or native apps for any operating system.

Always perform authorization checks on the server within any API endpoints accessed by your client-side app.

Require authorization for the entire app

Apply the [Authorize] attribute (API documentation) to each Razor component of the app using one of the following approaches:

• In the app's Imports file, add an @using directive for the Microsoft.AspNetCore.Authorization namespace with an @attribute directive for the [Authorize] attribute.

  _Imports.razor:

  @using Microsoft.AspNetCore.Authorization
  @attribute [Authorize]
  

  Allow anonymous access to the Authentication component to permit redirection to the Idenfity Provider. Add the following Razor code to the Authentication component under its @page directive.

  Pages/Authentication.razor:

  @using Microsoft.AspNetCore.Components.WebAssembly.Authentication
  @attribute [AllowAnonymous]
  

• Add the attribute to each Razor component in the Pages folder.

Note

Setting an AuthorizationOptions.FallbackPolicy to a policy with RequireAuthenticatedUser is not supported.

Refresh tokens

Refresh tokens can't be secured client-side in Blazor WebAssembly apps. Therefore, refresh tokens shouldn't be sent to the app for direct use.

Refresh tokens can be maintained and used by the server-side app in a hosted Blazor WebAssembly solution to access third-party APIs. For more information, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Establish claims for users

Apps often require claims for users based on a web API call to a server. For example, claims are frequently used to establish authorization in an app. In these scenarios, the app requests an access token to access the service and uses the token to obtain the user data for the claims. For examples, see the following resources:

• Additional scenarios: Customize the user
• ASP.NET Core Blazor WebAssembly with Azure Active Directory groups and roles

Azure App Service on Linux with Identity Server

Specify the issuer explicitly when deploying to Azure App Service on Linux with Identity Server. For more information, see Introduction to authentication for Single Page Apps on ASP.NET Core.

Windows Authentication

We don't recommend using Windows Authentication with Blazor Webassembly or with any other SPA framework. We recommend using token-based protocols instead of Windows Authentication, such as OIDC with Active Directory Federation Services (ADFS).

If Windows Authentication is used with Blazor Webassembly or with any other SPA framework, additional measures are required to protect the app from cross-site request forgery (CSRF) tokens. The same concerns that apply to cookies apply to Windows Authentication with the addition that Windows Authentication doesn't offer any mechanism to prevent sharing of the authentication context across origins. Apps using Windows Authentication without additional protection from CSRF should at least be restricted to an organization's intranet and not be used on the Internet.

For more information, see Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core.

Implementation guidance

Articles under this Overview provide information on authenticating users in Blazor WebAssembly apps against specific providers.

Standalone Blazor WebAssembly apps:

• General guidance for OIDC providers and the WebAssembly Authentication Library
• Microsoft Accounts
• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C

Hosted Blazor WebAssembly apps:

• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C
• Identity Server

Further configuration guidance is found in the following articles:

• ASP.NET Core Blazor WebAssembly additional security scenarios
• Use Graph API with ASP.NET Core Blazor WebAssembly

Additional resources

• Microsoft identity platform documentation
• 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.
• Support prerendering with authentication

Authentication library

Blazor WebAssembly supports authenticating and authorizing apps using OIDC via the Microsoft.AspNetCore.Components.WebAssembly.Authentication library. The library provides a set of primitives for seamlessly authenticating against ASP.NET Core backends. The library integrates ASP.NET Core Identity with API authorization support built on top of Identity Server. The library can authenticate against any third-party Identity Provider (IP) that supports OIDC, which are called OpenID Providers (OP).

The authentication support in Blazor WebAssembly is built on top of the oidc-client.js library, which is used to handle the underlying authentication protocol details.

Other options for authenticating SPAs exist, such as the use of SameSite cookies. However, the engineering design of Blazor WebAssembly is settled on OAuth and OIDC as the best option for authentication in Blazor WebAssembly apps. Token-based authentication based on JSON Web Tokens (JWTs) was chosen over cookie-based authentication for functional and security reasons:

• Using a token-based protocol offers a smaller attack surface area, as the tokens aren't sent in all requests.
• Server endpoints don't require protection against Cross-Site Request Forgery (CSRF) because the tokens are sent explicitly. This allows you to host Blazor WebAssembly apps alongside MVC or Razor pages apps.
• Tokens have narrower permissions than cookies. For example, tokens can't be used to manage the user account or change a user's password unless such functionality is explicitly implemented.
• Tokens have a short lifetime, one hour by default, which limits the attack window. Tokens can also be revoked at any time.
• Self-contained JWTs offer guarantees to the client and server about the authentication process. For example, a client has the means to detect and validate that the tokens it receives are legitimate and were emitted as part of a given authentication process. If a third party attempts to switch a token in the middle of the authentication process, the client can detect the switched token and avoid using it.
• Tokens with OAuth and OIDC don't rely on the user agent behaving correctly to ensure that the app is secure.
• Token-based protocols, such as OAuth and OIDC, allow for authenticating and authorizing hosted and standalone apps with the same set of security characteristics.

Authentication process with OIDC

The Microsoft.AspNetCore.Components.WebAssembly.Authentication library offers several primitives to implement authentication and authorization using OIDC. In broad terms, authentication works as follows:

• When an anonymous user selects the login button or requests a page with the [Authorize] attribute applied, the user is redirected to the app's login page (/authentication/login).
• In the login page, the authentication library prepares for a redirect to the authorization endpoint. The authorization endpoint is outside of the Blazor WebAssembly app and can be hosted at a separate origin. The endpoint is responsible for determining whether the user is authenticated and for issuing one or more tokens in response. The authentication library provides a login callback to receive the authentication response.
  • If the user isn't authenticated, the user is redirected to the underlying authentication system, which is usually ASP.NET Core Identity.
  • If the user was already authenticated, the authorization endpoint generates the appropriate tokens and redirects the browser back to the login callback endpoint (/authentication/login-callback).
• When the Blazor WebAssembly app loads the login callback endpoint (/authentication/login-callback), the authentication response is processed.
  • If the authentication process completes successfully, the user is authenticated and optionally sent back to the original protected URL that the user requested.
  • If the authentication process fails for any reason, the user is sent to the login failed page (/authentication/login-failed), and an error is displayed.

Authentication component

The Authentication component (Pages/Authentication.razor) handles remote authentication operations and permits the app to:

• Configure app routes for authentication states.
• Set UI content for authentication states.
• Manage authentication state.

Authentication actions, such as registering or signing in a user, are passed to the Blazor framework's RemoteAuthenticatorViewCore<TAuthenticationState> component, which persists and controls state across authentication operations.

For more information and examples, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Authorization

In Blazor WebAssembly apps, authorization checks can be bypassed because all client-side code can be modified by users. The same is true for all client-side app technologies, including JavaScript SPA frameworks or native apps for any operating system.

Always perform authorization checks on the server within any API endpoints accessed by your client-side app.

Require authorization for the entire app

Apply the [Authorize] attribute (API documentation) to each Razor component of the app using one of the following approaches:

• In the app's Imports file, add an @using directive for the Microsoft.AspNetCore.Authorization namespace with an @attribute directive for the [Authorize] attribute.

  _Imports.razor:

  @using Microsoft.AspNetCore.Authorization
  @attribute [Authorize]
  

  Allow anonymous access to the Authentication component to permit redirection to the Idenfity Provider. Add the following Razor code to the Authentication component under its @page directive.

  Pages/Authentication.razor:

  @using Microsoft.AspNetCore.Components.WebAssembly.Authentication
  @attribute [AllowAnonymous]
  

• Add the attribute to each Razor component in the Pages folder.

Note

Setting an AuthorizationOptions.FallbackPolicy to a policy with RequireAuthenticatedUser is not supported.

Refresh tokens

Refresh tokens can't be secured client-side in Blazor WebAssembly apps. Therefore, refresh tokens shouldn't be sent to the app for direct use.

Refresh tokens can be maintained and used by the server-side app in a hosted Blazor WebAssembly solution to access third-party APIs. For more information, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Establish claims for users

Apps often require claims for users based on a web API call to a server. For example, claims are frequently used to establish authorization in an app. In these scenarios, the app requests an access token to access the service and uses the token to obtain the user data for the claims. For examples, see the following resources:

• Additional scenarios: Customize the user
• ASP.NET Core Blazor WebAssembly with Azure Active Directory groups and roles

Azure App Service on Linux with Identity Server

Specify the issuer explicitly when deploying to Azure App Service on Linux with Identity Server. For more information, see Introduction to authentication for Single Page Apps on ASP.NET Core.

Windows Authentication

We don't recommend using Windows Authentication with Blazor Webassembly or with any other SPA framework. We recommend using token-based protocols instead of Windows Authentication, such as OIDC with Active Directory Federation Services (ADFS).

If Windows Authentication is used with Blazor Webassembly or with any other SPA framework, additional measures are required to protect the app from cross-site request forgery (CSRF) tokens. The same concerns that apply to cookies apply to Windows Authentication with the addition that Windows Authentication doesn't offer any mechanism to prevent sharing of the authentication context across origins. Apps using Windows Authentication without additional protection from CSRF should at least be restricted to an organization's intranet and not be used on the Internet.

For more information, see Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core.

Implementation guidance

Articles under this Overview provide information on authenticating users in Blazor WebAssembly apps against specific providers.

Standalone Blazor WebAssembly apps:

• General guidance for OIDC providers and the WebAssembly Authentication Library
• Microsoft Accounts
• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C

Hosted Blazor WebAssembly apps:

• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C
• Identity Server

Further configuration guidance is found in the following articles:

• ASP.NET Core Blazor WebAssembly additional security scenarios
• Use Graph API with ASP.NET Core Blazor WebAssembly

Additional resources

• Microsoft identity platform documentation
• 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.
• Support prerendering with authentication

Authentication library

Blazor WebAssembly supports authenticating and authorizing apps using OIDC via the Microsoft.AspNetCore.Components.WebAssembly.Authentication library. The library provides a set of primitives for seamlessly authenticating against ASP.NET Core backends. The library integrates ASP.NET Core Identity with API authorization support built on top of Identity Server. The library can authenticate against any third-party Identity Provider (IP) that supports OIDC, which are called OpenID Providers (OP).

The authentication support in Blazor WebAssembly is built on top of the oidc-client.js library, which is used to handle the underlying authentication protocol details.

Other options for authenticating SPAs exist, such as the use of SameSite cookies. However, the engineering design of Blazor WebAssembly is settled on OAuth and OIDC as the best option for authentication in Blazor WebAssembly apps. Token-based authentication based on JSON Web Tokens (JWTs) was chosen over cookie-based authentication for functional and security reasons:

• Using a token-based protocol offers a smaller attack surface area, as the tokens aren't sent in all requests.
• Server endpoints don't require protection against Cross-Site Request Forgery (CSRF) because the tokens are sent explicitly. This allows you to host Blazor WebAssembly apps alongside MVC or Razor pages apps.
• Tokens have narrower permissions than cookies. For example, tokens can't be used to manage the user account or change a user's password unless such functionality is explicitly implemented.
• Tokens have a short lifetime, one hour by default, which limits the attack window. Tokens can also be revoked at any time.
• Self-contained JWTs offer guarantees to the client and server about the authentication process. For example, a client has the means to detect and validate that the tokens it receives are legitimate and were emitted as part of a given authentication process. If a third party attempts to switch a token in the middle of the authentication process, the client can detect the switched token and avoid using it.
• Tokens with OAuth and OIDC don't rely on the user agent behaving correctly to ensure that the app is secure.
• Token-based protocols, such as OAuth and OIDC, allow for authenticating and authorizing hosted and standalone apps with the same set of security characteristics.

Authentication process with OIDC

The Microsoft.AspNetCore.Components.WebAssembly.Authentication library offers several primitives to implement authentication and authorization using OIDC. In broad terms, authentication works as follows:

• When an anonymous user selects the login button or requests a page with the [Authorize] attribute applied, the user is redirected to the app's login page (/authentication/login).
• In the login page, the authentication library prepares for a redirect to the authorization endpoint. The authorization endpoint is outside of the Blazor WebAssembly app and can be hosted at a separate origin. The endpoint is responsible for determining whether the user is authenticated and for issuing one or more tokens in response. The authentication library provides a login callback to receive the authentication response.
  • If the user isn't authenticated, the user is redirected to the underlying authentication system, which is usually ASP.NET Core Identity.
  • If the user was already authenticated, the authorization endpoint generates the appropriate tokens and redirects the browser back to the login callback endpoint (/authentication/login-callback).
• When the Blazor WebAssembly app loads the login callback endpoint (/authentication/login-callback), the authentication response is processed.
  • If the authentication process completes successfully, the user is authenticated and optionally sent back to the original protected URL that the user requested.
  • If the authentication process fails for any reason, the user is sent to the login failed page (/authentication/login-failed), and an error is displayed.

Authentication component

The Authentication component (Pages/Authentication.razor) handles remote authentication operations and permits the app to:

• Configure app routes for authentication states.
• Set UI content for authentication states.
• Manage authentication state.

Authentication actions, such as registering or signing in a user, are passed to the Blazor framework's RemoteAuthenticatorViewCore<TAuthenticationState> component, which persists and controls state across authentication operations.

For more information and examples, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Authorization

In Blazor WebAssembly apps, authorization checks can be bypassed because all client-side code can be modified by users. The same is true for all client-side app technologies, including JavaScript SPA frameworks or native apps for any operating system.

Always perform authorization checks on the server within any API endpoints accessed by your client-side app.

Require authorization for the entire app

Apply the [Authorize] attribute (API documentation) to each Razor component of the app using one of the following approaches:

• In the app's Imports file, add an @using directive for the Microsoft.AspNetCore.Authorization namespace with an @attribute directive for the [Authorize] attribute.

  _Imports.razor:

  @using Microsoft.AspNetCore.Authorization
  @attribute [Authorize]
  

  Allow anonymous access to the Authentication component to permit redirection to the Idenfity Provider. Add the following Razor code to the Authentication component under its @page directive.

  Pages/Authentication.razor:

  @using Microsoft.AspNetCore.Components.WebAssembly.Authentication
  @attribute [AllowAnonymous]
  

• Add the attribute to each Razor component in the Pages folder.

Note

Setting an AuthorizationOptions.FallbackPolicy to a policy with RequireAuthenticatedUser is not supported.

Refresh tokens

Refresh tokens can't be secured client-side in Blazor WebAssembly apps. Therefore, refresh tokens shouldn't be sent to the app for direct use.

Refresh tokens can be maintained and used by the server-side app in a hosted Blazor WebAssembly solution to access third-party APIs. For more information, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Establish claims for users

Apps often require claims for users based on a web API call to a server. For example, claims are frequently used to establish authorization in an app. In these scenarios, the app requests an access token to access the service and uses the token to obtain the user data for the claims. For examples, see the following resources:

• Additional scenarios: Customize the user
• ASP.NET Core Blazor WebAssembly with Azure Active Directory groups and roles

Azure App Service on Linux with Identity Server

Specify the issuer explicitly when deploying to Azure App Service on Linux with Identity Server. For more information, see Introduction to authentication for Single Page Apps on ASP.NET Core.

Windows Authentication

We don't recommend using Windows Authentication with Blazor Webassembly or with any other SPA framework. We recommend using token-based protocols instead of Windows Authentication, such as OIDC with Active Directory Federation Services (ADFS).

If Windows Authentication is used with Blazor Webassembly or with any other SPA framework, additional measures are required to protect the app from cross-site request forgery (CSRF) tokens. The same concerns that apply to cookies apply to Windows Authentication with the addition that Windows Authentication doesn't offer any mechanism to prevent sharing of the authentication context across origins. Apps using Windows Authentication without additional protection from CSRF should at least be restricted to an organization's intranet and not be used on the Internet.

For more information, see Prevent Cross-Site Request Forgery (XSRF/CSRF) attacks in ASP.NET Core.

Implementation guidance

Articles under this Overview provide information on authenticating users in Blazor WebAssembly apps against specific providers.

Standalone Blazor WebAssembly apps:

• General guidance for OIDC providers and the WebAssembly Authentication Library
• Microsoft Accounts
• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C

Hosted Blazor WebAssembly apps:

• Azure Active Directory (AAD)
• Azure Active Directory (AAD) B2C
• Identity Server

For further configuration guidance, see ASP.NET Core Blazor WebAssembly additional security scenarios.

Additional resources

• Microsoft identity platform documentation
• 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.
• Support prerendering with authentication