Android Play Integrity 踩坑实录：preauth 验证失败 – wiki基地

作者： /

Android Play Integrity 踩坑实录：深入解析 preauth 验证失败的谜团

引言：安全防线上的“隐形杀手”

在当今的移动应用生态中，安全是开发者不可逾越的生命线。无论是防止作弊、保护付费内容，还是确保用户账户安全，我们都需要一道坚固的防线来抵御日益猖獗的攻击行为。Google 推出的 Play Integrity API，作为 SafetyNet Attestation 的继任者，正是这道防线上的核心武器。它能够帮助我们的应用判断是否运行在真实、未受篡改的 Android 设备上，为我们的业务逻辑提供关键的信任依据。

Play Integrity 提供了多种请求类型，其中 requestStandardIntegrityToken 是最常用于保护高价值用户操作（如登录、支付、投票）的利器。为了进一步增强安全性，Google 引入了 preAuthenticationToken（下文简称 preauth 令牌）机制。其设计初衷是：在用户执行敏感操作之前，先获取一个预认证令牌，然后将此令牌与具体操作绑定，生成最终的完整性令牌。这样一来，服务端不仅能验证设备的完整性，还能确保这次完整性检查确实是为即将发生的特定操作而发起的，极大地增强了抗重放攻击和业务逻辑绑定的能力。

然而，理想很丰满，现实很骨感。许多开发者在集成 preauth 流程时，都掉进了一个深不见底的“坑”里：客户端似乎一切正常，令牌也成功获取并发送给了服务器，但服务器在进行解密和验证时，却无情地返回“验证失败”。这个错误就像一个幽灵，信息模糊，难以定位，耗费了开发者大量的时间和精力。本文将以“踩坑实录”的形式，系统性地、深度地剖析 preauth 验证失败的种种原因，并提供一套行之有效的排查方案和最佳实践，希望能为你拨开迷雾，彻底征服这个“隐形杀手”。

第一章：基础概念梳理 —— preauth 令牌究竟是什么？

在深入排查问题之前，我们必须对 Play Integrity，特别是 preauth 令牌的工作流程有清晰、准确的认识。错误的理解是导致错误实现的第一步。

1.1 Play Integrity 的基本流程

一个标准的 Play Integrity 验证流程（不含 preauth）通常如下：

  1. 客户端请求 Nonce：客户端向你的业务服务器请求一个一次性的、随机的字符串，即 Nonce。
  2. 客户端请求 Integrity Token：客户端调用 Play Integrity API，传入从服务器获取的 Nonce，向 Google Play 服务请求一个完整性令牌（Integrity Token）。
  3. 客户端发送 Token：客户端将获取到的 Integrity Token 发送回你的业务服务器。
  4. 服务端验证 Token：你的业务服务器使用从 Google Play Console 获取的解密密钥，对接收到的 Token 进行解密和验证。验证内容包括：
    • 签名校验：确保 Token 是由 Google 签发的，未被篡改。
    • Nonce 校验：确保 Token 中的 Nonce 与服务器之前下发给该客户端的 Nonce 一致，防止重放攻击。
    • Payload 校验：检查解密后的载荷（Payload），如应用信息（包名、证书摘要）、设备完整性状态（deviceIntegrity）、账户信息（accountDetails）等，并根据业务规则做出决策。

1.2 preauth 令牌的引入与工作流变迁

preauth 机制为上述流程增加了“预认证”和“操作绑定”的环节，其设计的核心思想是两步走：

第一步：准备阶段（用户操作前）

当应用预见到用户可能要执行一个敏感操作时（例如，用户进入了支付页面，但还未点击“确认支付”按钮），客户端可以提前向 Google Play 服务请求一个 preauth 令牌。

“`kotlin
// 步骤一：准备预认证令牌
val prepareTokenRequest = PrepareIntegrityTokenRequest.builder()
// 这里可以传入一个 cloudProjectNumber，但对于 preauth 来说是可选的
.setCloudProjectNumber(YOUR_CLOUD_PROJECT_NUMBER)
.build()

integrityManager.prepareIntegrityToken(prepareTokenRequest)
.addOnSuccessListener { prepareTokenResponse ->
// 成功获取 preauth 令牌
val preAuthToken = prepareTokenResponse.token()
// *** 关键：将这个 preAuthToken 暂存起来，等待用户操作 ***
}
.addOnFailureListener { e ->
// 处理获取失败
}

“`

