使用 Credential Manager 实现恢复凭据

本页面介绍了如何创建恢复密钥、使用恢复密钥登录以及删除恢复密钥。

Android skills

在 GitHub 上查看

恢复凭据

使用 Android skill 通过 Credential Manager 实现恢复凭据备份和恢复流程。

如需从 Android CLI 安装 skill，请运行以下命令：

android skills add --skill restore-credentials

版本兼容性

Credential Manager 的恢复凭据功能适用于搭载 Android 9 及更高版本、Google Play 服务 (GMS) 核心版本 24220000 或更高版本以及 androidx.credentials 库 1.5.0 或更高版本的设备。

前提条件

设置一个依赖方服务器，类似于通行密钥的服务器。如果您已设置 服务器 来处理使用通行密钥进行身份验证，请对恢复密钥使用相同的服务器端实现。

**注意** ：虽然通行密钥和恢复 密钥的服务器端实现相同，但您的客户端应用可以支持恢复密钥，而无需支持通行密钥。 由于恢复密钥独立于应用中的身份验证方法（例如密码或使用 Google 账号登录）运行，因此您无需对应用代码中的现有身份验证方法进行任何其他更改。

依赖项

将以下依赖项添加到应用模块的 build.gradle 文件中：

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

androidx.credentials 库 1.5.0 及更高版本提供恢复凭据功能。不过，建议尽可能使用依赖项的最新稳定版本。

**注意**： 无论是否在manifest中设置 allowBackup，恢复凭据功能都可以正常运行。

概览

1. 创建恢复密钥：如需创建恢复密钥，请完成以下步骤：
   1. 实例化 Credential Manager：创建一个 CredentialManager 对象。
   2. **从应用服务器获取凭据创建选项** ：向 客户端应用发送从应用 服务器创建恢复密钥所需的详细信息。
   3. 创建恢复密钥：如果用户已登录您的应用，则为其 账号创建恢复密钥。
   4. 处理凭据创建响应：将凭据 从客户端应用发送到应用服务器进行处理，并处理所有 异常。
2. 使用恢复密钥登录：如需使用恢复密钥登录， 请完成以下步骤：
   1. **从应用服务器获取凭据检索选项** ：向 客户端应用发送从 应用服务器检索恢复密钥所需的详细信息。
   2. 获取恢复密钥：当用户设置新设备时，向 Credential Manager 请求恢复密钥。这样，用户无需输入其他信息即可登录。
   3. **处理凭据检索响应**：将恢复密钥 从客户端应用发送到应用服务器，以供用户登录。
3. 删除恢复密钥。

创建恢复密钥

您的应用应涵盖用户登录的所有情况，以确保为活跃用户创建恢复密钥。在以下情况下创建恢复密钥：

• 如果用户已登录，但尚未创建恢复密钥（例如，在主 Activity 的 onCreate 方法中）。
• 当用户登录或完成新账号注册流程时。

为了优化性能并避免在每次登录时创建或检查恢复凭据的开销，请在本地存储空间中设置 boolean 标志或凭据创建时间戳（例如 has_synced_restore_credential），以跟踪密钥是否已创建。

注意 ：恢复密钥与应用的唯一软件包名称绑定。如果贵组织的主应用和子应用具有不同的软件包名称，请为每个应用分别创建恢复密钥。

实例化 Credential Manager

使用应用 activity 上下文来实例化 CredentialManager 对象。

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

从应用服务器获取凭据创建选项

在应用服务器中使用符合 FIDO 标准的库，向客户端应用发送创建恢复凭据所需的信息，例如有关用户、应用和其他配置属性的信息。如需详细了解服务器端实现，请参阅服务器端 指南。

创建恢复密钥

解析服务器发送的公钥创建选项后，通过将这些选项封装在 CreateRestoreCredentialRequest对象中，并使用CredentialManager对象调用 createCredential()方法，来创建 恢复密钥。

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

代码要点

• CreateRestoreCredentialRequest 对象包含以下字段：

  • requestJson：应用服务器以 Web Authentication API格式发送的凭据创建选项，适用于 PublicKeyCredentialCreationOptionsJSON。

  • isCloudBackupEnabled：Boolean 字段，用于确定是否应将恢复密钥备份到云端。默认情况下，此标志为 true。此字段具有以下值：

    • true：（推荐 ）如果用户启用了 Google 备份和端到端加密（例如屏幕锁定），则此值会启用将恢复密钥备份到云端的功能。
    • false：此值会将密钥保存在本地，而不是云端。如果用户选择从云端恢复，则新设备上没有该密钥。
  注意： 建议将 isCloudBackupEnabled 设置为 true。如果停用了云端 备份，并且用户从云端备份恢复，则 检索恢复密钥的调用会失败。使用云端备份 恢复应用的用户不会收到恢复密钥，也不会 自动登录。

