从 Ionic Identity Vault 迁移

Native Biometric 是 Ionic Identity Vault 中安全凭据库（credential-vault）部分的完整替代方案。它不仅能提供生物识别 prompt，还能利用原生 Keychain 或 Keystore 保护机制实现凭据的保存、校验、检索和删除。启用生物识别访问控制后，在应用获取凭据前，必须通过 Face ID、Touch ID 或 Android 生物识别进行受保护的读取操作。

对于 token 和凭据库流程，请直接使用 Native Biometric。应用可以自行决定何时发起受保护的读取请求，以应用其超时和生命周期策略。如果你还需要一个用于存储凭据以外数据的通用加密数据库，可以添加 快速 SQL 或 SQLite 数据存储；这对于凭据库迁移是可选的。

自动超时锁定和后台隐私屏属于应用层策略，因此请在应用中保留或重新实现它们。Native Biometric 不支持自定义密码和仅内存模式的 vault；如果需要这些功能，请使用独立的应用程序存储和加密设计。

Capgo 替换方案概览

Ionic Enterprise 插件	Capgo 替换	迁移指南
安全存储	@capgo/capacitor-fast-sql 或 @capgo/capacitor-data-storage-sqlite	Secure Storage 迁移
身份验证连接	@capgo/capacitor-social-login	Auth Connect 迁移
Identity Vault credential-vault 工作流	@capgo/capacitor-native-biometric — 直接替换	您当前的位置

Native Biometric 的功能范围

• 安全的凭据库： 用于保存、检索、检查和删除服务器或账户的凭据。
• 生物识别解锁控制： getSecureCredentials 在读取受保护的凭据前，显示原生的生物识别 prompt。
• 应用控制的锁定策略： 可在应用恢复、超时后或执行敏感操作前，调用受保护的读取操作。
• 独立的身份验证 prompt： verifyIdentity 在 iOS 上支持设备密码回退；受保护的凭据读取仍仅限生物识别。
• 访问控制选项： 选择生物识别注册变更是否会导致受保护的凭据失效。

迁移步骤

1. 安装 Native Biometric 并同步原生 code。

npm install @capgo/capacitor-native-biometric
npx cap sync

2. 保存 access token、refresh token 或其他凭据 并启用生物识别访问控制。
3. 使用 getSecureCredentials 以解锁受保护的凭据 在应用恢复、闲置超时后或执行敏感操作前。
4. 请在应用层保留超时和隐私屏（privacy-screen）逻辑。 Native Biometric 不支持自定义密码和仅内存模式；如有需要，请使用独立的存储与加密设计。
5. 使用 isCredentialsSaved 和 deleteCredentials 用于 onboarding、锁定状态及登出流程。
6. 在首次启动时迁移存储的密钥 通过从 Identity Vault 读取并使用 Native Biometric 进行写入。
7. 移除 Ionic Identity Vault 从你的依赖项和原生配置中移除。

下一步

• Native Biometric 入门指南
• Secure Storage 迁移
• Auth Connect 迁移

从 Migrate from Ionic Identity Vault 继续

如果你正在使用 从 Ionic Identity Vault 迁移 以规划安全与合规，并将其与 加密 以了解 Encryption 中的实现细节， 合规性 有关 Compliance 中的实现细节， Capgo 安全扫描器 关于 Capgo Security Scanner 的产品工作流， Capgo 安全性 关于 Capgo Security 的产品工作流，以及 Capgo 信托中心 关于 Capgo Trust Center 的产品工作流。