第二步：执行阶段（用户操作时）

当用户真正触发敏感操作时（例如，点击了“确认支付”按钮）：

  1. 客户端向业务服务器请求 Nonce，并附带上本次操作的唯一标识（如订单号）。
  2. 客户端请求标准的 Integrity Token，但这次请求必须包含两个关键参数：
    • 从服务器获取的 Nonce。
    • 在第一步中获取并暂存的 preauth 令牌。

“`kotlin
// 步骤二：用户点击支付按钮后
// 1. 从你的服务器获取一个与本次支付订单绑定的 Nonce
val nonce: String = yourBackend.getNonceForPayment(“order_12345”)

// 2. 构建标准完整性请求，但这次要“喂入” preauth 令牌
val standardTokenRequest = StandardIntegrityTokenRequest.builder()
.setNonce(nonce)
.setPreAuthenticationToken(preAuthToken) // *** 核心：在这里使用 preauth 令牌 ***
.build()

integrityManager.requestStandardIntegrityToken(standardTokenRequest)
.addOnSuccessListener { standardTokenResponse ->
// 成功获取最终的、绑定了 preauth 的 Integrity Token
val finalToken = standardTokenResponse.token()
// 3. 将这个 finalToken 发送到你的服务器进行验证
yourBackend.verifyPayment(finalToken, “order_12345”)
}
.addOnFailureListener { e ->
// 处理获取失败
}
“`

服务端的验证变化：

服务端收到的 finalToken，在解密后的 Payload 中，会额外多出一个 preAuthenticationDetails 字段。这个字段包含了与预认证相关的信息，服务端可以据此进行更严格的校验。

这个流程中最容易被误解、也是导致无数验证失败的核心认知误区是：

误区：preauth 令牌本身是需要发送给服务器验证的。
正解：preauth 令牌是一个中间产物，它仅在客户端使用，作为生成最终 Integrity Token 的一个输入参数。你永远不应该把 preauth 令牌本身发送到服务器进行验证。发送到服务器的，永远是调用 requestStandardIntegrityToken 后生成的那个最终令牌。

搞清楚这个核心概念，我们就已经走出了排查迷宫的第一步。

第二章：踩坑深水区 —— preauth 验证失败的 N 种可能

现在，让我们进入“案发现场”。当你的服务器日志打印出“Invalid signature”、“Decryption failed”或“Payload mismatch”时，不要慌张。这通常不是 Google 服务出了问题，而是我们自己的实现链条上某个环节断裂了。以下是我在实践中总结出的最常见的“坑点”，请逐一排查。

坑点一：令牌混淆 —— 将“介绍信”当成了“通行证”

这是最常见，也是最令人啼笑皆非的错误，源于对 preauth 流程的根本性误解。

  • 症状：客户端调用 prepareIntegrityToken 获得了 preAuthToken，然后直接将这个 preAuthToken 发送给了服务器。
  • 原因：服务器的解密逻辑是为标准的 Integrity Token 设计的。preAuthToken 的格式、加密方式、签名密钥都与最终的 Integrity Token 完全不同。用解密最终令牌的逻辑去解密一个 preauth 令牌，结果必然是失败。
  • 解决方案：
    1. 客户端自查：确认你的代码逻辑是否严格遵循了“两步走”流程。检查发送给服务器的令牌，是否来自于 requestStandardIntegrityToken 的成功回调，而不是 prepareIntegrityToken。
    2. 日志埋点：在客户端获取 preAuthToken 和 finalToken 的地方分别打印日志，并在发送网络请求前打印即将发送的令牌内容。通过对比日志，可以快速定位是否传错了令牌。

坑点二：服务端解密与验证逻辑错误

