本頁面由 Cloud Translation API 翻譯而成。

App Check 網站程式碼研究室

1. 簡介

上次更新時間：2023 年 2 月 23 日

如何防止未經授權存取 Firebase 資源？

您可以透過 Firebase App Check，要求傳入的要求附上證明，確認要求來自您的應用程式，並封鎖沒有適當證明的流量，防止未經授權的用戶端存取後端資源。Firebase App Check 會使用平台專用的認證供應商驗證用戶端是否為正版。對於網頁應用程式，App Check 支援 reCAPTCHA v3 和 reCAPTCHA Enterprise 做為認證供應商。

App Check 可用於保護傳送至 Cloud Firestore、即時資料庫、Cloud Functions、Firebase Authentication with Identity Platform，以及您自行代管後端的要求。

建構項目

在本程式碼研究室中，您將先新增並強制執行應用程式檢查，確保即時通訊應用程式安全無虞。

您建構的起始友善聊天應用程式。

課程內容

如何監控後端是否有未經授權的存取活動
如何對 Firestore 和 Cloud Storage 啟用強制執行功能
如何使用偵錯權杖執行應用程式，進行本機開發

軟硬體需求

您選擇的 IDE/文字編輯器
套件管理員 npm (通常會隨附於 Node.js)
已安裝 Firebase CLI，並設定為與您的帳戶搭配使用
終端機/控制台
你選擇的瀏覽器，例如 Chrome
程式碼研究室的程式碼範例 (請參閱程式碼研究室的下一個步驟，瞭解如何取得程式碼)。

2. 取得程式碼範例

從指令列複製程式碼研究室的 GitHub 存放區：

git clone https://github.com/firebase/codelab-friendlychat-web

或者，如果您未安裝 Git，可以將存放區下載為 ZIP 檔案。

匯入範例應用程式

使用 IDE 開啟或匯入複製存放區中的 📁 appcheck-start 目錄。這個 📁 appcheck-start 目錄包含程式碼研究室的起始程式碼，也就是功能齊全的即時通訊網路應用程式。📁 appcheck 目錄則包含程式碼研究室的完成程式碼。

3. 建立及設定 Firebase 專案

建立 Firebase 專案

使用 Google 帳戶登入 Firebase 控制台。
按一下按鈕建立新專案，然後輸入專案名稱 (例如 FriendlyChat)。
這個專案名稱會做為 Firebase 介面中的顯示名稱，而 Firebase 會根據這個專案名稱自動建立專屬的專案 ID。請注意，您現在可以選擇按一下「編輯」圖示，設定偏好的專案 ID，但專案建立後就無法變更這個 ID。

記住專案 ID，後續步驟將會用到，以便在 Firebase CLI 中識別 Firebase 專案。如果忘記 ID，之後隨時可以在「專案設定」中找到。
按一下「繼續」。
如果系統提示，請詳閱並接受 Firebase 條款，然後按一下「繼續」。
(選用) 在 Firebase 控制台中啟用 AI 輔助功能 (稱為「Gemini in Firebase」)。
本程式碼研究室不需要 Google Analytics，因此請關閉 Google Analytics 選項。
按一下「建立專案」，等待專案佈建完成，然後按一下「繼續」。

升級 Firebase 定價方案

如要使用 Cloud Storage for Firebase，Firebase 專案必須採用即付即用 (Blaze) 定價方案，也就是連結至 Cloud Billing 帳戶。

Cloud Billing 帳戶需要付款方式，例如信用卡。
如果您剛開始使用 Firebase 和 Google Cloud，請確認是否符合 $300 美元抵免額和免費試用 Cloud Billing 帳戶的資格。
如果您是在活動中進行這項程式碼研究室，請詢問主辦單位是否有可用的 Cloud 抵免額。

如要將專案升級至 Blaze 方案，請按照下列步驟操作：

在 Firebase 控制台中，選取「升級方案」。
選取 Blaze 方案。按照畫面上的指示，將 Cloud Billing 帳戶連結至專案。
如果你在升級過程中需要建立 Cloud Billing 帳戶，可能需要返回 Firebase 控制台的升級流程，才能完成升級。

將 Firebase 網頁應用程式新增至專案

按一下網頁圖示，建立新的 Firebase 網頁應用程式。
以「Friendly Chat」這個暱稱註冊應用程式，然後勾選「Also set up Firebase Hosting for this app」旁的方塊。按一下「Register app」。
在下一個步驟中，您會看到使用 npm 安裝 Firebase 的指令和設定物件。您會在後續的程式碼研究室中複製這個物件，因此請先按下「下一步」。

「將 Firebase 新增至您的網頁應用程式」視窗

