Android 设置与后端验证

使用的 Android 原生系统

在 Android 上，此插件使用 Google Play Integrity Standard API:

• prepareIntegrityToken 在 prepare()
• requestStandardIntegrityToken 来实现 createAttestation() 以及 createAssertion()

要求

• 通过 Google Play 生态系统分发的 Android 应用
• 设备上已安装 Google Play services
• 应用已启用 Play Integrity API
• 已配置 Google Cloud 项目编号

Google 设置

1. 启用 Play Integrity API 在您的 Google Cloud 项目中。
2. 打开 Play Console 并为您的应用配置 Play Integrity 访问权限。
3. 提供 cloudProjectNumber 给插件。

Capacitor 配置

capacitor.config.ts

plugins: {
  AppAttest: {
    cloudProjectNumber: '123456789012',
  },
}

你也可以通过 cloudProjectNumber 在方法选项中进行单次调用。

客户端流程

import { AppAttest } from '@capgo/capacitor-app-attest';

const { keyId } = await AppAttest.prepare({
  cloudProjectNumber: '123456789012',
});

const attestation = await AppAttest.createAttestation({
  keyId,
  challenge: 'backend-registration-challenge',
});

const assertion = await AppAttest.createAssertion({
  keyId,
  payload: 'backend-request-payload',
});

token 是一个 Play Integrity token，必须在服务端进行解码。

后端工作流 (Android)

注册（createAttestation)

1. 后端创建一次性 challenge.
2. App 调用 createAttestation({ keyId, challenge }).
3. 后端调用 Google decodeIntegrityToken API。
4. 后端至少验证以下内容：
   • requestDetails.requestHash === base64url(SHA256(challenge))
   • appIntegrity.packageName 与您的 Android application id 一致
   • appIntegrity.certificateSha256Digest 包含您的 release signing cert digest
   • integrity verdicts 符合您的安全策略

请求保护（createAssertion)

1. 后端创建一次性 payload.
2. App 调用 createAssertion({ keyId, payload }).
3. 后端解码 Token 并检查 requestHash === base64url(SHA256(payload)).
4. 强制执行重放攻击防护（单次使用 + TTL）及完整性判定策略。

Android Schema

sequenceDiagram
  participant App as Android App
  participant Plugin as AppAttest plugin
  participant PlaySDK as Play Integrity SDK
  participant BE as Backend
  participant Google as decodeIntegrityToken API

  App->>Plugin: prepare(cloudProjectNumber)
  Plugin->>PlaySDK: prepareIntegrityToken()
  PlaySDK-->>Plugin: provider handle (keyId)

  BE->>App: one-time challenge
  App->>Plugin: createAttestation(keyId, challenge)
  Plugin->>PlaySDK: requestStandardIntegrityToken(requestHash)
  PlaySDK-->>Plugin: integrity token
  Plugin-->>App: token + platform + format + keyId
  App->>BE: token + challenge + keyId
  BE->>Google: decodeIntegrityToken(token)
  Google-->>BE: decoded payload
  BE->>BE: verify requestHash + app identity + verdicts

  BE->>App: one-time payload
  App->>Plugin: createAssertion(keyId, payload)
  Plugin->>PlaySDK: requestStandardIntegrityToken(requestHash)
  PlaySDK-->>Plugin: integrity token
  App->>BE: token + payload + keyId
  BE->>Google: decodeIntegrityToken(token)
  Google-->>BE: decoded payload
  BE->>BE: verify requestHash + replay policy

最小后端 payload 契约

注册：

{
  "platform": "android",
  "format": "google-play-integrity-standard",
  "keyId": "string",
  "challenge": "string",
  "token": "string"
}

断言：

{
  "platform": "android",
  "format": "google-play-integrity-standard",
  "keyId": "string",
  "payload": "string",
  "token": "string"
}

从 Android 设置与后端验证继续

如果你正在使用 Android 设置与后端验证 来规划安全与合规，请结合 使用 @capgo/capacitor-app-attest 用于“使用 @capgo/capacitor-app-attest”中的原生能力， 加密 了解 Encryption 的实现细节， 合规性 了解合规部分的实现细节， Capgo 安全扫描器 用于 Capgo Security Scanner 中的产品工作流，以及 Capgo 安全 用于 Capgo Security 中的产品工作流。