即使客户端发送了正确的最终令牌，服务端的处理逻辑也可能出错。

  • 症状：服务器报告签名无效或解密失败。

  • 原因分析与解决方案：

    1. 密钥错误：

      • 确认密钥来源：用于解密和验证的密钥，必须从 Google Play Console -> 应用完整性 -> Integrity API 页面获取。它是一个 Base64 编码的加密公钥。
      • 密钥管理：确保你在服务器代码中使用的密钥是最新、最完整的。复制粘贴时不要有任何遗漏或多余的字符/空格。
      • 环境隔离：如果你有开发、测试、生产多套环境，请确保每个环境的应用（不同包名或签名）都对应了其在 Play Console 中的正确密钥。

    2. 解密库使用不当：

      • 推荐官方方案：Google 官方提供了用于在服务端处理令牌的示例代码（通常是 Java 或其他语言）。强烈建议直接使用或参考这个官方实现。它使用了 Google 的 Tink 加密库，能够正确处理令牌的加密和签名格式（JWE/JWS）。
      • 避免使用通用 JWT 库：Play Integrity 令牌的结构比标准 JWT 更复杂。直接用一个通用的 JWT 库去解析，很可能会因为不识别其加密封装（Encryption envelope）而失败。

    3. 代码逻辑 bug：

      • 检查你服务端代码中处理 Base64 编码、JSON 解析的部分。令牌字符串在网络传输中是否被意外转义或修改？
      • 仔细阅读并理解官方示例代码中的每一步：如何加载密钥、如何构建解密器/验证器、如何调用解密/验证方法。

坑点三：Google Cloud 项目编号不匹配

这是一个非常隐蔽但致命的坑。

  • 症状：一切看起来都对，但验证就是失败。尤其是在从旧的 SafetyNet API 迁移过来时容易发生。
  • 原因：在客户端调用 Play Integrity API 时，你需要通过 .setCloudProjectNumber() 指定一个 Google Cloud 项目编号。这个项目编号必须与你在 Google Play Console 中为你的应用关联的那个 Google Cloud 项目完全一致。如果两者不匹配，Google 的后台会用一个项目的密钥对令牌进行签名，而你的服务器拿着另一个项目（Play Console 关联的）的公钥去验证，自然会失败。

  • 解决方案：

    1. 找到正确的项目编号：
      • 登录 Google Play Console。
      • 选择你的应用，进入 “设置” -> “开发者帐号详情”，或者在 “API 访问权限” 页面，找到关联的 Google Cloud 项目。
      • 登录对应的 Google Cloud Console，在首页的“项目信息”卡片中找到“项目编号”（Project Number），它是一串纯数字。
    2. 客户端代码确认：确保你在客户端 IntegrityTokenRequest 的构建器中设置的是这个正确的项目编号。

    kotlin
    // 客户端代码务必使用正确的项目编号
    .setCloudProjectNumber(123456789012) // 替换成你自己的

坑点四：Nonce 的生命周期与一致性问题

虽然 preauth 的引入是为了增强绑定，但 Nonce 的作用依然至关重要。

  • 症状：服务器解密成功，但发现 Payload 中的 nonce 与预期不符。
  • 原因：
    1. Nonce 未绑定操作：服务器在生成 Nonce 时，没有与具体的用户操作（如订单 ID）进行绑定和存储。导致客户端用这个 Nonce 请求了令牌后，服务器无从查证这个 Nonce 是否合法。
    2. Nonce 复用：Nonce 必须是一次性的。如果一个 Nonce 被用于多次请求，除了第一次之外，后续所有请求都应被视为重放攻击而拒绝。
    3. 客户端与服务器状态不一致：例如，客户端在网络不佳时重试操作，重新向服务器请求了一个新的 Nonce，但由于某种原因，它在调用 Play Integrity API 时仍然使用了旧的 Nonce。
  • 解决方案：
    • 服务端：
      • 生成 Nonce 时，应将其与一个唯一的操作 ID（如 orderId）关联，并设置一个较短的过期时间（例如 5 分钟）。可以存入 Redis 或类似缓存中。
      • 当收到客户端发来的 finalToken 后，解密出 nonce，根据 nonce 或 orderId 查出预期的 nonce 值进行比对。
      • 验证通过后，立即将该 Nonce 从存储中删除或标记为已使用。
    • 客户端：
      • 确保每次发起敏感操作流程时，都向服务器请求一个新的 Nonce。
      • 管理好 Nonce 的状态，避免在重试或复杂的回调逻辑中用错了 Nonce。

