从 FIDO2 迁移到凭据管理器

Credential Manager 支持通行密钥、联合登录和第三方身份验证 provider，是推荐用于在 Android 上进行身份验证的 API，可提供安全便捷的环境，让用户可以同步和管理其凭据。如果您是使用本地 FIDO2 凭据的开发者，则应对您的应用进行更新，通过集成 Credential Manager API 来支持使用通行密钥进行身份验证。本文档介绍了如何将项目从 FIDO2 迁移到 Credential Manager。

从 FIDO2 迁移到 Credential Manager 的原因

在大多数情况下，您应将 Android 应用的身份验证 provider 迁移到 Credential Manager，原因如下：迁移到 Credential Manager 的原因包括：

  • 通行密钥支持：Credential Manager 支持通行密钥，这是一种新的无密码身份验证机制，比密码更安全且更易于使用。
  • 多账号登录方法：Credential Manager 支持多账号登录方法，包括密码、通行密钥和联合登录方法。这样，无论用户首选的身份验证方法如何，都可以更轻松地向您的应用进行身份验证。
  • 第三方凭据 provider 支持：在 Android 14 及更高版本中，Credential Manager 支持多个第三方凭据 provider。这意味着，用户可以使用来自其他 provider 的现有凭据登录您的应用。
  • 一致的用户体验：Credential Manager 可为各种应用和登录机制的身份验证提供更加一致的用户体验。这样，用户就可以更轻松地理解和使用应用的身份验证流程。

如需开始从 FIDO2 迁移到 Credential Manager，请按以下步骤操作。

更新依赖项

  1. 将项目的 build.gradle 中的 Kotlin 插件更新到 1.8.10 或更高版本。

    plugins {
  //…
    id 'org.jetbrains.kotlin.android' version '1.8.10' apply false
  //…
}

  2. 在项目的 build.gradle 中，更新您的依赖项以使用 Credential Manager 和 Play 服务身份验证。

    dependencies {
  // ...
  // Credential Manager:
  implementation 'androidx.credentials:credentials:<latest-version>'

  // Play Services Authentication:
  // Optional - needed for credentials support from play services, for devices running
  // Android 13 and below:
  implementation 'androidx.credentials:credentials-play-services-auth:<latest-version>'
  // ...
}

  3. 将 FIDO 初始化替换为 Credential Manager 始化。在您用于创建通行密钥和登录方法的类中添加此声明：

    val credMan = CredentialManager.create(context)

创建通行密钥

您需要创建新的通行密钥，将其与用户账号相关联，并将通行密钥的公钥存储在您的服务器上，然后用户才能使用该通行密钥进行登录。您可以通过更新寄存器函数调用，将您的应用设置为支持此功能。

