使用 Credential Manager 实现恢复凭据

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

版本兼容性

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

前提条件

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

依赖项

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

Kotlin

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

Groovy

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

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

概览

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

// 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：此值会将密钥保存在本地，而不是云端。 如果用户选择从云端恢复，则无法在新设备上使用该密钥。

处理凭据创建响应

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

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

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

使用恢复密钥登录

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

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

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

获取恢复密钥

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

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

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

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

// 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)

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

处理登录响应

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

删除恢复密钥

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)