坑点五：环境与构建配置的差异

开发环境一切正常，一到线上就出问题？检查你的构建配置。

  • 症状：仅在特定构建变体（如 Release）或分发渠道（如从 Play Store 下载）上出现验证失败。
  • 原因：
    1. 应用签名不一致：Play Integrity 的结果与应用的签名证书指纹（certificateSha256Digest）强相关。你在本地用 debug key 签名的应用，和上传到 Play Store 后由 Google Play App Signing 签名的应用，其证书是不同的。服务器端的验证逻辑如果硬编码了 debug 证书的指纹，线上版本自然会验证失败。
    2. 代码混淆（ProGuard/R8）：如果混淆规则不当，可能会移除掉 Play Integrity SDK 或其依赖的某些必要类，导致运行时错误。
  • 解决方案：
    • 签名问题：
      • 在 Play Console 的“应用完整性”页面，可以找到由 Google Play 管理的发布证书的 SHA-256 指纹。
      • 服务器在验证 Payload 时，应该允许一个证书指纹列表，至少包含你的上传证书和 Google Play 的签名证书。
    • 混淆问题：
      • 确保你的 proguard-rules.pro 文件中包含了 Google 官方或相关库推荐的 keep 规则。对于 Play Core Library，通常需要保留一些特定的类。一个通用的规则可能是：
        -keep class com.google.android.play.core.** { *; }
        -dontwarn com.google.android.play.core.**
      • 在 Release 构建版本上进行充分测试。

第三章：拨乱反正 —— 正确的 preauth 实现路径

理论和坑点都分析完了，现在我们来梳理一下端到端的、无坑的最佳实践。

3.1 客户端（Android）正确流程

场景：用户准备进行一次价值 10 元的虚拟商品购买。

  1. 进入购买页面（准备阶段）

    “`kotlin
    class PurchaseActivity : AppCompatActivity() {
    private var preAuthToken: String? = null
    private lateinit var integrityManager: IntegrityManager

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...
    integrityManager = IntegrityManagerFactory.create(applicationContext)
    prepareForPurchase()
}

private fun prepareForPurchase() {
    val prepareTokenRequest = PrepareIntegrityTokenRequest.builder()
        .setCloudProjectNumber(YOUR_CLOUD_PROJECT_NUMBER)
        .build()

    integrityManager.prepareIntegrityToken(prepareTokenRequest)
        .addOnSuccessListener { response ->
            this.preAuthToken = response.token()
            // UI上可以启用支付按钮了
            binding.payButton.isEnabled = true
        }
        .addOnFailureListener { e ->
            // 获取预认证令牌失败，UI上提示用户稍后重试
            Log.e("Integrity", "Prepare token failed", e)
            // ...
        }
}
// ...

    }
    “`

  2. 用户点击“确认支付”按钮（执行阶段）

    “`kotlin
    // 在 PurchaseActivity 中
    fun onPayButtonClicked() {
    val currentPreAuthToken = this.preAuthToken
    if (currentPreAuthToken == null) {
    // preAuthToken 还未准备好，提示用户
    return
    }

    // 1. 向你的服务器请求与本次交易绑定的 Nonce
// 伪代码
val orderId = "ORDER_UNIQUE_ID_123"
yourApi.getNonce(orderId) { nonce ->
    if (nonce != null) {
        // 2. 请求最终的 Integrity Token
        requestFinalToken(nonce, currentPreAuthToken)
    } else {
        // 获取 Nonce 失败
    }
}

    }

    private fun requestFinalToken(nonce: String, preAuthToken: String) {
    val standardTokenRequest = StandardIntegrityTokenRequest.builder()
    .setNonce(nonce)
    .setPreAuthenticationToken(preAuthToken)
    .build()

    integrityManager.requestStandardIntegrityToken(standardTokenRequest)
    .addOnSuccessListener { response ->
        val finalToken = response.token()
        // 3. 将 finalToken 和 orderId 发送到服务器
        yourApi.verifyPurchase(finalToken, "ORDER_UNIQUE_ID_123") { success ->
            // 处理支付结果
        }
    }
    .addOnFailureListener { e ->
        Log.e("Integrity", "Request standard token failed", e)
        // ...
    }

    }
    “`

