CredentialAuthPrompt

@RequiresApi(value = Build.VERSION_CODES.R)
class CredentialAuthPrompt


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

Summary

Nested types

Builder for a CredentialAuthPrompt with configurable options.

Public functions

CharSequence?

Gets the description to be displayed on the prompt, if set.

CharSequence

Gets the title to be displayed on the prompt.

AuthPrompt
startAuthentication(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?,
    callback: AuthPromptCallback
)

Shows an authentication prompt to the user.

AuthPrompt
startAuthentication(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?,
    executor: Executor,
    callback: AuthPromptCallback
)

Shows an authentication prompt to the user.

Extension functions

suspend BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

Public functions

getDescription

Added in 1.2.0-alpha06
fun getDescription(): CharSequence?

Gets the description to be displayed on the prompt, if set.

Returns
CharSequence?

The description for the prompt.

See also
setDescription

getTitle

Added in 1.2.0-alpha06
fun getTitle(): CharSequence

Gets the title to be displayed on the prompt.

Returns
CharSequence

The title for the prompt.

startAuthentication

Added in 1.2.0-alpha06
fun startAuthentication(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?,
    callback: AuthPromptCallback
): AuthPrompt

Shows an authentication prompt to the user.

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.

callback: AuthPromptCallback

The callback object that will receive and process authentication events. Each callback method will be run on the main thread.

Returns
AuthPrompt

A handle to the shown prompt.

startAuthentication

Added in 1.2.0-alpha06
fun startAuthentication(
    host: AuthPromptHost,
    crypto: BiometricPrompt.CryptoObject?,
    executor: Executor,
    callback: AuthPromptCallback
): AuthPrompt

Shows an authentication prompt to the user.

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.

executor: Executor

The executor that will be used to run authentication callback methods.

callback: AuthPromptCallback

The callback object that will receive and process authentication events.

Returns
AuthPrompt

A handle to the shown prompt.

Extension functions

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

Shows an authentication prompt to the user.

import androidx.biometric.auth.AuthPromptHost
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 )