Enforce a Content Security Policy for ASP.NET Core Blazor

This article explains how to use a Content Security Policy (CSP) with ASP.NET Core Blazor apps to help protect against Cross-Site Scripting (XSS) attacks.

Cross-Site Scripting (XSS) is a security vulnerability where an attacker places one or more malicious client-side scripts into an app's rendered content. A CSP helps protect against XSS attacks by informing the browser of valid:

• Sources for loaded content, including scripts, stylesheets, images, and plugins.
• Actions taken by a page, specifying permitted URL targets of forms.

To apply a CSP to an app, the developer specifies several CSP content security directives in one or more Content-Security-Policy headers or <meta> tags. For guidance on applying a CSP to an app in C# code at startup, see ASP.NET Core Blazor startup.

Policies are evaluated by the browser while a page is loading. The browser inspects the page's sources and determines if they meet the requirements of the content security directives. When policy directives aren't met for a resource, the browser doesn't load the resource. For example, consider a policy that doesn't allow third-party scripts. When a page contains a <script> tag with a third-party origin in the src attribute, the browser prevents the script from loading.

CSP is supported in most modern desktop and mobile browsers, including Chrome, Edge, Firefox, Opera, and Safari. CSP is recommended for Blazor apps.

Policy directives

Minimally, specify the following directives and sources for Blazor apps. Add additional directives and sources as needed. The following directives are used in the Apply the policy section of this article, where example security policies for Blazor apps are provided:

• base-uri: Restricts the URLs for a page's <base> tag. Specify self to indicate that the app's origin, including the scheme and port number, is a valid source.
• default-src: Indicates a fallback for source directives that aren't explicitly specified by the policy. Specify self to indicate that the app's origin, including the scheme and port number, is a valid source.
• img-src: Indicates valid sources for images.
  • Specify data: to permit loading images from data: URLs.
  • Specify https: to permit loading images from HTTPS endpoints.
• object-src: Indicates valid sources for the <object>, <embed>, and <applet> tags. Specify none to prevent all URL sources.
• script-src: Indicates valid sources for scripts.
  • Specify self to indicate that the app's origin, including the scheme and port number, is a valid source.
  • In a client-side Blazor app:
    • Specify wasm-unsafe-eval to permit the client-side Blazor Mono runtime to function.
    • Specify any additional hashes to permit your required non-framework scripts to load.
  • In a server-side Blazor app, specify hashes to permit required scripts to load.
• style-src: Indicates valid sources for stylesheets.
  • Specify self to indicate that the app's origin, including the scheme and port number, is a valid source.
  • If the app uses inline styles, specify unsafe-inline to allow the use of your inline styles.
• upgrade-insecure-requests: Indicates that content URLs from insecure (HTTP) sources should be acquired securely over HTTPS.

The preceding directives are supported by all browsers except Microsoft Internet Explorer.

To obtain SHA hashes for additional inline scripts:

• Apply the CSP shown in the Apply the policy section.
• Access the browser's developer tools console while running the app locally. The browser calculates and displays hashes for blocked scripts when a CSP header or meta tag is present.
• Copy the hashes provided by the browser to the script-src sources. Use single quotes around each hash.

For a Content Security Policy Level 2 browser support matrix, see Can I use: Content Security Policy Level 2.

Apply the policy

Use a <meta> tag to apply the policy:

• Set the value of the http-equiv attribute to Content-Security-Policy.
• Place the directives in the content attribute value. Separate directives with a semicolon (;).
• Always place the meta tag in the <head> content.

The following sections show example policies. These examples are versioned with this article for each release of Blazor. To use a version appropriate for your release, select the document version with the Version dropdown selector on this webpage.

Server-side Blazor apps

In the <head> content, apply the directives described in the Policy directives section:

<meta http-equiv="Content-Security-Policy" 
      content="base-uri 'self';
               default-src 'self';
               img-src data: https:;
               object-src 'none';
               script-src 'self';
               style-src 'self';
               upgrade-insecure-requests;">

Add additional script-src and style-src hashes as required by the app. During development, use an online tool or browser developer tools to have the hashes calculated for you. For example, the following browser tools console error reports the hash for a required script not covered by the policy:

Refused to execute inline script because it violates the following Content Security Policy directive: " ... ". Either the 'unsafe-inline' keyword, a hash ('sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA='), or a nonce ('nonce-...') is required to enable inline execution.

