binding/com.pingidentity.device.binding.authenticator/authenticateWithBiometric

authenticateWithBiometric

suspend fun authenticateWithBiometric(context: Context, promptInfo: BiometricPrompt.PromptInfo, privateKey: PrivateKey?): BiometricPrompt.AuthenticationResult

Performs biometric authentication using AndroidX BiometricPrompt with thread-safe operation handling.

This function provides a coroutine-based interface to AndroidX BiometricPrompt authentication, with built-in concurrency control to prevent multiple simultaneous operations. It launches a transparent Activity to handle user interaction and returns the result asynchronously through Kotlin coroutines.

Concurrency Behavior:

  • Only one biometric operation can be active at a time (enforced by mutex)

  • If another operation is already in progress, subsequent calls will suspend until completion

  • Automatic cleanup on cancellation, completion, or error

  • Thread-safe state management across coroutine boundaries

Error Handling:

  • Converts biometric authentication errors to custom BiometricAuthenticationException

  • Handles user cancellation, timeouts, and authentication failures gracefully

  • Provides detailed error codes and messages for different failure scenarios

  • Ensures proper cleanup even in error conditions

CryptoObject Integration:

  • With private key: Creates RSA signature CryptoObject for hardware-backed authentication

  • Without private key: Uses time-based authentication for broader device compatibility

  • Automatic fallback: Gracefully handles CryptoObject creation failures

Return

BiometricPrompt.AuthenticationResult containing authentication outcome and any associated CryptoObject that was used during the authentication process.

Since

1.0.0

Parameters

context

The Android context for launching the authentication flow. Can be Activity or Application context - function handles both scenarios appropriately.

promptInfo

The BiometricPrompt.PromptInfo configuration defining dialog appearance, allowed authenticators, button text, and other UI/UX parameters.

privateKey

Optional private key for CryptoObject-based authentication. When provided, creates RSA signature CryptoObject for hardware-backed security. When null, uses time-based authentication validation.

See also

Throws

on authentication failure, user cancellation, hardware unavailability, or other biometric system errors. Exception includes detailed error code and message for specific failure diagnosis.

if another biometric operation is already in progress (should not occur due to mutex, but included for completeness).