androidx.biometric.auth


Interfaces

AuthPrompt

A handle to the prompt that is shown while the user is authenticating.

Classes

AuthPromptCallback

A collection of methods that may be invoked by an auth prompt during authentication.

AuthPromptHost

A wrapper class for the component that will be used to host an auth prompt.

Class2BiometricAuthPrompt

An authentication prompt that requires the user to present a Class 2 biometric (e.g. fingerprint, face, or iris).

Class2BiometricAuthPrompt.Builder

Builder for a Class2BiometricAuthPrompt with configurable options.

Class2BiometricOrCredentialAuthPrompt

An authentication prompt that requires the user to present a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Class2BiometricOrCredentialAuthPrompt.Builder

Builder for a Class2BiometricOrCredentialAuthPrompt with configurable options.

Class3BiometricAuthPrompt

An authentication prompt that requires the user to present a Class 3 biometric (e.g. fingerprint, face, or iris).

Class3BiometricAuthPrompt.Builder

Builder for a Class3BiometricAuthPrompt with configurable options.

Class3BiometricOrCredentialAuthPrompt

An authentication prompt that requires the user to present a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Class3BiometricOrCredentialAuthPrompt.Builder

Builder for a Class3BiometricOrCredentialAuthPrompt with configurable options.

CredentialAuthPrompt

An authentication prompt that requires the user to present the screen lock credential (i.e. PIN, pattern, or password) for the device.

CredentialAuthPrompt.Builder

Builder for a CredentialAuthPrompt with configurable options.

Exceptions

AuthPromptErrorException

Thrown when an unrecoverable error has been encountered and authentication has stopped.

AuthPromptFailureException

Thrown when an authentication attempt by the user has been rejected, e.g., the user's biometrics were not recognized.

Extension functions summary

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

suspend BiometricPrompt.AuthenticationResult
FragmentActivity.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

suspend BiometricPrompt.AuthenticationResult
Fragment.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

suspend BiometricPrompt.AuthenticationResult
FragmentActivity.authenticateWithClass2BiometricsOrCredentials(
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

suspend BiometricPrompt.AuthenticationResult
Fragment.authenticateWithClass2BiometricsOrCredentials(
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

suspend BiometricPrompt.AuthenticationResult
FragmentActivity.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

suspend BiometricPrompt.AuthenticationResult
Fragment.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

AuthPrompt
FragmentActivity.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

AuthPrompt
Fragment.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

suspend BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
FragmentActivity.authenticateWithClass3BiometricsOrCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

suspend BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
Fragment.authenticateWithClass3BiometricsOrCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

suspend BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
FragmentActivity.authenticateWithCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence?
)

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

suspend BiometricPrompt.AuthenticationResult
@RequiresApi(value = 30)
Fragment.authenticateWithCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence?
)

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
FragmentActivity.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

AuthPrompt
Fragment.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

AuthPrompt
FragmentActivity.startClass2BiometricOrCredentialAuthentication(
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
Fragment.startClass2BiometricOrCredentialAuthentication(
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
@RequiresApi(value = 30)
FragmentActivity.startClass3BiometricOrCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
@RequiresApi(value = 30)
Fragment.startClass3BiometricOrCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence?,
    description: CharSequence?,
    confirmationRequired: Boolean,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
@RequiresApi(value = 30)
FragmentActivity.startCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence?,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

AuthPrompt
@RequiresApi(value = 30)
Fragment.startCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence?,
    executor: Executor?,
    callback: AuthPromptCallback
)

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

Extension functions

suspend fun Class2BiometricAuthPrompt.authenticate(host: AuthPromptHost): BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.Class2BiometricAuthPrompt
import androidx.biometric.auth.authenticate

val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    Class2BiometricAuthPrompt.Builder(title, negativeButtonText)
        .apply {
            setSubtitle(subtitle)
            setDescription(description)
            setConfirmationRequired(true)
        }
        .build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this))

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
host: AuthPromptHost

A wrapper for the component that will host the prompt.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

(AuthPromptHost, AuthPromptCallback)

suspend fun Class2BiometricOrCredentialAuthPrompt.authenticate(
    host: AuthPromptHost
): BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.Class2BiometricOrCredentialAuthPrompt
import androidx.biometric.auth.CredentialAuthPrompt
import androidx.biometric.auth.authenticate

val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    Class2BiometricOrCredentialAuthPrompt.Builder(title)
        .apply {
            setSubtitle(subtitle)
            setDescription(description)
            setConfirmationRequired(true)
        }
        .build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this))

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
host: AuthPromptHost

A wrapper for the component that will host the prompt.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

( AuthPromptHost, AuthPromptCallback )

suspend fun Class3BiometricAuthPrompt.authenticate(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?
): BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.Class3BiometricAuthPrompt
import androidx.biometric.auth.authenticate

// To use Class3 authentication, we need to create a CryptoObject.
// First create a spec for the key to be generated.
val keyPurpose = KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
val keySpec =
    KeyGenParameterSpec.Builder(KEY_NAME, keyPurpose)
        .apply {
            setBlockModes(KeyProperties.BLOCK_MODE_CBC)
            setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
            setUserAuthenticationRequired(true)

            // Require authentication for each use of the key.
            val timeout = 0
            // Set the key type according to the allowed auth types.
            val keyType =
                KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
            setUserAuthenticationParameters(timeout, keyType)
        }
        .build()