图 1. 此图显示了使用 Credential Manager 创建通行密钥时，应用与服务器之间如何交换数据。

  1. 如需获取在创建通行密钥过程中发送到 createCredential() 方法的必要参数，请按照 WebAuthn 规范中所述的方法将 name("residentKey").value("required") 添加到您的 registerRequest() 服务器调用。

    suspend fun registerRequest(sessionId: String ... {
    // ...
    .method("POST", jsonRequestBody {
        name("attestation").value("none")
        name("authenticatorSelection").objectValue {
            name("residentKey").value("required")
        }
    }).build()
    // ...
}

  2. 将 registerRequest() 及所有子函数的 return 类型均设置为 JSONObject。

    suspend fun registerRequest(sessionId: String): ApiResult<JSONObject> {
    val call = client.newCall(
        Request.Builder()
            .url("$BASE_URL/<your api url>")
            .addHeader("Cookie", formatCookie(sessionId))
            .method("POST", jsonRequestBody {
                name("attestation").value("none")
                name("authenticatorSelection").objectValue {
                    name("authenticatorAttachment").value("platform")
                    name("userVerification").value("required")
                    name("residentKey").value("required")
                }
            }).build()
    )
    val response = call.await()
    return response.result("Error calling the api") {
        parsePublicKeyCredentialCreationOptions(
            body ?: throw ApiException("Empty response from the api call")
        )
    }
}

  3. 从您的视图中安全地移除用于处理 intent 启动器和 activity 结果调用的所有方法。

  4. 由于 registerRequest() 现在会返回 JSONObject，因此您无需创建 PendingIntent。将返回的 intent 替换为 JSONObject。更新 intent 启动器调用，以便从 Credential Manager API 调用 createCredential()。调用 createCredential() API 方法。

    suspend fun createPasskey(
    activity: Activity,
    requestResult: JSONObject
    ): CreatePublicKeyCredentialResponse? {
        val request = CreatePublicKeyCredentialRequest(requestResult.toString())
        var response: CreatePublicKeyCredentialResponse? = null
        try {
            response = credMan.createCredential(
                request as CreateCredentialRequest,
                activity
            ) as CreatePublicKeyCredentialResponse
        } catch (e: CreateCredentialException) {

            showErrorAlert(activity, e)

            return null
        }
        return response
    }

  5. 调用成功后，将响应发送回服务器。此调用的请求和响应与 FIDO2 实现类似，因此您无需做出任何更改。

使用通行密钥进行身份验证

设置好通行密钥创建流程后，您可以将应用设置为允许用户使用通行密钥进行登录和身份验证。为此，您需要更新身份验证代码来处理 Credential Manager 结果，并实现一个通过通行密钥进行身份验证的函数。

图 2. Credential Manager 的通行密钥身份验证流程。
  1. 为了获取要发送至 getCredential() 请求的必要信息，您需要向服务器发出登录请求调用，而该请求调用与 FIDO2 实现相同，因此您无需做出任何更改。

  2. 与寄存器请求调用类似，返回的响应采用 JSONObject 格式。

    /**
 * @param sessionId The session ID to be used for the sign-in.
 * @param credentialId The credential ID of this device.
 * @return a JSON object.
 */
suspend fun signinRequest(): ApiResult<JSONObject> {
    val call = client.newCall(Builder().url(buildString {
        append("$BASE_URL/signinRequest")
    }).method("POST", jsonRequestBody {})
        .build()
    )
    val response = call.await()
    return response.result("Error calling /signinRequest") {
        parsePublicKeyCredentialRequestOptions(
            body ?: throw ApiException("Empty response from /signinRequest")
        )
    }
}

/**
 * @param sessionId The session ID to be used for the sign-in.
 * @param response The JSONObject for signInResponse.
 * @param credentialId id/rawId.
 * @return A list of all the credentials registered on the server,
 * including the newly-registered one.
 */
suspend fun signinResponse(
    sessionId: String, response: JSONObject, credentialId: String
    ): ApiResult<Unit> {

        val call = client.newCall(
            Builder().url("$BASE_URL/signinResponse")
                .addHeader("Cookie",formatCookie(sessionId))
                .method("POST", jsonRequestBody {
                    name("id").value(credentialId)
                    name("type").value(PUBLIC_KEY.toString())
                    name("rawId").value(credentialId)
                    name("response").objectValue {
                        name("clientDataJSON").value(
                            response.getString("clientDataJSON")
                        )
                        name("authenticatorData").value(
                            response.getString("authenticatorData")
                        )
                        name("signature").value(
                            response.getString("signature")
                        )
                        name("userHandle").value(
                            response.getString("userHandle")
                        )
                    }
                }).build()
        )
        val apiResponse = call.await()
        return apiResponse.result("Error calling /signingResponse") {
        }
    }

  3. 从您的视图中安全地移除用于处理 intent 启动器和 activity 结果调用的所有方法。

  4. 由于 signInRequest() 现在会返回 JSONObject，因此您无需创建 PendingIntent。将返回的 intent 替换为 JSONObject，然后通过您的 API 方法调用 getCredential()。

    suspend fun getPasskey(
    activity: Activity,
    creationResult: JSONObject
    ): GetCredentialResponse? {
        Toast.makeText(
            activity,
            "Fetching previously stored credentials",
            Toast.LENGTH_SHORT)
            .show()
        var result: GetCredentialResponse? = null
        try {
            val request= GetCredentialRequest(
                listOf(
                    GetPublicKeyCredentialOption(
                        creationResult.toString(),
                        null
                    ),
                    GetPasswordOption()
                )
            )
            result = credMan.getCredential(activity, request)
            if (result.credential is PublicKeyCredential) {
                val publicKeycredential = result.credential as PublicKeyCredential
                Log.i("TAG", "Passkey ${publicKeycredential.authenticationResponseJson}")
                return result
            }
        } catch (e: Exception) {
            showErrorAlert(activity, e)
        }
        return result
    }

  5. 调用成功后，将响应发送回服务器，以进行验证和对用户进行身份验证。此 API 调用的请求和响应参数与 FIDO2 实现类似，因此您无需做出任何更改。

其他资源