然後您會看到安裝 Firebase CLI 的選項。如果尚未安裝，請使用 npm install -g firebase-tools 指令立即安裝。然後點選「下一步」。
然後您會看到登入 Firebase 並部署至 Firebase 託管的選項。請使用 firebase login 指令登入 Firebase，然後按一下「Continue to Console」(繼續前往控制台)。您會在後續步驟中部署至 Firebase 託管。

設定 Firebase 產品

我們要建構的應用程式會使用幾項 Firebase 產品，這些產品都可用於網頁應用程式：

Firebase 驗證：可讓使用者輕鬆登入您的應用程式。
使用 Cloud Firestore 將結構化資料儲存至雲端，並在資料變更時收到即時通知。
Cloud Storage for Firebase，用於在雲端儲存檔案。
Firebase 託管服務，用於代管及提供資產。
Firebase 雲端通訊，用於傳送推播通知及顯示瀏覽器彈出式通知。
Firebase Performance Monitoring，收集應用程式的使用者效能資料。

部分產品需要特殊設定或透過 Firebase 控制台啟用。

如要允許使用者透過 Google 帳戶登入網頁應用程式，請使用 Google 登入方式。

請啟用 Google 登入：

在 Firebase 控制台中，找出左側面板的「Build」部分。
依序點選「Authentication」->「Get Started」(如適用) ->「Sign-in method」分頁標籤 (或按這裡直接前往)。
啟用 Google 登入供應器
將應用程式的公開名稱設為 Friendly Chat，然後從下拉式選單中選擇專案支援電子郵件地址。
點選「儲存」。

設定 Cloud Firestore

這個網路應用程式使用 Cloud Firestore 儲存及接收即時通訊訊息。

如要在 Firebase 專案中設定 Cloud Firestore，請按照下列步驟操作：

在 Firebase 控制台的左側面板中，展開「Build」，然後選取「Firestore database」。
按一下 [Create database] (建立資料庫)。
將「資料庫 ID」保留為 (default)。
選取資料庫位置，然後按一下「下一步」。
如果是實際應用程式，請選擇離使用者較近的位置。
按一下「以測試模式啟動」。請詳閱安全性規則免責事項。
在本程式碼研究室的後續步驟中，您將新增安全性規則，確保資料安全。請勿在未為資料庫新增安全性規則的情況下，公開發布或公開應用程式。
點選「建立」。

設定 Cloud Storage for Firebase

網頁應用程式會使用 Cloud Storage for Firebase 儲存、上傳及分享圖片。

如要在 Firebase 專案中設定 Cloud Storage for Firebase，請按照下列步驟操作：

在 Firebase 主控台的左側面板中，展開「Build」，然後選取「Storage」。
按一下「開始使用」。
選取預設 Storage bucket 的位置。
位於 US-WEST1、US-CENTRAL1 和 US-EAST1 的 bucket 可享有 Google Cloud Storage 的「永久免費」方案。其他所有位置的值區均適用 Google Cloud Storage 定價和用量。
按一下「以測試模式啟動」。請詳閱安全性規則免責事項。
在本程式碼研究室的後續步驟中，您將新增安全性規則來保護資料。請勿在未為 Storage 值區新增安全規則的情況下，公開發布或公開應用程式。
點選「建立」。

4. 設定 Firebase

從 appcheck-start 目錄呼叫：

firebase use --add

系統顯示提示訊息時，請選取專案 ID，然後為 Firebase 專案提供別名。這個專案的別名可以設為 default。接下來，您需要設定本機專案，才能使用 Firebase。

前往 Firebase 控制台中的專案設定
在「您的應用程式」資訊卡中，選取需要設定物件的應用程式暱稱。
從 Firebase SDK 程式碼片段窗格中選取「設定」。
複製設定物件程式碼片段，然後加進 appcheck-start/hosting/src/firebase-config.js。本程式碼研究室的其餘部分會假設變數名為 config。

firebase-config.js

const config = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID",
};

從相同的 appcheck-start 目錄中，呼叫：

firebase experiments:enable webframeworks

這會啟用專案建構時使用的網頁架構支援。

現在應該一切就緒，可以執行專案並測試預設專案是否正常運作！

5. 在不使用 App Check 的情況下試用應用程式

設定應用程式並安裝 SDK 後，請嘗試使用應用程式，看看是否如原先設計。首先，請安裝所有依附元件。在終端機中，前往 appcheck-start/hosting 目錄。在該目錄中執行 npm install。這會擷取專案運作所需的所有依附元件。如要以目前狀態啟動應用程式，可以執行 firebase serve。應用程式會要求你登入 Google 帳戶，請登入帳戶，然後嘗試在即時通訊中發布幾則訊息和幾張相片。

您已在本機測試過，現在可以看看實際運作情況！執行 firebase deploy，將網路應用程式部署到網路上。這是示範 App Check 在現實世界中運作方式的重要步驟，因為需要為 reCAPTCHA Enterprise 認證供應商設定網域。

