共用方式為

為 ASP.NET Core Blazor 強制執行內容安全性原則

  • 發行項

注意

這不是這篇文章的最新版本。 如需目前的版本，請參閱 本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。 如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。 如需目前的版本，請參閱 本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱 本文的 .NET 9 版本。

本文說明如何使用內容安全性原則 (CSP) 搭配 ASP.NET Core Blazor 應用程式，協助防範跨網站指令碼 (XSS) 攻擊。

跨網站指令碼 (XSS) 是一種安全性漏洞，網路攻擊者會將一或多個惡意的用戶端指令碼放入應用程式的轉譯內容中。 CSP 可藉由通知瀏覽器有效，協助防範 XSS 攻擊：

  • 載入內容的來源，包括指令碼、樣式表、影像和外掛程式。
  • 頁面所採取的動作，指定表單允許的 URL 目標。

若要將 CSP 套用至應用程式，開發人員會在一或多個 Content-Security-Policy 標頭或 <meta> 標籤中指定數個 CSP 內容安全性指示詞。 如需在啟動時將 CSP 套用至 C# 程式碼中應用程式的指導，請參閱 ASP.NET Core Blazor 啟動。

載入頁面時，瀏覽器會評估原則。 瀏覽器會檢查頁面的來源，並判斷其是否符合內容安全性指示詞的需求。 當原則指示詞與資源不符時，瀏覽器不會載入資源。 例如，請考慮不允許協力廠商指令碼的原則。 當頁面在 src 屬性中包含具有協力廠商來源的 <script> 標籤時，瀏覽器會防止指令碼載入。

大部分新式桌面和行動瀏覽器都支援 CSP，包括 Chrome、Edge、Firefox、Opera 和 Safari。 建議針對 Blazor 應用程式使用 CSP。

原則指示詞

請至少為 Blazor 應用程式指定下列指示詞和來源。 視需要新增其他指示詞和來源。 本文的 [套用原則] 區段中會使用下列指示詞，其中會提供 Blazor 應用程式的範例安全性原則：

  • base-uri：限制頁面 <base> 標籤的 URL。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • default-src：表示原則未明確指定之來源指示詞的後援。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • img-src：指出影像的有效來源。
    • 指定 data: 以允許從 data: URL 載入影像。
    • 指定 https: 以允許從 HTTPS 端點載入影像。
  • object-src：指出 <object>、<embed> 和 <applet> 標籤的有效來源。 指定 none 以防止所有 URL 來源。
  • script-src：指出指令碼的有效來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 在用戶端 Blazor 應用程式中：
      • 指定 wasm-unsafe-eval 以允許用戶端 Blazor Mono 執行階段運作。
      • 指定任何其他雜湊，以允許載入所需的非架構指令碼。
    • 在伺服器端 Blazor 應用程式中，指定雜湊以允許載入所需的指令碼。
  • style-src：指出樣式表的有效來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 如果應用程式使用內嵌樣式，請指定 unsafe-inline 以允許使用您的內嵌樣式。
  • upgrade-insecure-requests：表示應透過 HTTPS 安全地取得來自不安全 (HTTP) 來源的內容 URL。
  • base-uri：限制頁面 <base> 標籤的 URL。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • default-src：表示原則未明確指定之來源指示詞的後援。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • img-src：指出影像的有效來源。
    • 指定 data: 以允許從 data: URL 載入影像。
    • 指定 https: 以允許從 HTTPS 端點載入影像。
  • object-src：指出 <object>、<embed> 和 <applet> 標籤的有效來源。 指定 none 以防止所有 URL 來源。
  • script-src：指出指令碼的有效來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 在用戶端 Blazor 應用程式中：
      • 指定 unsafe-eval 以允許用戶端 Blazor Mono 執行階段運作。
      • 指定任何其他雜湊，以允許載入所需的非架構指令碼。
    • 在伺服器端 Blazor 應用程式中，指定雜湊以允許載入所需的指令碼。
  • style-src：指出樣式表的有效來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 如果應用程式使用內嵌樣式，請指定 unsafe-inline 以允許使用您的內嵌樣式。
  • upgrade-insecure-requests：表示應透過 HTTPS 安全地取得來自不安全 (HTTP) 來源的內容 URL。
  • base-uri：限制頁面 <base> 標籤的 URL。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • default-src：表示原則未明確指定之來源指示詞的後援。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • img-src：指出影像的有效來源。
    • 指定 data: 以允許從 data: URL 載入影像。
    • 指定 https: 以允許從 HTTPS 端點載入影像。
  • object-src：指出 <object>、<embed> 和 <applet> 標籤的有效來源。 指定 none 以防止所有 URL 來源。
  • script-src：指出指令碼的有效來源。
    • 指定 Bootstrap 指令碼的 https://stackpath.bootstrapcdn.com/ 主機來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 在用戶端 Blazor 應用程式中：
      • 指定 unsafe-eval 以允許用戶端 Blazor Mono 執行階段運作。
      • 指定任何其他雜湊，以允許載入所需的非架構指令碼。
    • 在伺服器端 Blazor 應用程式中，指定雜湊以允許載入所需的指令碼。
  • style-src：指出樣式表的有效來源。
    • 指定 https://stackpath.bootstrapcdn.com/ Bootstrap 樣式表的主機來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 指定 unsafe-inline 以允許使用內嵌樣式。
  • upgrade-insecure-requests：表示應透過 HTTPS 安全地取得來自不安全 (HTTP) 來源的內容 URL。
  • base-uri：限制頁面 <base> 標籤的 URL。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • default-src：表示原則未明確指定之來源指示詞的後援。 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
  • img-src：指出影像的有效來源。
    • 指定 data: 以允許從 data: URL 載入影像。
    • 指定 https: 以允許從 HTTPS 端點載入影像。
  • object-src：指出 <object>、<embed> 和 <applet> 標籤的有效來源。 指定 none 以防止所有 URL 來源。
  • script-src：指出指令碼的有效來源。
    • 指定 Bootstrap 指令碼的 https://stackpath.bootstrapcdn.com/ 主機來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 在用戶端 Blazor 應用程式中：
      • 指定雜湊以允許載入所需的指令碼。
      • 指定 unsafe-eval 以使用 eval() 和方法以從字串建立程式碼。
    • 在伺服器端 Blazor 應用程式中，指定雜湊以允許載入所需的指令碼。
  • style-src：指出樣式表的有效來源。
    • 指定 https://stackpath.bootstrapcdn.com/ Bootstrap 樣式表的主機來源。
    • 指定 self 以指出應用程式的來源，包括配置和連接埠號碼，是有效的來源。
    • 指定 unsafe-inline 以允許使用內嵌樣式。 UI 需要內嵌宣告，才能在初始要求之後重新連線用戶端和伺服器。 在未來版本中，可能會移除內嵌樣式，因而不再需要 unsafe-inline。
  • upgrade-insecure-requests：表示應透過 HTTPS 安全地取得來自不安全 (HTTP) 來源的內容 URL。

