Class3BiometricOrCredentialAuthPrompt


@RequiresApi(value = Build.VERSION_CODES.R)
public class 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.

Summary

Nested types

Builder for a Class3BiometricOrCredentialAuthPrompt with configurable options.

Public methods

@Nullable CharSequence

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

@Nullable CharSequence

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

@NonNull CharSequence

Gets the title to be displayed on the prompt.

boolean

Checks if the prompt should require explicit user confirmation after a passive biometric (e.g. iris or face) has been recognized but before onAuthenticationSucceeded is called.

@NonNull AuthPrompt

Shows an authentication prompt to the user.

@NonNull AuthPrompt
startAuthentication(
    @NonNull AuthPromptHost host,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull Executor executor,
    @NonNull AuthPromptCallback callback
)

Shows an authentication prompt to the user.

Extension functions

final @NonNull BiometricPrompt.AuthenticationResult

Shows an authentication prompt to the user.

Public methods

getDescription

Added in 1.4.0-alpha02
public @Nullable CharSequence getDescription()

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

Returns
@Nullable CharSequence

The description for the prompt.

See also
setDescription

getSubtitle

Added in 1.4.0-alpha02
public @Nullable CharSequence getSubtitle()

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

Returns
@Nullable CharSequence

The subtitle for the prompt.

See also
setSubtitle

getTitle

Added in 1.4.0-alpha02
public @NonNull CharSequence getTitle()

Gets the title to be displayed on the prompt.

Returns
@NonNull CharSequence

The title for the prompt.

isConfirmationRequired

Added in 1.4.0-alpha02
public boolean isConfirmationRequired()

Checks if the prompt should require explicit user confirmation after a passive biometric (e.g. iris or face) has been recognized but before onAuthenticationSucceeded is called.

Returns
boolean

Whether the prompt should require explicit user confirmation for passive biometrics.

startAuthentication

Added in 1.4.0-alpha02
public @NonNull AuthPrompt startAuthentication(
    @NonNull AuthPromptHost host,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull AuthPromptCallback callback
)

Shows an authentication prompt to the user.

Parameters
@NonNull AuthPromptHost host

A wrapper for the component that will host the prompt.

@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull AuthPromptCallback callback

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

Returns
@NonNull AuthPrompt

A handle to the shown prompt.

startAuthentication

Added in 1.4.0-alpha02
public @NonNull AuthPrompt startAuthentication(
    @NonNull AuthPromptHost host,
    @Nullable BiometricPrompt.CryptoObject crypto,
    @NonNull Executor executor,
    @NonNull AuthPromptCallback callback
)

Shows an authentication prompt to the user.

Parameters
@NonNull AuthPromptHost host

A wrapper for the component that will host the prompt.

@Nullable BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

@NonNull Executor executor

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

@NonNull AuthPromptCallback callback

The callback object that will receive and process authentication events.

Returns
@NonNull AuthPrompt

A handle to the shown prompt.

Extension functions

Class3BiometricOrCredentialAuthExtensionsKt.authenticate

@RequiresApi(value = 30)
public final @NonNull BiometricPrompt.AuthenticationResult Class3BiometricOrCredentialAuthExtensionsKt.authenticate(
    @NonNull Class3BiometricOrCredentialAuthPrompt receiver,
    @NonNull AuthPromptHost host,
    BiometricPrompt.CryptoObject crypto
)

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
@NonNull AuthPromptHost host

A wrapper for the component that will host the prompt.

BiometricPrompt.CryptoObject crypto

A cryptographic object to be associated with this authentication.

Returns
@NonNull 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 )