希望您正在體驗應用程式提供的預設功能。發布即時通訊訊息，以及其他只能透過這類應用程式執行的操作。目前狀態的缺點是，只要有人擁有上一個步驟中的應用程式設定，就能存取後端資源。他們仍須遵守 Firestore 和 Cloud Storage 系統的現行安全規則，但除此之外，他們仍可查詢、儲存及存取儲存在這些系統中的資料。

在接下來的幾個步驟中，您將：

在 App Check 註冊
驗證強制執行
開始強制執行規則

6. 開啟 App Check 和強制執行功能

首先，請為專案取得 reCAPTCHA Enterprise 金鑰，然後將金鑰新增至 App Check。首先，請前往 Google Cloud 控制台的 reCAPTCHA Enterprise 專區。選取專案，系統會提示您啟用 reCAPTCHA Enterprise API。啟用 API，然後等待幾分鐘，讓系統完成作業。然後按一下「企業金鑰」旁的「建立金鑰」。然後在這個部分中指定顯示名稱，並選取「網站」類型金鑰。您必須指定應用程式的託管網域。由於您打算在 Firebase 託管上代管這個應用程式，因此請使用預設代管名稱，通常是 ${YOUR_PROJECT_ID}.web.app。您可以在 Firebase 控制台的「Hosting」部分找到託管網域。填寫完畢後，請依序按下「完成」和「建立金鑰」。

reCAPTCHA 建立金鑰畫面

完成後，「金鑰詳細資料」頁面頂端會顯示 ID。

reCAPTCHA Enterprise 註冊視窗

請將這個 ID 複製到剪貼簿。這是您用於應用程式檢查的金鑰。接著前往 Firebase 控制台的「App Check」部分，然後按一下「開始使用」。然後按一下「註冊」，再按一下「reCAPTCHA Enterprise」，並將複製的 ID 貼到「reCAPTCHA Enterprise 網站金鑰」文字方塊中。其餘設定保留預設值。您的應用程式檢查頁面應如下所示：

您可以在「App Check 應用程式」視窗中註冊 reCAPTCHA Enterprise 權杖

未經驗證和未強制執行的要求

您已在 Firebase 控制台註冊金鑰，現在請執行 firebase serve，返回瀏覽器執行網站。現在您已在本機執行網頁應用程式，可以再次對 Firebase 後端提出要求。由於要求會傳送至 Firebase 後端，App Check 會監控這些要求，但不會強制執行。如要查看傳入要求的狀態，可以前往 Firebase 控制台的「App Check」頁面，然後點選「APIs」分頁標籤中的「Cloud Firestore」部分。由於您尚未設定用戶端使用應用程式檢查，因此應該會看到類似下列內容的訊息：

App Check 資訊主頁顯示您應用程式的未驗證用戶端要求比例為 100%。

後端收到的要求有 100% 未經驗證。這個畫面很有用，因為它顯示幾乎所有用戶端要求都來自未整合 App Check 的用戶端。

這個資訊主頁可顯示幾項資訊，首先，這項指標會指出所有用戶端應用程式是否都執行最新版用戶端。如果是，您就可以放心強制執行 App Check，不必擔心會關閉應用程式正版用戶端的存取權。此外，您也可以藉此瞭解有多少存取後端的嘗試並非來自應用程式。這可能是使用者在您不知情的情況下直接查詢後端。由於您可以看到要求未通過驗證，因此在驗證這些使用者的要求之前，請先瞭解這些使用者可能對後端發出未驗證要求時會發生什麼情況。

未驗證和強制執行的要求

請按下上一個畫面中的「強制執行」按鈕，然後在系統提示時再次按下「強制執行」。

未驗證的指標資訊主頁，醒目顯示「強制執行」按鈕

這會開始強制執行 App Check，現在會封鎖未透過所選認證供應商 (本例為 reCAPTCHA Enterprise) 驗證的後端服務要求。返回執行中的網路應用程式，該應用程式應會在 http://localhost:5000 執行。重新整理頁面後，嘗試從資料庫取得資料時，不會發生任何事。如果您開啟 Chrome 控制台來讀取錯誤，應該會看到類似下列內容的訊息：

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

這是因為 App Check 封鎖了要求，這些要求在傳送至 Firebase 資源時，未通過有效的認證權杖。目前您可以關閉 App Check 強制執行功能，並在下一節中瞭解如何在 Friendly Chat 範例中新增 reCAPTCHA Enterprise App Check。

7. 在網站中新增 reCAPTCHA Enterprise 金鑰

我們會在您的應用程式中加入企業金鑰。首先，請開啟 hosting/src/firebase-config.js，然後將 reCAPTCHA Enterprise 金鑰新增至下列程式碼片段：

