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,请按以下步骤操作。
更新依赖项
将项目的 build.gradle 中的 Kotlin 插件更新到 1.8.10 或更高版本。
plugins { //… id 'org.jetbrains.kotlin.android' version '1.8.10' apply false //… }
在项目的 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>' // ... }
将 FIDO 初始化替换为 Credential Manager 始化。在您用于创建通行密钥和登录方法的类中添加此声明:
val credMan = CredentialManager.create(context)
创建通行密钥
您需要创建新的通行密钥,将其与用户账号相关联,并将通行密钥的公钥存储在您的服务器上,然后用户才能使用该通行密钥进行登录。您可以通过更新寄存器函数调用,将您的应用设置为支持此功能。
如需获取在创建通行密钥过程中发送到
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() // ... }
将
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") ) } }
从您的视图中安全地移除用于处理 intent 启动器和 activity 结果调用的所有方法。
由于
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 }
调用成功后,将响应发送回服务器。此调用的请求和响应与 FIDO2 实现类似,因此您无需做出任何更改。
使用通行密钥进行身份验证
设置好通行密钥创建流程后,您可以将应用设置为允许用户使用通行密钥进行登录和身份验证。为此,您需要更新身份验证代码来处理 Credential Manager 结果,并实现一个通过通行密钥进行身份验证的函数。
- 为了获取要发送至
getCredential()
请求的必要信息,您需要向服务器发出登录请求调用,而该请求调用与 FIDO2 实现相同,因此您无需做出任何更改。 与寄存器请求调用类似,返回的响应采用 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") { } }
从您的视图中安全地移除用于处理 intent 启动器和 activity 结果调用的所有方法。
由于
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 }
调用成功后,将响应发送回服务器,以进行验证和对用户进行身份验证。此 API 调用的请求和响应参数与 FIDO2 实现类似,因此您无需做出任何更改。
其他资源
- Credential Manager 示例参考文档
- Credential Manager Codelab
- 借助 Credential Manager API 让应用可通过通行密钥顺畅地进行身份验证
- FIDO2 Codelab