App Check 網站程式碼研究室

1. 簡介

上次更新時間：2023-02-23

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

您可以使用 Firebase App Check 防止未授權的用戶端存取後端資源，方法是要求傳入的要求附上認證，證明要求來自您的正版應用程式，並封鎖未經適當認證的流量。Firebase App Check 會依賴平台專屬的認證服務供應商來驗證用戶端的真實性：對於網頁應用程式，App Check 支援 reCAPTCHA v3 和 reCAPTCHA Enterprise 做為認證服務供應商。

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

建構項目

在本程式碼研究室中，您將先新增再強制執行 App Check，藉此保護聊天應用程式。

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

課程內容

  • 如何監控後端是否有未經授權的存取行為
  • 如何在 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 專案

  1. 登入 Firebase。
  2. 在 Firebase 控制台中，按一下「新增專案」，然後將 Firebase 專案命名為 FriendlyChat。請記下 Firebase 專案的專案 ID。
  3. 取消勾選「為這項專案啟用 Google Analytics」
  4. 按一下「建立專案」。

我們要建構的應用程式會使用可用於網頁應用程式的 Firebase 產品：

  • Firebase 驗證：可讓使用者輕鬆登入您的應用程式。
  • Cloud Firestore 可將結構化資料儲存在雲端，並在資料變更時立即通知您。
  • Cloud Storage for Firebase，可將檔案儲存在雲端。
  • Firebase 代管功能可代管及提供素材資源。
  • Firebase 雲端通訊，用於傳送推播通知和顯示瀏覽器彈出式通知。
  • Firebase 效能監控，收集應用程式的使用者效能資料。

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

升級 Firebase 定價方案

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

  • 您必須提供付款方式 (例如信用卡)，才能建立 Cloud Billing 帳戶。
  • 如果您是 Firebase 和 Google Cloud 的新手，請確認您是否符合$300 美元的抵免額和免費試用 Cloud Billing 帳戶的資格。
  • 如果您是為了參加活動而進行這個程式碼研究室，請向活動主辦單位詢問是否有任何 Cloud 抵用金。

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

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

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

  1. 按一下網頁圖示 58d6543a156e56f9.png，建立新的 Firebase 網頁應用程式。
  2. 使用「Friendly Chat」這個別名註冊應用程式，然後勾選「Also set up Firebase Hosting for this app」旁的方塊。按一下「Register app」。
  3. 在下一個步驟中，您會看到使用 npm 和設定物件安裝 Firebase 的指令。您稍後會在程式碼研究室中複製這個物件，因此目前請按下「Next」。

將 Firebase 新增至網頁應用程式視窗

  1. 接著，您會看到安裝 Firebase CLI 的選項。如果您尚未安裝，請立即使用 npm install -g firebase-tools 指令進行安裝。然後點選「下一步」。
  2. 接著，您會看到登入 Firebase 並部署至 Firebase 託管的選項。請使用 firebase login 指令登入 Firebase，然後按一下「Continue to Console」。您會在後續步驟中部署至 Firebase 代管服務。

為 Firebase 驗證啟用 Google 登入

為了讓使用者可以使用 Google 帳戶登入網頁應用程式，我們會使用 Google 登入方式。

您必須啟用 Google 登入：

  1. 在 Firebase 控制台中，找出左側面板中的「建構」專區。
  2. 依序點選「驗證」和「開始使用」(如適用)，然後點選「登入方式」分頁標籤 (或按這裡直接前往)。
  3. 啟用 Google 登入供應器
  4. 將應用程式的公開名稱設為 Friendly Chat，然後從下拉式選單中選擇專案支援電子郵件地址。
  5. 點選「儲存」。

f96888973c3d00cc.png

設定 Cloud Firestore

這個網頁應用程式會使用 Cloud Firestore 儲存即時通訊訊息，並接收新的即時通訊訊息。

以下說明如何在 Firebase 專案中設定 Cloud Firestore：

  1. 在 Firebase 主控台的左側面板中展開「Build」，然後選取「Firestore database」。
  2. 按一下 [Create database] (建立資料庫)。
  3. 將「資料庫 ID」設為 (default)。
  4. 選取資料庫的位置，然後按一下「Next」。
    如果是實際應用程式，請選擇距離使用者較近的位置。
  5. 按一下「以測試模式啟動」。請詳閱安全性規則免責事項。
    在本程式碼研究室的後續部分，您將新增安全性規則來保護資料。請勿發布或公開應用程式，除非您已為資料庫新增安全性規則。
  6. 按一下「建立」。

