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

认证转移

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

核心概念

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

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

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

Android 版本兼容性

凭据传输 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：

<activity
    android:name="com.example.CredentialExportActivity"
    android:exported="true"
    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) 解析请求，验证调用应用和 credId，执行任何所需的生物识别身份验证，并将 FIDO CXF 载荷写回提供的 content URI：

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：由于提供方设置问题（例如， supportedCredentialTypes 在 ExportEntry 中为空，或在不受支持的操作系统层级上调用）导致注册或清除失败时抛出。
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) {}

导入流程异常