const reCAPTCHAEnterpriseKey = {
  // Replace with your recaptcha enterprise site key
  key: "Replace with your recaptcha enterprise site key"
};

完成後，開啟 hosting/src/index.js，在第 51 行新增從 firebase-config.js 匯入的內容，以便擷取 reCAPTCHA 金鑰，並匯入 App Check 程式庫，這樣就能使用 reCAPTCHA Enterprise 提供者。

// add from here
 import {
   initializeAppCheck,
   ReCaptchaEnterpriseProvider,
 } from 'firebase/app-check';
// to here

// replace this line
import { getFirebaseConfig } from './firebase-config.js';
// with this line
import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';

接著，在下一行中建立函式來設定 App Check。函式會先檢查您是否處於開發環境，如果是，則會列印可用於本機開發的偵錯權杖。

import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';
// add from here
 function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
 }
// to here

現在可以初始化 App Check，以便與所選供應商 (本例為 reCAPTCHA Enterprise) 搭配使用。您也會想在背景自動重新整理 App Check 權杖，這樣一來，如果使用者的 App Check 權杖過時，他們與服務互動時就不會發生任何延遲。

function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
// add from here
   // Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
   // site key and pass it to initializeAppCheck().
   initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider(getReCaptchaKey()),
     isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
   });
// to here
 }

最後，確認應用程式已初始化後，您需要呼叫剛才建立的 setupAppCheck 函式。在 hosting/src/index.js 檔案底部，新增對最近新增方法的呼叫。

const firebaseApp = initializeApp(getFirebaseConfig());
// add from here
setupAppCheck(firebaseApp);
// to here
getPerformance();
initFirebaseAuth();
loadMessages();

先在本機測試

請先在本機測試應用程式。如果尚未在本機提供應用程式，請執行 firebase serve。您應該會發現應用程式仍無法在本機載入。這是因為您只向 reCAPTCHA 認證供應商註冊了 Firebase 網域，而未註冊 localhost 網域。您絕不應將 localhost 註冊為核准網域，因為這樣一來，使用者就能從在本機電腦上執行的應用程式存取受限制的後端。不過，由於您設定了 self.FIREBASE_APPCHECK_DEBUG_TOKEN = true，因此您會在 JavaScript 控制台中看到類似下列的程式碼行：

App Check debug token: 55183c20-de61-4438-85e6-8065789265be. You will need to add it to your app's App Check settings in the Firebase console for it to work.

您需要取得提供的偵錯權杖 (在本例中為：55183c20-de61-4438-85e6-8065789265be)，然後在應用程式的溢位選單中，將權杖插入「應用程式檢查設定」。

應用程式檢查資訊主頁，顯示「管理偵錯權杖」的位置

為權杖取一個好記的專屬名稱，然後按一下「儲存」。這個選項可讓您在應用程式中使用用戶端產生的權杖，相較於產生偵錯權杖並嵌入應用程式，這種做法更安全。在應用程式中嵌入權杖可能會導致權杖意外散布給使用者，而這些使用者可能會利用權杖繞過檢查。如要在 CI 環境中發布偵錯權杖，請參閱這份說明文件，進一步瞭解如何發布。

使用別名填入偵錯權杖的範例

在 Firebase 主控台中註冊偵錯權杖後，您就可以重新啟用應用程式檢查強制執行功能，並從終端機呼叫 firebase serve，測試應用程式內容是否會在本地載入。您應該會看到先前輸入的資料，已提供給網頁應用程式的本機版本。您應該仍會看到訊息，且偵錯權杖會列印到控制台。

在正式版中試用

確認 App Check 在本機運作正常後，請將網頁應用程式部署至正式環境。從終端機再次呼叫 firebase deploy，然後重新載入頁面。這會將網頁應用程式封裝起來，以便在 Firebase 託管服務上執行。應用程式託管於 Firebase Hosting 後，請前往 ${YOUR_PROJECT_ID}.web.app 存取應用程式。您可以開啟 JavaScript 控制台，應該不會再看到列印的偵錯權杖，且專案中應該會載入即時通訊。此外，與應用程式互動一段時間後，您可以前往 Firebase 控制台的「App Check」部分，確認對應用程式的要求是否都已改為經過驗證。

8. 恭喜！

恭喜，您已成功將 Firebase App Check 新增至網頁應用程式！

您可以設定 Firebase 控制台，處理實際工作環境的 reCAPTCHA Enterprise 權杖，甚至為本機開發作業設定偵錯權杖。確保應用程式仍可從核准的用戶端存取 Firebase 資源，並防止應用程式內發生詐欺活動。

後續步驟

如要將 Firebase App Check 新增至下列平台，請參閱相關說明文件：