為 Cloud Functions 啟用 App Check 強制執行功能

瞭解 App Check 對使用者的影響並準備好繼續後，即可為可呼叫函式啟用 App Check 強制執行。

啟用強制執行功能

如要在可呼叫函式中開始強制執行 App Check 權杖規定，請修改函式以檢查有效的 App Check 權杖，如下所示。強制執行後，所有未經驗證的要求都會遭到拒絕。

1. 安裝 Cloud Functions SDK。

   Node.js (第 2 代)

   將專案的 firebase-functions 依附元件更新至 4.0.0 以上版本：

   npm install firebase-functions@">=4.0.0"

   Node.js (第 1 代)

   將專案的 firebase-functions 依附元件更新至 4.0.0 以上版本：

   npm install firebase-functions@">=4.0.0"

   Python (預先發布版)

   將 firebase-functions 新增至 functions/requirements.txt：

   firebase-functions >= 0.1.0
   

   接著，更新專案虛擬環境中的依附元件：

   ./venv/bin/pip install -r requirements.txt
   

2. 為函式啟用 App Check 強制執行執行階段選項：

   Node.js (第 2 代)

   const { onCall } = require("firebase-functions/v2/https");
   
   exports.yourV2CallableFunction = onCall(
     {
       enforceAppCheck: true, // Reject requests with missing or invalid App Check tokens.
     },
     (request) => {
       // request.app contains data from App Check, including the app ID.
       // Your function logic follows.
       ...
     }
   );
   

   Node.js (第 1 代)

   const functions = require("firebase-functions/v1");
   
   exports.yourV1CallableFunction = functions
     .runWith({
         enforceAppCheck: true, // Reject requests with missing or invalid App Check tokens.
     })
     .https.onCall((data, context) => {
           // context.app contains data from App Check, including the app ID.
           // Your function logic follows.
           ...
     });
   

   Python (預先發布版)

   from firebase_functions import https_fn
   
   @https_fn.on_call(
       enforce_app_check=True  # Reject requests with missing or invalid App Check tokens.
   )
   def your_callable_function(req: https_fn.CallableRequest) -> https_fn.Response:
       # req.app contains data from App Check, including the app ID.
       # Your function logic follows.
       ...
   

3. 重新部署函式：

   firebase deploy --only functions
   

部署這些變更後，可呼叫函式就必須使用有效的 App Check 權杖。呼叫可呼叫函式時，Cloud Functions 用戶端 SDK 會自動附加 App Check 權杖。

重送攻擊防護 (Beta 版)

為保護可呼叫函式免於重播攻擊，您可以在驗證 App Check 權杖後使用該權杖。權杖一經使用即無法再次使用。

請注意，使用重播保護機制會在權杖驗證中新增網路往返行程，因此會增加函式呼叫的延遲時間。因此，大多數應用程式通常只會在特別敏感的端點上啟用重播保護機制。

如要使用權杖，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，將「Firebase App Check Token Verifier」角色授予函式使用的服務帳戶。

   • 如果您明確初始化 Admin SDK，並指定專案的 Admin SDK 服務帳戶憑證，系統會自動授予必要角色。
   • 如果您使用第 1 代 Cloud Functions，且採用預設的 Admin SDK 設定，請將角色授予 App Engine 預設服務帳戶。請參閱「變更服務帳戶權限」。
   • 如果您使用第 2 代 Cloud Functions，且採用預設的 Admin SDK 設定，請將角色授予預設運算服務帳戶。

2. 在函式定義中，將 consumeAppCheckToken 設為 true：

   Node.js (第 2 代)

   const { onCall } = require("firebase-functions/v2/https");
   
   exports.yourV2CallableFunction = onCall(
     {
       enforceAppCheck: true, // Reject requests with missing or invalid App Check tokens.
       consumeAppCheckToken: true  // Consume the token after verification.
     },
     (request) => {
       // request.app contains data from App Check, including the app ID.
       // Your function logic follows.
       ...
     }
   );
   

   Node.js (第 1 代)

   const functions = require("firebase-functions/v1");
   
   exports.yourV1CallableFunction = functions
     .runWith({
         enforceAppCheck: true, // Reject requests with missing or invalid App Check tokens.
         consumeAppCheckToken: true  // Consume the token after verification.
     })
     .https.onCall((data, context) => {
         // context.app contains data from App Check, including the app ID.
         // Your function logic follows.
         ...
     });
   

3. 更新應用程式用戶端程式碼，在呼叫函式時取得可消耗的有限用途權杖：

   Swift

   let options = HTTPSCallableOptions(requireLimitedUseAppCheckTokens: true)
   let yourCallableFunction =
       Functions.functions().httpsCallable("yourCallableFunction", options: options)
   do {
       let result = try await yourCallableFunction.call()
   } catch {
       // ...
   }
   

   Kotlin

   val yourCallableFunction = Firebase.functions.getHttpsCallable("yourCallableFunction") {
       limitedUseAppCheckTokens = true
   }
   val result = yourCallableFunction.call().await()
   

   Java

   HttpsCallableReference yourCallableFunction = FirebaseFunctions.getInstance().getHttpsCallable(
           "yourCallableFunction",
           new HttpsCallableOptions.Builder()
                   .setLimitedUseAppCheckTokens(true)
                   .build()
   );
   Task<HttpsCallableResult> result = yourCallableFunction.call();
   

   Web

   import { getFunctions, httpsCallable } from "firebase/functions";
   
   const yourCallableFunction = httpsCallable(
     getFunctions(),
     "yourCallableFunction",
     { limitedUseAppCheckTokens: true },
   );
   await yourCallableFunction();