Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

认证转移

借助 Credential Manager 的 Credentials Transfer API，用户可以在同一设备上安全地在凭据提供程序之间转移用户凭据。本指南详细介绍了 Android 上的凭据提供程序如何与 androidx.credentials:providerevents 库提供的 API 集成。此功能使用标准化的 FIDO 凭证交换格式 (CXF)，支持密码、通行密钥、地址信息和自定义字段。

核心概念

凭据传输框架有助于在同一设备上进行点对点凭据传输，而不会向 Android OS 或未经身份验证的应用公开原始凭据。

该框架定义了两个主要角色：

导出方（来源提供程序）：当前持有用户凭证的凭证提供程序。它会向系统预注册有关可导出账号 (ExportEntry) 的元数据，并在用户选择时响应转移请求。
导入器（客户端提供程序或设置向导）：发起导入请求 (ImportCredentialsRequest) 的凭证提供程序或设置向导，用于指定它可以接收哪些类型的凭证和扩展程序。

Android 版本兼容性

Credentials Transfer API 适用于搭载 Android 8（API 级别 26）及更高版本的设备。

添加依赖项

将 androidx.credentials:providerevents 依赖项添加到模块的 build.gradle 或 build.gradle.kts：

dependencies {
    implementation("androidx.credentials:providerevents:1.0.0-alpha06")
}

实例化所需的类

创建所需 ProviderEventsManager 的实例。

val providerEventsManager = ProviderEventsManager.create(context)

实现导出器

如需允许用户将凭据从您的应用导出到设备上的其他凭据提供程序，请实现导出程序角色。

注册导出条目

当凭证提供程序发生变化（例如，用户登录、添加凭证或修改账号）时，请使用 ProviderEventsManager.registerExport() 注册或更新 ExportEntry 项。

每个 ExportEntry 都需要：

id：一个随机生成的机密字符串标识符，用于唯一表示此导出条目。您必须安全地持久保存此 ID；稍后您将需要使用它来验证传入的转移请求。
accountDisplayName：可选账号标签（例如 "Personal Account"）。
userDisplayName：用户的主要标识符（例如 "alice@example.com"）。
icon：代表提供方或账号的 Bitmap 图标（由库自动缩放为 32x32 PNG）。
supportedCredentialTypes：CredentialTypes 中的一组字符串常量，表示此条目包含的类型。

suspend fun registerMyProviderForExport(
    providerEventsManager: ProviderEventsManager,
    providerIcon: Bitmap,
    // Randomly generated and stored in encrypted storage
    secretEntryId: String
) {
    val entry = ExportEntry(
        id = secretEntryId,
        accountDisplayName = "MyProvider Personal",
        userDisplayName = "alice@example.com",
        icon = providerIcon,
        supportedCredentialTypes = setOf(
            CredentialTypes.CREDENTIAL_TYPE_BASIC_AUTH, // Passwords
            CredentialTypes.CREDENTIAL_TYPE_PUBLIC_KEY, // Passkeys
            CredentialTypes.CREDENTIAL_TYPE_ADDRESS,
            CredentialTypes.CREDENTIAL_TYPE_CREDIT_CARD
        )
    )

    // RegisterExportRequest.create() attaches the default WASM matcher from assets
    val request = RegisterExportRequest.create(context, listOf(entry))

    try {
        val response = providerEventsManager.registerExport(request)
        // Registration successful
    } catch (e: Exception) {
        // Handle registration exceptions (e.g., RegisterExportProviderConfigurationException)
    }
}

在清单文件中声明导出器 activity

当用户在系统选择器界面上选择您的 ExportEntry 时，系统会启动您指定的处理 Activity。使用强制性 intent 操作和内容 URI scheme 声明此 Activity。

为了防范未经授权的调用和混淆代理攻击，请在 Android 14（API 级别 34）及更高版本上声明 android:requireContentUriPermissionFromCaller="write"。这会指示 Android 操作系统在允许启动 activity 之前，先验证发起启动的调用方是否具有对目标内容 URI 的写入权限，如以下示例所示：

<activity
    android:name="com.example.CredentialExportActivity"
    android:exported="true"
    android:requireContentUriPermissionFromCaller="write"
    android:label="@string/export_activity_label">
    <intent-filter>
        <!-- This intent action is required for Credential Manager to invoke this activity -->
        <action android:name="androidx.identitycredentials.action.IMPORT_CREDENTIALS" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="content" />
    </intent-filter>
</activity>

在 activity 中处理转移 intent

在 CredentialExportActivity 中，使用 IntentHandler.retrieveProviderImportCredentialsRequest(intent) 解析请求、验证调用组件和请求元数据、执行任何必需的生物识别验证，并将 FIDO CXF 载荷写回提供的内容 URI。

对请求进行身份验证

由于您的 activity 已导出，因此请通过验证以下每个层来保护凭据导出流程：

