在 Android 上使用 Play Integrity 啟用應用檢查

此頁面向您展示如何使用內置的 Play Integrity 提供程序在 Android 應用程序中啟用應用程序檢查。當您啟用 App Check 時，您有助於確保只有您的應用可以訪問您項目的 Firebase 資源。請參閱此功能的概述。

目前，內置的 Play Integrity 提供程序僅支持由 Google Play 分發的 Android 應用程序。要使用 Play Integrity 的 off-Play 功能，或將 App Check 與您自己的自定義提供程序一起使用，請參閱實現自定義應用程序檢查提供程序。

1. 設置您的 Firebase 項目

1. 如果您還沒有這樣做，請將 Firebase 添加到您的 Android 項目中。

2. 啟用 Play Integrity API：

   1. 在Google Play Console中，選擇您的應用程序，或者如果您還沒有這樣做，請添加它。

   2. 在發布部分，單擊設置 > 應用程序完整性。

   3. 在Integrity API頁面上，點擊Link project ，然後從 Google Cloud 項目列表中選擇您的 Firebase 項目。

      您在此處選擇的項目必須與您在其中註冊應用的 Firebase 項目相同（請參閱下一步）。

3. 在 Firebase 控制台的App Check部分註冊您的應用以使用 Play Integrity 提供程序使用 App Check。您需要提供應用簽名證書的 SHA-256 指紋。

   您通常需要註冊項目的所有應用，因為一旦您為 Firebase 產品啟用強制執行，只有已註冊的應用才能訪問該產品的後端資源。

4. 可選：在應用註冊設置中，為提供商發布的應用檢查令牌設置自定義生存時間 (TTL)。您可以將 TTL 設置為 30 分鐘到 7 天之間的任何值。更改此值時，請注意以下權衡：

   • 安全性：較短的 TTL 可提供更強的安全性，因為它減少了洩露或攔截的令牌可能被攻擊者濫用的窗口。
   • 性能：較短的 TTL 意味著您的應用將更頻繁地執行證明。由於應用程序證明過程每次執行都會增加網絡請求的延遲，因此較短的 TTL 可能會影響應用程序的性能。
   • 配額和成本：較短的 TTL 和頻繁的重新證明會更快地耗盡您的配額，而對於付費服務，可能會花費更多。請參閱配額和限制。

   對於大多數應用程序來說， 1 小時的默認 TTL 是合理的。請注意，App Check 庫以大約一半的 TTL 持續時間刷新令牌。

2. 將 App Check 庫添加到您的應用程序

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.2.0')

    // Declare the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

dependencies {
    // Declare the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity:16.0.0'
}

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.2.0')

    // Declare the dependency for the App Check library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

dependencies {
    // Declare the dependency for the App Check library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-appcheck-playintegrity:16.0.0'
}

3.初始化應用檢查

將以下初始化代碼添加到您的應用中，以便它在您使用任何其他 Firebase SDK 之前運行：

FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance());

FirebaseApp.initializeApp(/*context=*/this)
val firebaseAppCheck = FirebaseAppCheck.getInstance()
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance()
)

在您的應用中安裝 App Check 庫後，開始將更新的應用分發給您的用戶。

更新後的客戶端應用將開始向 Firebase 發出的每個請求發送 App Check 令牌，但 Firebase 產品不需要令牌有效，直到您在 Firebase 控制台的 App Check 部分啟用強制執行。有關詳細信息，請參閱接下來的兩節。

4. 監控請求指標

現在您的更新應用已在用戶手中，您可以為您使用的 Firebase 產品啟用應用檢查。但是，在您這樣做之前，您應該確保這樣做不會破壞您現有的合法用戶。

實時數據庫、Cloud Firestore 和 Cloud Storage

您可以用來為實時數據庫、Cloud Firestore 和 Cloud Storage 做出此決定的一個重要工具是應用檢查請求指標屏幕。

要查看產品的 App Check 請求指標，請打開 Firebase 控制台的App Check部分。例如：

每個產品的請求指標分為四類：

• 已驗證的請求是那些具有有效 App Check 令牌的請求。啟用 App Check 強制執行後，只有此類別中的請求才會成功。

• 過時的客戶端請求是那些缺少 App Check 令牌的請求。這些請求可能來自應用檢查未包含在應用中之前的舊版 Firebase SDK。

• 未知來源請求是那些缺少應用檢查令牌的請求，它們看起來不像來自 Firebase SDK。這些請求可能來自使用被盜 API 密鑰發出的請求，也可能來自未使用 Firebase SDK 發出的偽造請求。

• 無效請求是那些具有無效應用檢查令牌的請求，這些請求可能來自試圖模擬您的應用的不真實客戶端，或來自模擬環境。

當您決定啟用強制執行時，您的應用程序的這些類別的分佈應通知您。以下是一些指導方針：

• 如果幾乎所有最近的請求都來自經過驗證的客戶端，請考慮啟用強制措施以開始保護您的後端資源。

• 如果最近的請求中有很大一部分來自可能已過時的客戶端，為避免干擾用戶，請考慮等待更多用戶更新您的應用，然後再啟用強制執行。對已發布的應用程序強制執行應用程序檢查將破壞未與應用程序檢查 SDK 集成的先前應用程序版本。

• 如果您的應用尚未啟動，您應該立即啟用應用檢查強制，因為沒有任何過時的客戶端在使用中。

雲函數

對於 Cloud Functions，您可以通過檢查函數的日誌來獲取 App Check 指標。每次調用可調用函數都會發出一個結構化日誌條目，如下例所示：

{
  "severity": "INFO",    // INFO, WARNING, or ERROR
  "logging.googleapis.com/labels": {"firebase-log-type": "callable-request-verification"},
  "jsonPayload": {
    "message": "Callable header verifications passed.",
    "verifications": {
      // ...
      "app": "MISSING",  // VALID, INVALID, or MISSING
    }
  }
}

您可以通過使用以下指標過濾器創建基於日誌的計數器指標，在 Google Cloud Console 中分析這些指標：

resource.type="cloud_function"
resource.labels.function_name="YOUR_CLOUD_FUNCTION"
resource.labels.region="us-central1"
labels.firebase-log-type="callable-request-verification"

使用字段jsonPayload.verifications.appCheck標記指標。

5. 啟用強制執行

要啟用強制執行，請按照以下每種產品的說明進行操作。為產品啟用強制執行後，對該產品的所有未經驗證的請求都將被拒絕。

實時數據庫、Cloud Firestore 和 Cloud Storage

要為實時數據庫、Cloud Firestore（iOS 和 Android）和 Cloud Storage 啟用強制執行：

1. 打開 Firebase 控制台的應用檢查部分。

2. 展開您要為其啟用強制執行的產品的指標視圖。

3. 單擊強制並確認您的選擇。

請注意，啟用強制實施後最多可能需要 15 分鐘才能生效。

雲函數

請參閱為 Cloud Functions 啟用應用檢查強制。

下一步

如果在您為 App Check 註冊了您的應用程序後，您希望在 App Check 通常不會歸類為有效的環境中運行您的應用程序，例如開發期間的模擬器或持續集成 (CI) 環境，您可以創建使用 App Check 調試提供程序而不是真正的證明提供程序的應用程序的調試版本。

請參閱在 Android 上通過調試提供程序使用 App Check 。