設定 Cloud Storage for Firebase

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

以下說明如何在 Firebase 專案中設定 Cloud Storage for Firebase：

  1. 在 Firebase 主控台的左側面板中，展開「Build」，然後選取「Storage」。
  2. 按一下「開始使用」。
  3. 選取預設儲存體值區的位置。
    US-WEST1、US-CENTRAL1 和 US-EAST1 中的值區可使用 Google Cloud Storage 的「永遠免費」方案。其他所有位置的值區都會遵循 Google Cloud Storage 的定價和用量。
  4. 按一下「以測試模式啟動」。請詳閱安全性規則免責事項。
    在本程式碼研究室的後續部分，您將新增安全性規則來保護資料。請勿發布或公開應用程式，否則請為儲存空間值區新增安全規則。
  5. 按一下「建立」。

4. 設定 Firebase

從 appcheck-start 目錄呼叫：

firebase use --add

系統顯示提示時，請選取專案 ID，然後為 Firebase 專案指定別名。對於這個專案，您可以直接指定「預設」別名。接下來，您需要設定本機專案，讓其與 Firebase 搭配運作。

  1. 前往 Firebase 主控台中的專案設定
  2. 在「您的應用程式」資訊卡中，選取需要設定物件的應用程式別名。
  3. 在 Firebase SDK 程式碼片段窗格中選取「Config」。
  4. 複製設定物件程式碼片段，然後將其新增至 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. 在未使用應用程式檢查功能的情況下試用應用程式

設定應用程式和 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，並稍候幾分鐘讓 API 完成啟用。然後點選「企業金鑰」旁的「建立金鑰」。接著，在這個部分指定顯示名稱，並選取「網站」類型金鑰。您必須指定應用程式託管的網域。由於您打算在 Firebase 託管中代管這個資源，因此請使用預設的代管名稱，通常為 ${YOUR_PROJECT_ID}.web.app。您可以在 Firebase 控制台的「託管」部分下方找到託管網域。填妥資訊後，請按一下「完成」和「建立金鑰」。

reCAPTCHA 建立金鑰畫面

完成後，您會在「重要詳細資料」頁面頂端看到 ID。

reCAPTCHA Enterprise 註冊視窗

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

註冊 reCAPTCHA Enterprise 權杖的 App Check 應用程式視窗

未驗證且未強制執行的要求

在 Firebase 控制台中註冊了金鑰後，請返回瀏覽器執行 firebase serve，這裡的網頁應用程式會在本機執行，您可以開始再次向 Firebase 後端提出要求。由於要求會傳送至 Firebase 後端，因此 App Check 會監控這些要求，但不會強制執行。如要查看傳入要求的狀態，請前往 Firebase 控制台的「App Check」頁面，在「API」分頁中查看「Cloud Firestore」部分。由於您尚未設定用戶端使用 App Check，因此畫面應會顯示類似下列的內容：

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 註冊為已核准的網域，因為這會讓使用者透過在本機上執行的應用程式存取受限制的後端。由於您已設定 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)，並將其插入應用程式溢出選單下方的應用程式檢查設定。

顯示「管理偵錯權杖」位置的 App Check 資訊主頁

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

使用別名填入偵錯符記的範例

在 Firebase 主控台註冊偵錯權杖後，您可以重新啟用 App Check 強制執行機制，並透過終端機呼叫 firebase serve，測試應用程式內容是否會在本機載入。您應該會看到先前輸入的資料，會傳送至本機版本的網路應用程式。您應該會看到訊息，並在控制台中顯示偵錯符記。

在實際工作環境中試用

確認 App Check 在本機運作正常後，即可將網頁應用程式部署至正式環境。再次從終端機呼叫 firebase deploy，然後重新載入頁面。這項操作會將您的網頁應用程式封裝，以便在 Firebase 代管服務上執行。應用程式託管於 Firebase 託管服務後，請嘗試前往 ${YOUR_PROJECT_ID}.web.app 瀏覽應用程式。您可以開啟 JavaScript 控制台，應該不會再看到輸出的偵錯符記，而且應該會看到專案中載入的即時通訊。此外，在與應用程式互動一段時間後，您可以前往 Firebase 控制台的「應用程式檢查」部分，驗證應用程式要求是否已全部改為驗證狀態。

8. 恭喜！

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

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

後續步驟

請參閱下列說明文件，瞭解如何將 Firebase App Check 新增至：

參考文件