// Generate and store the key in the Android keystore.
KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE_INSTANCE).run {
    init(keySpec)
    generateKey()
}

// Prepare the crypto object to use for authentication.
val cipher =
    Cipher.getInstance(
            "${KeyProperties.KEY_ALGORITHM_AES}/${KeyProperties.BLOCK_MODE_CBC}/" +
                KeyProperties.ENCRYPTION_PADDING_PKCS7
        )
        .apply {
            val keyStore = KeyStore.getInstance(KEYSTORE_INSTANCE).apply { load(null) }
            init(Cipher.ENCRYPT_MODE, keyStore.getKey(KEY_NAME, null) as SecretKey)
        }

val cryptoObject = BiometricPrompt.CryptoObject(cipher)
val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    Class3BiometricAuthPrompt.Builder(title, negativeButtonText)
        .apply {
            setSubtitle(subtitle)
            setDescription(description)
            setConfirmationRequired(true)
        }
        .build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this), cryptoObject)

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
host: AuthPromptHost

A wrapper for the component that will host the prompt.

crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

(AuthPromptHost, AuthPromptCallback)

@RequiresApi(value = 30)
suspend fun Class3BiometricOrCredentialAuthPrompt.authenticate(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?
): BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.Class3BiometricOrCredentialAuthPrompt
import androidx.biometric.auth.CredentialAuthPrompt
import androidx.biometric.auth.authenticate

// To use Class3 authentication, we need to create a CryptoObject.
// First create a spec for the key to be generated.
val keyPurpose = KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
val keySpec =
    KeyGenParameterSpec.Builder(KEY_NAME, keyPurpose)
        .apply {
            setBlockModes(KeyProperties.BLOCK_MODE_CBC)
            setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
            setUserAuthenticationRequired(true)

            // Require authentication for each use of the key.
            val timeout = 0
            // Set the key type according to the allowed auth types.
            val keyType =
                KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
            setUserAuthenticationParameters(timeout, keyType)
        }
        .build()

// Generate and store the key in the Android keystore.
KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE_INSTANCE).run {
    init(keySpec)
    generateKey()
}

// Prepare the crypto object to use for authentication.
val cipher =
    Cipher.getInstance(
            "${KeyProperties.KEY_ALGORITHM_AES}/${KeyProperties.BLOCK_MODE_CBC}/" +
                KeyProperties.ENCRYPTION_PADDING_PKCS7
        )
        .apply {
            val keyStore = KeyStore.getInstance(KEYSTORE_INSTANCE).apply { load(null) }
            init(Cipher.ENCRYPT_MODE, keyStore.getKey(KEY_NAME, null) as SecretKey)
        }

val cryptoObject = BiometricPrompt.CryptoObject(cipher)
val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    Class3BiometricOrCredentialAuthPrompt.Builder(title)
        .apply {
            setSubtitle(subtitle)
            setDescription(description)
            setConfirmationRequired(true)
        }
        .build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this), cryptoObject)

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
host: AuthPromptHost

A wrapper for the component that will host the prompt.

crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

( AuthPromptHost, AuthPromptCallback )

@RequiresApi(value = 30)
suspend fun CredentialAuthPrompt.authenticate(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?
): BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

import androidx.biometric.BiometricPrompt
import androidx.biometric.auth.AuthPromptErrorException
import androidx.biometric.auth.AuthPromptFailureException
import androidx.biometric.auth.AuthPromptHost
import androidx.biometric.auth.CredentialAuthPrompt
import androidx.biometric.auth.authenticate

// To use credential authentication, we need to create a CryptoObject.
// First create a spec for the key to be generated.
val keyPurpose = KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
val keySpec =
    KeyGenParameterSpec.Builder(KEY_NAME, keyPurpose)
        .apply {
            setBlockModes(KeyProperties.BLOCK_MODE_CBC)
            setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
            setUserAuthenticationRequired(true)

            // Require authentication for each use of the key.
            val timeout = 0
            // Set the key type according to the allowed auth type.
            val keyType = KeyProperties.AUTH_DEVICE_CREDENTIAL
            setUserAuthenticationParameters(timeout, keyType)
        }
        .build()

// Generate and store the key in the Android keystore.
KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE_INSTANCE).run {
    init(keySpec)
    generateKey()
}

// Prepare the crypto object to use for authentication.
val cipher =
    Cipher.getInstance(
            "${KeyProperties.KEY_ALGORITHM_AES}/${KeyProperties.BLOCK_MODE_CBC}/" +
                KeyProperties.ENCRYPTION_PADDING_PKCS7
        )
        .apply {
            val keyStore = KeyStore.getInstance(KEYSTORE_INSTANCE).apply { load(null) }
            init(Cipher.ENCRYPT_MODE, keyStore.getKey(KEY_NAME, null) as SecretKey)
        }

