使用 Credential Manager 实现恢复凭据

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

版本兼容性

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

前提条件

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

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

依赖项

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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

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

概览

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

创建恢复密钥

在用户向您的应用完成身份验证后（即登录后立即创建，或者在用户已登录的情况下，在后续应用启动期间创建），创建恢复密钥。

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

实例化 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() 方法，来创建恢复密钥。

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 格式保存公钥凭据注册响应。

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

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

• CreateRestoreCredentialDomException：如果 requestJson 无效且不遵循 PublicKeyCredentialCreationOptionsJSON 的 WebAuthn 格式，则会发生此异常。
• E2eeUnavailableException：如果 isCloudBackupEnabled 为 true，但用户设备没有数据备份或端到端加密功能（例如屏幕锁定），则会发生此异常。
• IllegalArgumentException：如果 createRestoreRequest 为空或不是有效的 JSON，或者如果它没有符合 WebAuthn 规范的有效 user.id，则会发生此异常。

使用恢复密钥登录

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

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

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

获取恢复密钥

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

在以下情况下，您可以获取恢复密钥：

• （推荐）在应用数据恢复后立即执行。使用 BackupAgent 配置应用的备份，并在 onRestore 回调中完成 getCredential 功能，以确保在恢复应用数据后立即恢复应用的凭据。这样可以避免用户首次打开新设备时可能出现的延迟，并让用户无需等待您的应用打开即可进行互动。
• 在设备上首次启动应用时。

如需在用户首次在新设备上打开应用之前向其发送通知，请在 BackupAgent 的 onRestore 回调中提取恢复密钥。这对于即时通讯应用或通信应用尤其重要。

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

凭据管理器 API 会返回 GetCredentialResponse 类型的响应。此响应包含公钥。

处理登录响应

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

注意： 尽管恢复密钥和通行密钥使用相同的底层服务器实现，但在应用服务器的数据库中保存它们时，请区分它们。如果存在通行密钥管理页面，则此区别至关重要，因为用户可以直接管理用户创建的通行密钥，而恢复密钥由系统管理，并且在通行密钥管理页面中处于隐藏状态。

删除恢复密钥

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

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

只有在以下情况下，恢复密钥才会被移除：

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)