验证 credId 会话 Nonce（主要防御措施）：注册 ExportEntry 时，生成一个加密随机、高熵的 id (Nonce)，并将其与短期会话相关联。在您的 activity 中，验证 request.credId 是否与提供程序之前发出的有效、未过期的会话 Nonce 匹配。由于第三方应用无法猜测此 Nonce，因此这可确保 intent 对应于系统选择器上的真实用户选择。
验证 Activity.getCallingPackage()（调用方检查）：由于凭据选择器会使用 startActivityForResult 启动您的 activity，因此您的 activity 可以检查 getCallingPackage()，以确认启动界面的直接调用方是可信的系统凭据选择器框架（在搭载 Google Play 服务的 Android 设备上，为 "com.google.android.gms"）。如果调用软件包无法识别，请拒绝请求。
检查 request.callingAppInfo（目标应用信息）：callingAppInfo 用于标识将接收导入凭据的目标应用。您可以根据需要使用这些信息来提高透明度（例如在确认界面中显示目标应用的名称和图标），或验证目标应用是否可信。

class CredentialExportActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. Extract the transfer request from the incoming Intent
        val request: ProviderImportCredentialsRequest? =
            IntentHandler.retrieveProviderImportCredentialsRequest(intent)

        if (request == null) {
            finishWithError()
            return
        }

        // 2. Validate CallingAppInfo and secret `credId`
        val callingAppPackage = request.callingAppInfo.packageName
        val receivedCredId = request.credId
        if (!verifySecretEntryId(receivedCredId) || !isTrustedImporter(callingAppPackage)) {
            // Secret ID mismatch or untrusted caller -> abort
            sendExceptionAndFinish(ImportCredentialsNoExportOptionException("Unauthorized request"))
            return
        }

        // 3. Optional: Prompt user for Biometric / PIN authentication before exporting
        authenticateUserThenExport(request)
    }

    private fun authenticateUserThenExport(request: ProviderImportCredentialsRequest) {
        // ... Biometric prompt logic ...
        // Once authenticated, generate the FIDO CXF JSON string matching the requested types
        val cxfJsonPayload = buildFidoCxfJsonPayload(
            requestedTypes = request.request.credentialTypes,
            requestedExtensions = request.request.knownExtensions
        )

        val response = ImportCredentialsResponse(cxfJsonPayload)

        // 4. Write the JSON payload to the Content URI and set Activity result
        IntentHandler.setImportCredentialsResponse(
            context = this,
            uri = request.uri,
            intent = intent,
            response = response
        )
        setResult(Activity.RESULT_OK, intent)
        finish()
    }

    private fun sendExceptionAndFinish(exception: androidx.credentials.providerevents.exception.ImportCredentialsException) {
        IntentHandler.setImportCredentialsException(intent, exception)
        setResult(Activity.RESULT_OK, intent)
        finish()
    }

    private fun verifySecretEntryId(credentialId: String): Boolean {
        // Check if credentialId matches what you stored when calling RegisterExportRequest
        return credentialId == getStoredSecretEntryId()
    }

    private fun isTrustedImporter(packageName: String): Boolean {
        // Implement any specific allowlisting / caller checks if required
        return true
    }

    private fun finishWithError() {
        setResult(Activity.RESULT_CANCELED)
        finish()
    }
}

导出注册和清除异常

此模块中的所有异常都是 ImportCredentialsException、RegisterExportException 或 ClearExportException 的子类。

RegisterExportProviderConfigurationException 或 ClearExportProviderConfigurationException：当注册或清除因提供程序设置问题（例如 ExportEntry 中的 supportedCredentialTypes 为空，或在不受支持的操作系统层级上调用）而失败时抛出。
RegisterExportUnknownErrorException 或 ClearExportUnknownErrorException：更新导出注册表时发生未分类的系统或存储错误。

实现导入器

如需将凭证导入您的应用（例如，在新手入门或提供方导入期间），请实现导入器角色，并通过调用 ProviderEventsManager.importCredentials() 启动流程。

构建导入请求并启动流程

指定导入器支持的 CredentialTypes 和 KnownExtensions：

suspend fun startCredentialImport(
    activityContext: Context,
    providerEventsManager: ProviderEventsManager
) {
    val importRequest = ImportCredentialsRequest(
        credentialTypes = setOf(
            CredentialTypes.CREDENTIAL_TYPE_BASIC_AUTH,
            CredentialTypes.CREDENTIAL_TYPE_PUBLIC_KEY,
            CredentialTypes.CREDENTIAL_TYPE_ADDRESS,
            CredentialTypes.CREDENTIAL_TYPE_NOTE
        ),
        knownExtensions = setOf(
            KnownExtensions.KNOWN_EXTENSION_SHARED
        )
    )

    try {
        // Launches the system Selector UI; suspends until user selects a provider and completes transfer
        val response = providerEventsManager.importCredentials(activityContext, importRequest)

        // 1. Inspect the source exporter's package info
        val exporterPackageName = response.callingAppInfo.packageName

        // 2. Parse the FIDO CXF JSON string
        val cxfJsonString = response.response.responseJson
        parseAndSaveImportedCredentials(cxfJsonString)
    } catch (e: ImportCredentialsException) {
        // Handle specific import exceptions (e.g., ImportCredentialsCancellationException)
        handleImportFailure(e)
    }
}

private fun parseAndSaveImportedCredentials(cxfJsonString: String) {
    val rootJson = JSONObject(cxfJsonString)
    // Parse according to FIDO Credential Exchange Format (CXF v1.0) specification:
    // https://fidoalliance.org/specs/cx/cxf-v1.0-ps-20250814.html
}

// Helper function to make it compile
private fun handleImportFailure(e: ImportCredentialsException) {}

导入流异常