val cryptoObject = BiometricPrompt.CryptoObject(cipher)
val payload = "A message to encrypt".toByteArray(Charset.defaultCharset())

// Construct AuthPrompt with localized Strings to be displayed to UI.
val authPrompt =
    CredentialAuthPrompt.Builder(title).apply { setDescription(description) }.build()

try {
    val authResult = authPrompt.authenticate(AuthPromptHost(this), cryptoObject)

    // Encrypt a payload using the result of crypto-based auth.
    val encryptedPayload = authResult.cryptoObject?.cipher?.doFinal(payload)

    // Use the encrypted payload somewhere interesting.
    sendEncryptedPayload(encryptedPayload)
} catch (e: AuthPromptErrorException) {
    // Handle irrecoverable error during authentication.
    // Possible values for AuthPromptErrorException.errorCode are listed in the @IntDef,
    // androidx.biometric.BiometricPrompt.AuthenticationError.
} catch (e: AuthPromptFailureException) {
    // Handle auth failure due biometric credentials being rejected.
}
Parameters
host: AuthPromptHost

A wrapper for the component that will host the prompt.

crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

See also
authenticate

( AuthPromptHost host, BiometricPrompt.CryptoObject, AuthPromptCallback )

authenticateWithClass2Biometrics

suspend fun FragmentActivity.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass2Biometrics

suspend fun Fragment.authenticateWithClass2Biometrics(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass2BiometricsOrCredentials

suspend fun FragmentActivity.authenticateWithClass2BiometricsOrCredentials(
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass2BiometricsOrCredentials

suspend fun Fragment.authenticateWithClass2BiometricsOrCredentials(
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

An AuthPrompt handle to the shown prompt.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass3Biometrics

suspend fun FragmentActivity.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass3Biometrics

suspend fun Fragment.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass3Biometrics

fun FragmentActivity.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

authenticateWithClass3Biometrics

fun Fragment.authenticateWithClass3Biometrics(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris).

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

authenticateWithClass3BiometricsOrCredentials

@RequiresApi(value = 30)
suspend fun FragmentActivity.authenticateWithClass3BiometricsOrCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithClass3BiometricsOrCredentials

@RequiresApi(value = 30)
suspend fun Fragment.authenticateWithClass3BiometricsOrCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithCredentials

@RequiresApi(value = 30)
suspend fun FragmentActivity.authenticateWithCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence? = null
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

authenticateWithCredentials

@RequiresApi(value = 30)
suspend fun Fragment.authenticateWithCredentials(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence? = null
): BiometricPrompt.AuthenticationResult

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

Returns
BiometricPrompt.AuthenticationResult

AuthenticationResult for a successful authentication.

Throws
androidx.biometric.auth.AuthPromptErrorException

when an unrecoverable error has been encountered and authentication has stopped.

androidx.biometric.auth.AuthPromptFailureException

when an authentication attempt by the user has been rejected.

startClass2BiometricAuthentication

fun FragmentActivity.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass2BiometricAuthentication

fun Fragment.startClass2BiometricAuthentication(
    title: CharSequence,
    negativeButtonText: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris).

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

negativeButtonText: CharSequence

The label for the negative button on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass2BiometricOrCredentialAuthentication

fun FragmentActivity.startClass2BiometricOrCredentialAuthentication(
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass2BiometricOrCredentialAuthentication

fun Fragment.startClass2BiometricOrCredentialAuthentication(
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 2 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Note that Class 3 biometrics are guaranteed to meet the requirements for Class 2 and thus will also be accepted.

Parameters
title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass3BiometricOrCredentialAuthentication

@RequiresApi(value = 30)
fun FragmentActivity.startClass3BiometricOrCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startClass3BiometricOrCredentialAuthentication

@RequiresApi(value = 30)
fun Fragment.startClass3BiometricOrCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    subtitle: CharSequence? = null,
    description: CharSequence? = null,
    confirmationRequired: Boolean = true,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with a Class 3 biometric (e.g. fingerprint, face, or iris) or the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

subtitle: CharSequence? = null

An optional subtitle to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

confirmationRequired: Boolean = true

Whether user confirmation should be required for passive biometrics.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startCredentialAuthentication

@RequiresApi(value = 30)
fun FragmentActivity.startCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence? = null,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.

startCredentialAuthentication

@RequiresApi(value = 30)
fun Fragment.startCredentialAuthentication(
    crypto: BiometricPrompt.CryptoObject?,
    title: CharSequence,
    description: CharSequence? = null,
    executor: Executor? = null,
    callback: AuthPromptCallback
): AuthPrompt

Prompts the user to authenticate with the screen lock credential (i.e. PIN, pattern, or password) for the device.

Parameters
crypto: BiometricPrompt.CryptoObject?

A cryptographic object to be associated with this authentication.

title: CharSequence

The title to be displayed on the prompt.

description: CharSequence? = null

An optional description to be displayed on the prompt.

executor: Executor? = null

An executor for callback methods. If null, these will run on the main thread.

callback: AuthPromptCallback

The object that will receive and process authentication events.

Returns
AuthPrompt

An AuthPrompt handle to the shown prompt.