处理凭据创建响应

Credential Manager API 会返回 CreateRestoreCredentialResponse 类型的响应。此响应以公钥 凭据注册响应的JSON 格式保存。

将公钥从应用发送到依赖方服务器。此公钥类似于您创建通行密钥时生成的公钥。在服务器上处理通行密钥创建的同一代码也可以处理恢复密钥创建。如需详细了解服务器端实现，请参阅 the 通行密钥指南。

在恢复密钥创建过程中，处理以下异常：

• CreateRestoreCredentialDomException：如果 requestJson 无效且不遵循 PublicKeyCredentialCreationOptionsJSON 的 WebAuthn 格式，则会发生此异常。
• E2eeUnavailableException：如果 isCloudBackupEnabled 为 true，但用户的设备没有数据备份或端到端加密（例如屏幕锁定），则会发生此异常。
  为了确保在所有情况下都创建恢复凭据，您必须通过将 isCloudBackupEnabled 设置为 true 来调用 createCredential，以明确处理 E2eeUnavailableException。如果抛出 E2eeUnavailableException，请捕获并再次调用 createCredential，并将 isCloudBackupEnabled 设置为 false。
• IllegalArgumentException：如果 createRestoreRequest 为空或不是有效的 JSON，或者没有符合 WebAuthn 规范的有效 user.id，则会发生此异常。

使用恢复密钥登录

使用恢复凭据在设备设置过程中静默登录用户。

从应用服务器获取凭据检索选项

向客户端应用发送从服务器获取恢复密钥所需的选项。 如需了解此步骤的类似通行密钥指南，请参阅使用通行密钥登录。 如需详细了解服务器端实现，请参阅服务器端 身份验证指南。

获取恢复密钥

如需在新设备上获取恢复密钥，请对 CredentialManager 对象调用 getCredential() 方法。

建议在以下两种情况下都提取恢复密钥：

• 在设备上首次启动应用时。在这种情况下，凭据恢复独立于应用数据恢复。
• 如果启用了应用数据备份和恢复，请在应用数据恢复后立即获取恢复密钥。使用 BackupAgent 配置您的 应用的备份，并确保在 getCredential 功能 中完成 onRestoreFinished 回调。请勿使用 onRestore 方法，因为它仅针对键值备份调用，而 onRestoreFinished 可靠地针对任何类型的备份恢复调用。 这样可以避免用户首次打开新设备时可能出现的延迟，并让用户无需等待打开应用即可与应用互动。例如，这样一来，您的应用就可以在用户首次在新设备上打开应用之前向其发送通知，这对于消息传递或通信应用尤其重要。

重要提示 ：检索恢复凭据后，通知不会自动 恢复。如果您使用 Firebase 处理通知，则必须提取 Firebase Cloud Messaging (FCM) 令牌并将其发送到后端，才能成功恢复后台消息传递和通知。

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

凭据管理器 API 会返回 GetCredentialResponse 类型的响应。此响应中包含的凭据明确为 RestoreCredential 类型，其中包含公钥。

处理登录响应

将公钥从应用发送到依赖方服务器，然后可以使用该公钥登录用户。在服务器端，此操作类似于使用通行密钥登录。在服务器上处理使用通行密钥登录的同一代码也可以处理使用恢复密钥登录。如需详细了解 通行密钥的服务器端实现，请参阅使用通行密钥登录。

注意： 即使恢复密钥和通行密钥使用相同的底层服务器 实现，在应用服务器的 数据库中保存它们时也要区分它们。当存在通行密钥管理页面时，这种区分至关重要，因为用户可以直接管理用户创建的通行密钥，而恢复密钥由系统管理，并且在通行密钥管理页面中隐藏。

删除恢复密钥

Credential Manager 是无状态的，不知道用户活动，因此不会自动删除已使用的恢复密钥。如需删除恢复密钥，请调用 clearCredentialState() 方法。为了安全起见，请在用户退出时删除密钥。这样可确保用户下次在同一设备上打开应用时，系统会将其退出，并提示其再次登录。

卸载应用会被解读为有意从相应设备中删除对应的恢复密钥，类似于用户退出时的意图。

仅在以下情况下移除恢复密钥：

• 系统级操作：用户卸载应用或清除其数据。
• 应用级调用：在应用代码中处理用户退出账号操作时，通过调用 clearCredentialState()以编程方式删除密钥。

当用户退出应用时，对 CredentialManager 对象调用 clearCredentialState() 方法。

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)