The particular script associated with the error is displayed in the console next to the error.

Client-side Blazor apps

In the <head> content, apply the directives described in the Policy directives section:

<meta http-equiv="Content-Security-Policy" 
      content="base-uri 'self';
               default-src 'self';
               img-src data: https:;
               object-src 'none';
               script-src 'self'
                          'wasm-unsafe-eval';
               style-src 'self';
               upgrade-insecure-requests;">

Add additional script-src and style-src hashes as required by the app. During development, use an online tool or browser developer tools to have the hashes calculated for you. For example, the following browser tools console error reports the hash for a required script not covered by the policy:

Refused to execute inline script because it violates the following Content Security Policy directive: " ... ". Either the 'unsafe-inline' keyword, a hash ('sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA='), or a nonce ('nonce-...') is required to enable inline execution.

The particular script associated with the error is displayed in the console next to the error.

Apply a CSP in non-Development environments

When a CSP is applied to a Blazor app's <head> content, it interferes with local testing in the Development environment. For example, Browser Link and the browser refresh script fail to load. The following examples demonstrate how to apply the CSP's <meta> tag in non-Development environments.

Note

The examples in this section don't show the full <meta> tag for the CSPs. The complete <meta> tags are found in the subsections of the Apply the policy section earlier in this article.

Three general approaches are available:

• Apply the CSP via the App component, which applies the CSP to all layouts of the app.
• If you need to apply CSPs to different areas of the app, for example a custom CSP for only the admin pages, apply the CSPs on a per-layout basis using the <HeadContent> tag. For complete effectiveness, every app layout file must adopt the approach.
• The hosting service or server can provide a CSP via a Content-Security-Policy header added an app's outgoing responses. Because this approach varies by hosting service or server, it isn't addressed in the following examples. If you wish to adopt this approach, consult the documentation for your hosting service provider or server.

Blazor Web App approaches

In the App component (Components/App.razor), inject IHostEnvironment:

@inject IHostEnvironment Env

In the App component's <head> content, apply the CSP when not in the Development environment:

@if (!Env.IsDevelopment())
{
    <meta ...>
}

Alternatively, apply CSPs on a per-layout basis in the Components/Layout folder, as the following example demonstrates. Make sure that every layout specifies a CSP.

@inject IHostEnvironment Env

@if (!Env.IsDevelopment())
{
    <HeadContent>
        <meta ...>
    </HeadContent>
}

Blazor WebAssembly app approaches

In the App component (App.razor), inject IWebAssemblyHostEnvironment:

@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

In the App component's <head> content, apply the CSP when not in the Development environment:

@if (!Env.IsDevelopment())
{
    <HeadContent>
        <meta ...>
    </HeadContent>
}

Alternatively, use the preceding code but apply CSPs on a per-layout basis in the Layout folder. Make sure that every layout specifies a CSP.

Meta tag limitations

A <meta> tag policy doesn't support the following directives:

• frame-ancestors
• report-to
• report-uri
• sandbox

To support the preceding directives, use a header named Content-Security-Policy. The directive string is the header's value.

Test a policy and receive violation reports

Testing helps confirm that third-party scripts aren't inadvertently blocked when building an initial policy.

To test a policy over a period of time without enforcing the policy directives, set the <meta> tag's http-equiv attribute or header name of a header-based policy to Content-Security-Policy-Report-Only. Failure reports are sent as JSON documents to a specified URL. For more information, see MDN web docs: Content-Security-Policy-Report-Only.

For reporting on violations while a policy is active, see the following articles:

• report-to
• report-uri

Although report-uri is no longer recommended for use, both directives should be used until report-to is supported by all of the major browsers. Don't exclusively use report-uri because support for report-uri is subject to being dropped at any time from browsers. Remove support for report-uri in your policies when report-to is fully supported. To track adoption of report-to, see Can I use: report-to.

Test and update an app's policy every release.

Troubleshoot

• Errors appear in the browser's developer tools console. Browsers provide information about:
  • Elements that don't comply with the policy.
  • How to modify the policy to allow for a blocked item.
• A policy is only completely effective when the client's browser supports all of the included directives. For a current browser support matrix, see Can I use: Content-Security-Policy.

Additional resources

• Apply a CSP in C# code at startup
• MDN web docs: Content Security Policy (CSP)
• MDN web docs: Content-Security-Policy response header
• Content Security Policy Level 2
• Google CSP Evaluator