除了 Microsoft Internet Explorer 之外，所有瀏覽器都支援上述指示詞。

若要取得其他內嵌指令碼的 SHA 雜湊：

  • 套用 [套用原則] 區段中所顯示的 CSP。
  • 在本機執行應用程式時，存取瀏覽器的開發人員工具主控台。 當 CSP 標頭或 meta 標籤存在時，瀏覽器會計算並顯示封鎖指令碼的雜湊。
  • 將瀏覽器所提供的雜湊複製到 script-src 來源。 在每個雜湊周圍使用單引號。

如需內容安全性原則層級 2 瀏覽器支援矩陣，請參閱我是否可以使用：內容安全性原則層級 2。

套用原則

使用 <meta> 標籤來套用原則：

  • 將 http-equiv 屬性值設定為 Content-Security-Policy。
  • 將指示詞放在 content 屬性值中。 以分號 (;) 分隔指示詞。
  • 一律將 meta 標籤放在 <head> 內容中。

下列各節顯示範例原則。 這些範例會針對 Blazor 的每個版本使用本文進行版本設定。 若要使用適合您版本的版本，請使用此網頁上的 [版本] 下拉式選取器選取文件版本。

伺服器端 Blazor 應用程式

在 <head> 內容中，套用原則指示詞一節中所述的指示詞：

<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;">

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

<meta http-equiv="Content-Security-Policy" 
      content="base-uri 'self';
               default-src 'self';
               img-src data: https:;
               object-src 'none';
               script-src https://stackpath.bootstrapcdn.com/ 
                          'self' 
                          'sha256-34WLX60Tw3aG6hylk0plKbZZFXCuepeQ6Hu7OqRf8PI=';
               style-src https://stackpath.bootstrapcdn.com/
                         'self' 
                         'unsafe-inline';
               upgrade-insecure-requests;">

視應用程式需要新增其他 script-src 和 style-src 雜湊。 在開發期間，使用線上工具或瀏覽器開發人員工具來為您計算雜湊。 例如，下列瀏覽器工具主控台錯誤會報告原則未涵蓋之必要指令碼的雜湊：

拒絕執行內嵌指令碼，因為它違反下列內容安全性原則指示詞：" ... "。 需要 'unsafe-inline' 關鍵字、雜湊 ('sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA=') 或 nonce ('nonce-...') 才能啟用內嵌執行。

與錯誤相關聯的特定指令碼會顯示在錯誤旁邊的主控台中。

用戶端 Blazor 應用程式

在 <head> 內容中，套用原則指示詞一節中所述的指示詞：

<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;">

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

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

注意

sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA= 雜湊代表用於用戶端 Blazor 應用程式的內嵌指令碼。 這可能會在未來移除。

<meta http-equiv="Content-Security-Policy" 
      content="base-uri 'self';
               default-src 'self';
               img-src data: https:;
               object-src 'none';
               script-src https://stackpath.bootstrapcdn.com/ 
                          'self' 
                          'sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA=' 
                          'unsafe-eval';
               style-src https://stackpath.bootstrapcdn.com/
                         'self'
                         'unsafe-inline';
               upgrade-insecure-requests;">