3.2 服务端（以 Java/Kotlin 伪代码为例）正确流程

  1. 接收请求并验证

    “`java
    @PostMapping(“/verifyPurchase”)
    public ResponseEntity verifyPurchase(@RequestBody PurchaseRequest request) {
    String finalToken = request.getFinalToken();
    String orderId = request.getOrderId();

    try {
    // 1. 从 Play Console 获取的 Base64 编码的公钥
    String integrityDecryptionKey = "YOUR_DECRYPTION_KEY_BASE64";
    String integrityVerificationKey = "YOUR_VERIFICATION_KEY_BASE64";

    // 2. 使用官方推荐的库或逻辑进行解密和验证
    // 这里的 'IntegrityTokenVerifier' 是一个假设的类，代表了官方的验证逻辑
    IntegrityTokenVerifier verifier = new IntegrityTokenVerifier.Builder()
            .setDecryptionKey(integrityDecryptionKey)
            .setVerificationKey(integrityVerificationKey)
            .build();

    String decryptedPayloadJson = verifier.verifyAndDecrypt(finalToken);

    // 3. 解析 Payload
    IntegrityPayload payload = new Gson().fromJson(decryptedPayloadJson, IntegrityPayload.class);

    // 4. --- 核心校验逻辑 ---

    // 4.1 校验 Nonce
    String expectedNonce = nonceService.getNonceForOrder(orderId);
    if (!payload.getRequestDetails().getNonce().equals(expectedNonce)) {
        throw new SecurityException("Nonce mismatch!");
    }
    // 验证通过后，立即使 Nonce 失效
    nonceService.invalidateNonce(expectedNonce);

    // 4.2 校验应用信息
    if (!payload.getAppIntegrity().getPackageName().equals("YOUR_PACKAGE_NAME")) {
        throw new SecurityException("Package name mismatch!");
    }
    // ... 其他应用信息校验，如证书指纹

    // 4.3 校验设备完整性
    String deviceVerdict = payload.getDeviceIntegrity().getDeviceRecognitionVerdict().get(0);
    if (!deviceVerdict.equals("MEETS_DEVICE_INTEGRITY")) {
         // 根据业务策略处理，不一定是失败，可能是风险提示
         // ...
    }

    // 4.4 *** 校验 preauth 信息 ***
    // 这是 preauth 流程的关键！
    if (payload.getPreAuthenticationDetails() == null) {
        // 如果启用了 preauth 流程，这里就不应该为空
        throw new SecurityException("PreAuthentication details are missing!");
    }

    // 这里可以添加更复杂的逻辑，比如检查 preauth token 的生成时间等
    // 但最基本的检查是它必须存在

    // 所有校验通过，处理发货逻辑
    orderService.fulfillOrder(orderId);

    return ResponseEntity.ok("Purchase successful!");

} catch (Exception e) {
    // 记录详细错误日志
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Verification failed: " + e.getMessage());
}

    }
    “`

结论：细节决定成败

Play Integrity 的 preauth 机制是一个强大的安全工具，但它的实现链条长，涉及客户端、业务服务器和 Google Play 服务三方，任何一个环节的微小偏差都可能导致“验证失败”这个令人沮丧的结果。

回顾我们的踩坑之旅，可以总结出几个核心要点：

  1. 清晰理解流程：preauth 令牌是“过程”，不是“结果”，它只在客户端内部流转，用于生成最终的 Integrity Token。
  2. 细心核对配置：Google Cloud 项目编号、应用签名、解密密钥，这些静态配置信息必须百分之百准确无误。
  3. 信任但要验证：服务端是最终的决策者。必须对解密后的 Payload 进行全面、严格的校验，包括 Nonce、应用信息、设备状态，以及最重要的 preAuthenticationDetails 是否存在。
  4. 善用官方资源：优先使用 Google 提供的官方示例代码和服务端库，它们能帮你避免很多底层加密实现的坑。

安全无小事。当你下一次遇到 preauth 验证失败时，希望这篇详尽的“踩坑实录”能成为你手中的那份排错地图，帮助你从容不迫地定位问题，最终构建起坚不可摧的应用安全防线。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部