在 Android 上使用自定义提供程序启用 App Check

此页面向您展示如何使用您的自定义 App Check 提供程序在 Android 应用中启用 App Check。当您启用 App Check 时,您有助于确保只有您的应用可以访问您项目的 Firebase 资源。

如果您想将 App Check 与默认的 Play Integrity 提供程序一起使用,请参阅在 Android 上使用 Play Integrity 启用 App Check

在你开始之前

1. 将 App Check 库添加到您的应用中

在您的模块(应用级)Gradle 文件(通常是app/build.gradle )中,声明 App Check Android 库的依赖项:

Java

dependencies {
    implementation 'com.google.firebase:firebase-appcheck:16.0.0'
}

Kotlin+KTX

dependencies {
    implementation 'com.google.firebase:firebase-appcheck:16.0.0'
}

2.实现App Check接口

首先,您需要创建实现AppCheckProviderAppCheckProviderFactory接口的类。

您的AppCheckProvider类必须有一个 getToken getToken()方法,该方法收集您的自定义 App Check 提供程序作为真实性证明所需的任何信息,并将其发送到您的令牌获取服务以换取 App Check 令牌。 App Check SDK 处理令牌缓存,因此始终在您的getToken()实现中获取新令牌。

Java

public class YourCustomAppCheckToken extends AppCheckToken {
    private String token;
    private long expiration;

    YourCustomAppCheckToken(String token, long expiration) {
        this.token = token;
        this.expiration = expiration;
    }

    @NonNull
    @Override
    public String getToken() {
        return token;
    }

    @Override
    public long getExpireTimeMillis() {
        return expiration;
    }
}

public class YourCustomAppCheckProvider implements AppCheckProvider {
    @Override
    public Task<AppCheckToken> getToken() {
        // Logic to exchange proof of authenticity for an App Check token and
        //   expiration time.
        // ...

        // Refresh the token early to handle clock skew.
        long expMillis = expirationFromServer * 1000 - 60000;

        // Create AppCheckToken object.
        AppCheckToken appCheckToken =
                YourCustomAppCheckToken(tokenFromServer, expMillis);

        return appCheckToken;
    }
}

Kotlin+KTX

class YourCustomAppCheckToken(
    private val token: String,
    private val expiration: Long
) : AppCheckToken() {
    override fun getToken(): String {
        return token
    }

    override fun getExpireTimeMillis(): Long {
        return expiration
    }
}

class YourCustomAppCheckProvider : AppCheckProvider {
    val token: Task<AppCheckToken>
        get() {
            // Logic to exchange proof of authenticity for an App Check token.
            // ...

            // Refresh the token early to handle clock skew.
            val expMillis: Long = expirationFromServer * 1000 - 60000

            // Create AppCheckToken object.
            val appCheckToken: AppCheckToken =
                    YourCustomAppCheckToken(tokenFromServer, expMillis)

            return appCheckToken!
        }
}

此外,实现一个AppCheckProviderFactory类来创建您的AppCheckProvider实现的实例:

Java

public class YourCustomAppCheckProviderFactory implements AppCheckProviderFactory {
  @Override
  public AppCheckProvider create(FirebaseApp firebaseApp) {
    // Create and return an AppCheckProvider object.
    return new YourCustomAppCheckProvider(firebaseApp);
  }
}

Kotlin+KTX

class YourCustomAppCheckProviderFactory : AppCheckProviderFactory {
    fun create(firebaseApp: FirebaseApp): AppCheckProvider {
        // Create and return an AppCheckProvider object.
        return YourCustomAppCheckProvider(firebaseApp)
    }
}

3.初始化应用检查

将以下初始化代码添加到您的应用中,以便它在您使用任何其他 Firebase SDK 之前运行:

Java

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

Kotlin+KTX

FirebaseApp.initializeApp(/*context=*/ this)
val firebaseAppCheck = FirebaseAppCheck.getInstance()
firebaseAppCheck.installAppCheckProviderFactory(
    YourCustomAppCheckProviderFactory.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 启用应用检查强制