<meta http-equiv="Content-Security-Policy" 
      content="base-uri 'self';
               default-src 'self';
               img-src data: https:;
               object-src 'none';
               script-src https://stackpath.bootstrapcdn.com/ 
                          'self' 
                          'sha256-v8ZC9OgMhcnEQ/Me77/R9TlJfzOBqrMTW8e1KuqLaqc=' 
                          'sha256-If//FtbPc03afjLezvWHnC3Nbu4fDM04IIzkPaf3pH0=' 
                          'sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA=' 
                          'unsafe-eval';
               style-src https://stackpath.bootstrapcdn.com/
                         'self'
                         'unsafe-inline';
               upgrade-insecure-requests;">

視應用程式需要新增其他 script-src 和 style-src 雜湊。 在開發期間，使用線上工具或瀏覽器開發人員工具來為您計算雜湊。 例如，下列瀏覽器工具主控台錯誤會報告原則未涵蓋之必要指令碼的雜湊：

拒絕執行內嵌指令碼，因為它違反下列內容安全性原則指示詞：" ... "。 需要 'unsafe-inline' 關鍵字、雜湊 ('sha256-v8v3RKRPmN4odZ1CWM5gw80QKPCCWMcpNeOmimNL2AA=') 或 nonce ('nonce-...') 才能啟用內嵌執行。

與錯誤相關聯的特定指令碼會顯示在錯誤旁邊的主控台中。

在非 Development 環境中套用 CSP

當 CSP 套用至 Blazor 應用程式的 <head> 內容時，會干擾 Development 環境中的本機測試。 例如，瀏覽器連結，且瀏覽器重新整理指令碼無法載入。 下列範例示範如何在非 Development 環境中套用 CSP 的 <meta> 標記。

注意

本節中的範例不會顯示 CSP 的完整 <meta> 標記。 完整 <meta> 標記位於本文稍早套用原則一節的子區段中。

有三種一般方法可供使用：

  • 透過 App 元件套用 CSP，以將 CSP 套用至應用程式的所有配置。
  • 如果您需要將 CSP 套用至應用程式的不同區域，例如只有系統管理員頁面的自訂 CSP，請使用 <HeadContent> 標籤，依配置套用 CSP。 為了獲得完整的有效性，每個應用程式配置檔案都必須採用方法。
  • 裝載服務或伺服器可以透過 Content-Security-Policy 標頭提供 CSP，新增應用程式的傳出回應。 由於此方法會因裝載服務或伺服器而異，因此不會在下列範例中說明。 如果您想要採用此方法，請參閱裝載服務提供者或伺服器的文件。

Blazor Web App 方法

在 App 元件 (Components/App.razor) 中，插入 IHostEnvironment：

@inject IHostEnvironment Env

在 App 元件的 <head> 內容中，當不在 Development 環境中時套用 CSP：

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

或者，在 Components/Layout 資料夾中依個別配置套用 CSP，如下列範例所示。 請確定每個配置都會指定 CSP。

@inject IHostEnvironment Env

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

Blazor WebAssembly 應用程式方法

在 App 元件 (App.razor) 中，插入 IWebAssemblyHostEnvironment：

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

在 App 元件的 <head> 內容中，當不在 Development 環境中時套用 CSP：

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

或者，使用上述程式碼，但在 Layout 資料夾中依個別配置套用 CSP。 請確定每個配置都會指定 CSP。

中繼標籤限制

<meta> 標籤原則不支援下列指示詞：

若要支援上述指示詞，請使用名為 Content-Security-Policy 的標頭。 指示詞字串是標頭的值。

測試原則並接收違規報告

測試有助於確認建置初始原則時，不會意外封鎖協力廠商指令碼。

若要在一段時間內測試原則，而不強制執行原則指示詞，請將 <meta> 標籤的 http-equiv 屬性或標頭式原則的標頭名稱設定為 Content-Security-Policy-Report-Only。 失敗報告會以 JSON 文件的形式傳送至指定的 URL。 如需詳細資訊，請參閱 MDN Web 文件：僅限內容安全性原則報告。

如需在原則作用中時報告違規情況，請參閱下列文章：

雖然不再建議使用 report-uri，但應該使用這兩個指示詞，直到所有主要瀏覽器都支援 report-to 為止。 請勿專門使用 report-uri，因為對 report-uri 的支援可能會隨時從瀏覽器卸除。 完全支援 report-to 時，請移除原則中的 report-uri 支援。 若要追蹤 report-to 的採用情況，請參閱我是否可以使用：報告目的地。

測試並更新每個版本的應用程式原則。

疑難排解

  • 錯誤會出現在瀏覽器的開發人員工具主控台中。 瀏覽器提供下列相關資訊：
    • 不符合原則的元素。
    • 如何修改原則以允許封鎖的項目。
  • 只有在用戶端的瀏覽器支援所有內含指示詞時，原則才完全有效。 如需目前的瀏覽器支援矩陣，請參閱我是否可以使用：內容安全性原則。

其他資源