Las APIs de transferencia de credenciales del Administrador de credenciales permiten la transferencia segura de credenciales de usuario entre proveedores de credenciales en el mismo dispositivo. En esta guía, se detalla
cómo los proveedores de credenciales en Android pueden integrarse con las APIs que proporciona la
androidx.credentials:providerevents biblioteca. Esta función admite
contraseñas, llaves de acceso, información de direcciones y campos personalizados con el
formato de intercambio de credenciales (CXF) de FIDO estandarizado.
Conceptos básicos
El framework de transferencia de credenciales facilita la transferencia de credenciales de par a par en el mismo dispositivo sin exponer credenciales sin procesar al SO Android ni a apps no autenticadas.
El framework define dos roles principales:
- Exportador (proveedor de origen): Es un proveedor de credenciales que actualmente tiene credenciales de usuario. Previamente, registra metadatos sobre las cuentas exportables
disponibles (
ExportEntry) con el sistema y responde a las solicitudes de transferencia cuando el usuario las selecciona. - Importador (proveedor de cliente o asistente de configuración): Es un proveedor de credenciales o un
asistente de configuración que inicia una solicitud de importación
(
ImportCredentialsRequest) en la que se especifican los tipos de credenciales y extensiones que puede recibir.
Compatibilidad con versiones de Android
La API de transferencia de credenciales funciona en dispositivos que ejecutan Android 8 (nivel de API 26) y versiones posteriores.
Cómo agregar dependencias
Agrega la dependencia androidx.credentials:providerevents al archivo
build.gradle o build.gradle.kts de tu módulo:
dependencies {
implementation("androidx.credentials:providerevents:1.0.0-alpha06")
}
Crea una instancia de la clase requerida
Crea una instancia de ProviderEventsManager requerida.
val providerEventsManager = ProviderEventsManager.create(context)
Implementa el exportador
Para permitir que los usuarios exporten credenciales de tu app a otros proveedores de credenciales en el dispositivo, implementa el rol de exportador.
Registra entradas de exportación
Cuando cambie tu proveedor de credenciales (por ejemplo, un usuario accede, agrega credenciales o modifica cuentas), registra o actualiza tus elementos ExportEntry con ProviderEventsManager.registerExport().
Cada ExportEntry requiere lo siguiente:
id: Un identificador de cadena secreto generado de forma aleatoria que representa de forma única esta entrada de exportación. Debes conservar este ID de forma segura; lo necesitarás más adelante para verificar las solicitudes de transferencia entrantes.accountDisplayName: Es una etiqueta de cuenta opcional (por ejemplo,"Personal Account").userDisplayName: Es el identificador principal del usuario (por ejemplo,"alice@example.com").icon: Es un íconoBitmapque representa el proveedor o la cuenta (la biblioteca lo ajusta automáticamente a PNG de 32 x 32).supportedCredentialTypes: Es un conjunto de constantes de cadena deCredentialTypesque representan los tipos que contiene esta entrada.
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) } }
Declara la actividad del exportador en el archivo de manifiesto
Cuando el usuario selecciona tu ExportEntry en la IU del selector del sistema, el sistema inicia tu Activity de control designada. Declara esta actividad con la acción de intent obligatoria y el esquema de URI de contenido:
<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>
Controla el intent de transferencia en tu actividad
En tu CredentialExportActivity, usa IntentHandler.retrieveProviderImportCredentialsRequest(intent) para analizar la solicitud, verificar la app que realiza la llamada y el credId, realizar cualquier autenticación biométrica requerida y volver a escribir la carga útil de CXF de FIDO en el URI de contenido proporcionado:
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() } }
Excepciones de registro y borrado de exportación
Todas las excepciones de este módulo son subclases de
ImportCredentialsException, RegisterExportException o
ClearExportException.
RegisterExportProviderConfigurationExceptionoClearExportProviderConfigurationException: Se arroja cuando el registro o el borrado fallan debido a problemas de configuración del proveedor (por ejemplo,supportedCredentialTypesvacío en unExportEntryo una llamada en un nivel de SO no compatible).RegisterExportUnknownErrorExceptionoClearExportUnknownErrorException: Se produjo un error no clasificado del sistema o de almacenamiento mientras se actualizaba el registro de exportación.
Implementa el importador
Para importar credenciales a tu app (por ejemplo, durante la incorporación o la importación de proveedores
), implementa el rol de importador y llama a
ProviderEventsManager.importCredentials() para iniciar el flujo.
Crea la solicitud de importación y el flujo de inicio
Especifica qué CredentialTypes y KnownExtensions admite tu importador:
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) {}
Excepciones de flujo de importación
Todas las excepciones de este módulo son subclases de
ImportCredentialsException, RegisterExportException o
ClearExportException.
ImportCredentialsCancellationException: El usuario descartó la IU del selector o canceló la actividad de exportación (Activity.RESULT_CANCELED).ImportCredentialsNoExportOptionException: No hay entradas de exportación registradas que coincidan con los tipos de credenciales solicitados, o el exportador seleccionado arrojó una excepción de rechazo.ImportCredentialsProviderConfigurationException: Error de configuración (por ejemplo,credentialTypesvacío establecido enImportCredentialsRequesto permisos faltantes).ImportCredentialsInvalidJsonException: El exportador devolvió una carga útil de JSON con formato incorrecto o vacía que no pasó la validación de la solicitud.ImportCredentialsSystemErrorException: Se produjo un error interno del sistema Android o de transferencia de Binder durante la importación.ImportCredentialsUnknownCallerException: El framework no pudo verificar la app que realiza la llamada.ImportCredentialsUnknownErrorException: Error no clasificado o inesperado durante el flujo de importación.
Tipos de credenciales y extensiones compatibles
El objeto androidx.credentials.providerevents.transfer.CredentialTypes define constantes de cadena estandarizadas que corresponden a los tipos de elementos CXF de FIDO:
| Constante | Valor (tipo cxf) |
Descripción |
|---|---|---|
CREDENTIAL_TYPE_BASIC_AUTH |
"basic-auth" |
Credenciales de acceso de nombre de usuario y contraseña |
CREDENTIAL_TYPE_PUBLIC_KEY |
"passkey" |
Credenciales de clave pública de llave de acceso FIDO2 o WebAuthn |
CREDENTIAL_TYPE_ADDRESS |
"address" |
Información de dirección postal o de envío para el autocompletado de formularios |
CREDENTIAL_TYPE_API_KEY |
"api-key" |
Claves y tokens de acceso a la API |
CREDENTIAL_TYPE_CREDIT_CARD |
"credit-card" |
Información de pago con tarjeta de crédito y débito |
CREDENTIAL_TYPE_CUSTOM_FIELDS |
"custom-fields" |
Agrupaciones personalizadas o campos definidos por el usuario |
CREDENTIAL_TYPE_DRIVERS_LICENSE |
"drivers-license" |
Detalles de la licencia de conducir |
CREDENTIAL_TYPE_FILE |
"file" |
Metadatos y referencias de marcadores de posición para archivos binarios |
CREDENTIAL_TYPE_GENERATED_PASSWORD |
"generated-password" |
Contraseñas seguras generadas por la máquina |
CREDENTIAL_TYPE_IDENTITY_DOCUMENT |
"identity-document" |
Referencias de documentos nacionales de identidad, números de seguro social, números de identificación fiscal o pasaportes |
CREDENTIAL_TYPE_ITEM_REFERENCE |
"item-reference" |
Vínculos lógicos que apuntan a otro elemento en la carga útil |
CREDENTIAL_TYPE_NOTE |
"note" |
Notas seguras definidas por el usuario (cadena UTF-8) |
CREDENTIAL_TYPE_PASSPORT |
"passport" |
Detalles del documento de viaje del pasaporte |
CREDENTIAL_TYPE_PERSON_NAME |
"person-name" |
Detalles de identidad y nombres de personas |
CREDENTIAL_TYPE_SSH_KEY |
"ssh-key" |
Pares de claves SSH públicas y privadas |
CREDENTIAL_TYPE_TOTP |
"totp" |
Secretos de contraseña de un solo uso basada en el tiempo (2FA) |
CREDENTIAL_TYPE_WIFI |
"wifi" |
SSID y frases de contraseña de la red Wi-Fi |
Comparadores WASM (WebAssembly) personalizados (avanzado)
De forma predeterminada, si llamas a RegisterExportRequest.create(context, entries), se agrupa el credential_transfer_matcher.wasm predeterminado del sistema desde los recursos de la biblioteca, que filtra las entradas en función de la intersección de supportedCredentialTypes.
Si tu proveedor de credenciales requiere una lógica de coincidencia compleja (por ejemplo, verificaciones de capacidades dinámicas o filtrado condicional basado en campos personalizados), puedes compilar tu propio módulo de WebAssembly que coincida con la API de transferencia de credenciales de WASM y pasar el array de bytes sin procesar directamente:
// Loading a custom WASM matcher val customMatcherBytes = context.assets.open("my_custom_matcher.wasm").use { it.readBytes() } val customRequest = RegisterExportRequest( entries = myEntries, exportMatcher = customMatcherBytes ) providerEventsManager.registerExport(customRequest)