显示生物识别身份验证对话框

保护应用中的敏感信息或付费内容的一种方法是请求生物识别身份验证，例如使用人脸识别或指纹识别。本指南介绍如何在您的应用中支持生物识别登录流程。

一般来说，您应使用 Credential Manager 在设备上进行初始登录。后续的重新授权可以使用生物识别提示 (Biometric Prompt) 或 Credential Manager 进行。使用生物识别提示的优势在于它提供了更多自定义选项，而 Credential Manager 在这两种流程中提供单一实现。

声明您的应用支持的身份验证类型

要定义您的应用支持的身份验证类型，请使用 BiometricManager.Authenticators 接口。系统允许您声明以下身份验证类型

BIOMETRIC_STRONG: 使用 Class 3 生物识别技术的身份验证，定义见 Android 兼容性定义页面。
BIOMETRIC_WEAK: 使用 Class 2 生物识别技术的身份验证，定义见 Android 兼容性定义页面。
DEVICE_CREDENTIAL: 使用屏幕锁定凭据（用户的 PIN、图案或密码）的身份验证。

要开始使用身份验证器，用户需要创建 PIN、图案或密码。如果用户尚未设置，生物识别注册流程会提示用户创建一个。

要定义您的应用接受的生物识别身份验证类型，请将一种身份验证类型或多种类型的位组合传递给 setAllowedAuthenticators() 方法。以下代码片段展示了如何支持使用 Class 3 生物识别技术或屏幕锁定凭据进行身份验证。

Kotlin

// Lets the user authenticate using either a Class 3 biometric or
// their lock screen credential (PIN, pattern, or password).
promptInfo = BiometricPrompt.PromptInfo.Builder()
        .setTitle("Biometric login for my app")
        .setSubtitle("Log in using your biometric credential")
        .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
        .build()

Java

// Lets user authenticate using either a Class 3 biometric or
// their lock screen credential (PIN, pattern, or password).
promptInfo = new BiometricPrompt.PromptInfo.Builder()
        .setTitle("Biometric login for my app")
        .setSubtitle("Log in using your biometric credential")
        .setAllowedAuthenticators(BIOMETRIC_STRONG | DEVICE_CREDENTIAL)
        .build();

以下身份验证器类型组合在 Android 10（API 级别 29）及更低版本上不受支持：DEVICE_CREDENTIAL 和 BIOMETRIC_STRONG | DEVICE_CREDENTIAL。要在 Android 10 及更低版本上检查是否存在 PIN、图案或密码，请使用 KeyguardManager.isDeviceSecure() 方法。

检查生物识别身份验证是否可用

在决定您的应用支持哪些身份验证元素后，请检查这些元素是否可用。为此，请将您使用 setAllowedAuthenticators() 方法声明的相同类型的位组合传递到 canAuthenticate() 方法中。如有必要，请调用 ACTION_BIOMETRIC_ENROLL intent 操作。在 intent extra 中，提供您的应用接受的身份验证器集。此 intent 会提示用户注册您的应用接受的身份验证器的凭据。

Kotlin

val biometricManager = BiometricManager.from(this)
when (biometricManager.canAuthenticate(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)) {
    BiometricManager.BIOMETRIC_SUCCESS ->
        Log.d("MY_APP_TAG", "App can authenticate using biometrics.")
    BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE ->
        Log.e("MY_APP_TAG", "No biometric features available on this device.")
    BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE ->
        Log.e("MY_APP_TAG", "Biometric features are currently unavailable.")
    BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> {
        // Prompts the user to create credentials that your app accepts.
        val enrollIntent = Intent(Settings.ACTION_BIOMETRIC_ENROLL).apply {
            putExtra(Settings.EXTRA_BIOMETRIC_AUTHENTICATORS_ALLOWED,
                BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
        }
        startActivityForResult(enrollIntent, REQUEST_CODE)
    }
}

Java

BiometricManager biometricManager = BiometricManager.from(this);
switch (biometricManager.canAuthenticate(BIOMETRIC_STRONG | DEVICE_CREDENTIAL)) {
    case BiometricManager.BIOMETRIC_SUCCESS:
        Log.d("MY_APP_TAG", "App can authenticate using biometrics.");
        break;
    case BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE:
        Log.e("MY_APP_TAG", "No biometric features available on this device.");
        break;
    case BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE:
        Log.e("MY_APP_TAG", "Biometric features are currently unavailable.");
        break;
    case BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED:
        // Prompts the user to create credentials that your app accepts.
        final Intent enrollIntent = new Intent(Settings.ACTION_BIOMETRIC_ENROLL);
        enrollIntent.putExtra(Settings.EXTRA_BIOMETRIC_AUTHENTICATORS_ALLOWED,
                BIOMETRIC_STRONG | DEVICE_CREDENTIAL);
        startActivityForResult(enrollIntent, REQUEST_CODE);
        break;
}

确定用户如何进行身份验证

用户身份验证成功后，您可以通过调用 getAuthenticationType() 检查用户是使用设备凭据还是生物识别凭据进行了身份验证。

要显示一个请求用户使用生物识别凭据进行身份验证的系统提示，请使用 Biometric 库。这个系统提供的对话框在所有使用它的应用中保持一致，从而创造了更值得信赖的用户体验。图 1 显示了一个示例对话框。

图 1. 请求生物识别身份验证的系统对话框。

要使用 Biometric 库为您的应用添加生物识别身份验证，请完成以下步骤

在应用的模块 build.gradle 文件中，添加对 androidx.biometric 库的依赖。

在承载生物识别登录对话框的 Activity 或 Fragment 中，使用以下代码片段所示的逻辑显示对话框

Kotlin

private lateinit var executor: Executor
private lateinit var biometricPrompt: BiometricPrompt
private lateinit var promptInfo: BiometricPrompt.PromptInfo

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_login)
    executor = ContextCompat.getMainExecutor(this)
    biometricPrompt = BiometricPrompt(this, executor,
            object : BiometricPrompt.AuthenticationCallback() {
        override fun onAuthenticationError(errorCode: Int,
                errString: CharSequence) {
            super.onAuthenticationError(errorCode, errString)
            Toast.makeText(applicationContext,
                "Authentication error: $errString", Toast.LENGTH_SHORT)
                .show()
        }

        override fun onAuthenticationSucceeded(
                result: BiometricPrompt.AuthenticationResult) {
            super.onAuthenticationSucceeded(result)
            Toast.makeText(applicationContext,
                "Authentication succeeded!", Toast.LENGTH_SHORT)
                .show()
        }

        override fun onAuthenticationFailed() {
            super.onAuthenticationFailed()
            Toast.makeText(applicationContext, "Authentication failed",
                Toast.LENGTH_SHORT)
                .show()
        }
    })

    promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("Biometric login for my app")
            .setSubtitle("Log in using your biometric credential")
            .setNegativeButtonText("Use account password")
            .build()

    // Prompt appears when user clicks "Log in".
    // Consider integrating with the keystore to unlock cryptographic operations,
    // if needed by your app.
    val biometricLoginButton =
            findViewById<Button>(R.id.biometric_login)
    biometricLoginButton.setOnClickListener {
        biometricPrompt.authenticate(promptInfo)
    }
}

Java

private Executor executor;
private BiometricPrompt biometricPrompt;
private BiometricPrompt.PromptInfo promptInfo;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_login);
    executor = ContextCompat.getMainExecutor(this);
    biometricPrompt = new BiometricPrompt(MainActivity.this,
            executor, new BiometricPrompt.AuthenticationCallback() {
        @Override
        public void onAuthenticationError(int errorCode,
                @NonNull CharSequence errString) {
            super.onAuthenticationError(errorCode, errString);
            Toast.makeText(getApplicationContext(),
                "Authentication error: " + errString, Toast.LENGTH_SHORT)
                .show();
        }

        @Override
        public void onAuthenticationSucceeded(
                @NonNull BiometricPrompt.AuthenticationResult result) {
            super.onAuthenticationSucceeded(result);
            Toast.makeText(getApplicationContext(),
                "Authentication succeeded!", Toast.LENGTH_SHORT).show();
        }

        @Override
        public void onAuthenticationFailed() {
            super.onAuthenticationFailed();
            Toast.makeText(getApplicationContext(), "Authentication failed",
                Toast.LENGTH_SHORT)
                .show();
        }
    });

    promptInfo = new BiometricPrompt.PromptInfo.Builder()
            .setTitle("Biometric login for my app")
            .setSubtitle("Log in using your biometric credential")
            .setNegativeButtonText("Use account password")
            .build();

    // Prompt appears when user clicks "Log in".
    // Consider integrating with the keystore to unlock cryptographic operations,
    // if needed by your app.
    Button biometricLoginButton = findViewById(R.id.biometric_login);
    biometricLoginButton.setOnClickListener(view -> {
            biometricPrompt.authenticate(promptInfo);
    });
}

使用依赖于身份验证的加密解决方案

要进一步保护应用中的敏感信息，您可以使用 CryptoObject 实例将加密集成到您的生物识别身份验证工作流程中。该框架支持以下加密对象：Signature、Cipher 和 Mac。

用户通过生物识别提示成功进行身份验证后，您的应用可以执行加密操作。例如，如果您使用 Cipher 对象进行身份验证，则您的应用随后可以使用 SecretKey 对象执行加密和解密。

以下部分将介绍使用 Cipher 对象和 SecretKey 对象加密数据的示例。每个示例都使用了以下方法

Kotlin

private fun generateSecretKey(keyGenParameterSpec: KeyGenParameterSpec) {
    val keyGenerator = KeyGenerator.getInstance(
            KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
    keyGenerator.init(keyGenParameterSpec)
    keyGenerator.generateKey()
}

private fun getSecretKey(): SecretKey {
    val keyStore = KeyStore.getInstance("AndroidKeyStore")

    // Before the keystore can be accessed, it must be loaded.
    keyStore.load(null)
    return keyStore.getKey(KEY_NAME, null) as SecretKey
}

private fun getCipher(): Cipher {
    return Cipher.getInstance(KeyProperties.KEY_ALGORITHM_AES + "/"
            + KeyProperties.BLOCK_MODE_CBC + "/"
            + KeyProperties.ENCRYPTION_PADDING_PKCS7)
}

Java

private void generateSecretKey(KeyGenParameterSpec keyGenParameterSpec) {
    KeyGenerator keyGenerator = KeyGenerator.getInstance(
            KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore");
    keyGenerator.init(keyGenParameterSpec);
    keyGenerator.generateKey();
}

private SecretKey getSecretKey() {
    KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");

    // Before the keystore can be accessed, it must be loaded.
    keyStore.load(null);
    return ((SecretKey)keyStore.getKey(KEY_NAME, null));
}

private Cipher getCipher() {
    return Cipher.getInstance(KeyProperties.KEY_ALGORITHM_AES + "/"
            + KeyProperties.BLOCK_MODE_CBC + "/"
            + KeyProperties.ENCRYPTION_PADDING_PKCS7);
}

仅使用生物识别凭据进行身份验证

如果您的应用使用的密钥需要生物识别凭据才能解锁，则用户每次在应用访问该密钥之前都必须对其生物识别凭据进行身份验证。

要仅在用户使用生物识别凭据进行身份验证后才加密敏感信息，请完成以下步骤

生成一个使用以下 KeyGenParameterSpec 配置的密钥

Kotlin

generateSecretKey(KeyGenParameterSpec.Builder(
        KEY_NAME,
        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
        .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
        .setUserAuthenticationRequired(true)
        // Invalidate the keys if the user has registered a new biometric
        // credential, such as a new fingerprint. Can call this method only
        // on Android 7.0 (API level 24) or higher. The variable
        // "invalidatedByBiometricEnrollment" is true by default.
        .setInvalidatedByBiometricEnrollment(true)
        .build())

Java

generateSecretKey(new KeyGenParameterSpec.Builder(
        KEY_NAME,
        KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
        .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
        .setUserAuthenticationRequired(true)
        // Invalidate the keys if the user has registered a new biometric
        // credential, such as a new fingerprint. Can call this method only
        // on Android 7.0 (API level 24) or higher. The variable
        // "invalidatedByBiometricEnrollment" is true by default.
        .setInvalidatedByBiometricEnrollment(true)
        .build());

启动一个包含 cipher 的生物识别身份验证工作流程

Kotlin

biometricLoginButton.setOnClickListener {
    // Exceptions are unhandled within this snippet.
    val cipher = getCipher()
    val secretKey = getSecretKey()
    cipher.init(Cipher.ENCRYPT_MODE, secretKey)
    biometricPrompt.authenticate(promptInfo,
            BiometricPrompt.CryptoObject(cipher))
}

Java

biometricLoginButton.setOnClickListener(view -> {
    // Exceptions are unhandled within this snippet.
    Cipher cipher = getCipher();
    SecretKey secretKey = getSecretKey();
    cipher.init(Cipher.ENCRYPT_MODE, secretKey);
    biometricPrompt.authenticate(promptInfo,
            new BiometricPrompt.CryptoObject(cipher));
});

在生物识别身份验证回调中，使用密钥加密敏感信息

Kotlin

override fun onAuthenticationSucceeded(
        result: BiometricPrompt.AuthenticationResult) {
    val encryptedInfo: ByteArray = result.cryptoObject.cipher?.doFinal(
        // plaintext-string text is whatever data the developer would like
        // to encrypt. It happens to be plain-text in this example, but it
        // can be anything
            plaintext-string.toByteArray(Charset.defaultCharset())
    )
    Log.d("MY_APP_TAG", "Encrypted information: " +
            Arrays.toString(encryptedInfo))
}

Java

@Override
public void onAuthenticationSucceeded(
        @NonNull BiometricPrompt.AuthenticationResult result) {
    // NullPointerException is unhandled; use Objects.requireNonNull().
    byte[] encryptedInfo = result.getCryptoObject().getCipher().doFinal(
        // plaintext-string text is whatever data the developer would like
        // to encrypt. It happens to be plain-text in this example, but it
        // can be anything
            plaintext-string.getBytes(Charset.defaultCharset()));
    Log.d("MY_APP_TAG", "Encrypted information: " +
            Arrays.toString(encryptedInfo));
}

使用生物识别或锁屏凭据进行身份验证

您可以使用允许使用生物识别凭据或锁屏凭据（PIN、图案或密码）进行身份验证的密钥。配置此密钥时，请指定一个有效期。在此期间，您的应用可以执行多次加密操作，而用户无需重新进行身份验证。

要在用户使用生物识别或锁屏凭据进行身份验证后加密敏感信息，请完成以下步骤

生成一个使用以下 KeyGenParameterSpec 配置的密钥

Kotlin

generateSecretKey(KeyGenParameterSpec.Builder(
    KEY_NAME,
    KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
    .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
    .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
    .setUserAuthenticationRequired(true)
    .setUserAuthenticationParameters(VALIDITY_DURATION_SECONDS,
            ALLOWED_AUTHENTICATORS)
    .build())

Java

generateSecretKey(new KeyGenParameterSpec.Builder(
    KEY_NAME,
    KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
    .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
    .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
    .setUserAuthenticationRequired(true)
    .setUserAuthenticationParameters(VALIDITY_DURATION_SECONDS,
            ALLOWED_AUTHENTICATORS)
    .build());

在用户进行身份验证后的 VALIDITY_DURATION_SECONDS 时间段内，加密敏感信息

Kotlin

private fun encryptSecretInformation() {
    // Exceptions are unhandled for getCipher() and getSecretKey().
    val cipher = getCipher()
    val secretKey = getSecretKey()
    try {
        cipher.init(Cipher.ENCRYPT_MODE, secretKey)
        val encryptedInfo: ByteArray = cipher.doFinal(
            // plaintext-string text is whatever data the developer would
            // like to encrypt. It happens to be plain-text in this example,
            // but it can be anything
                plaintext-string.toByteArray(Charset.defaultCharset()))
        Log.d("MY_APP_TAG", "Encrypted information: " +
                Arrays.toString(encryptedInfo))
    } catch (e: InvalidKeyException) {
        Log.e("MY_APP_TAG", "Key is invalid.")
    } catch (e: UserNotAuthenticatedException) {
        Log.d("MY_APP_TAG", "The key's validity timed out.")
        biometricPrompt.authenticate(promptInfo)
    }

Java

private void encryptSecretInformation() {
    // Exceptions are unhandled for getCipher() and getSecretKey().
    Cipher cipher = getCipher();
    SecretKey secretKey = getSecretKey();
    try {
        // NullPointerException is unhandled; use Objects.requireNonNull().
        ciper.init(Cipher.ENCRYPT_MODE, secretKey);
        byte[] encryptedInfo = cipher.doFinal(
            // plaintext-string text is whatever data the developer would
            // like to encrypt. It happens to be plain-text in this example,
            // but it can be anything
                plaintext-string.getBytes(Charset.defaultCharset()));
    } catch (InvalidKeyException e) {
        Log.e("MY_APP_TAG", "Key is invalid.");
    } catch (UserNotAuthenticatedException e) {
        Log.d("MY_APP_TAG", "The key's validity timed out.");
        biometricPrompt.authenticate(promptInfo);
    }
}

使用按次授权密钥进行身份验证

您可以在 BiometricPrompt 实例中提供对按次授权密钥的支持。此类密钥要求用户每次应用需要访问受该密钥保护的数据时，都必须提供生物识别凭据或设备凭据。按次授权密钥对于高价值交易非常有用，例如进行大额支付或更新个人的健康记录。

要将 BiometricPrompt 对象与按次授权密钥关联，请添加类似于以下内容的代码

Kotlin

val authPerOpKeyGenParameterSpec =
        KeyGenParameterSpec.Builder("myKeystoreAlias", key-purpose)
    // Accept either a biometric credential or a device credential.
    // To accept only one type of credential, include only that type as the
    // second argument.
    .setUserAuthenticationParameters(0 /* duration */,
            KeyProperties.AUTH_BIOMETRIC_STRONG or
            KeyProperties.AUTH_DEVICE_CREDENTIAL)
    .build()

Java

KeyGenParameterSpec authPerOpKeyGenParameterSpec =
        new KeyGenParameterSpec.Builder("myKeystoreAlias", key-purpose)
    // Accept either a biometric credential or a device credential.
    // To accept only one type of credential, include only that type as the
    // second argument.
    .setUserAuthenticationParameters(0 /* duration */,
            KeyProperties.AUTH_BIOMETRIC_STRONG |
            KeyProperties.AUTH_DEVICE_CREDENTIAL)
    .build();

无需用户显式操作即可进行身份验证

默认情况下，系统要求用户在生物识别凭据被接受后执行特定操作，例如按按钮。如果您的应用显示对话框以确认敏感或高风险操作（例如进行购买），则此配置更可取。

但是，如果您的应用显示生物识别身份验证对话框用于低风险操作，您可以向系统提供提示，指示用户无需确认身份验证。此提示可以让用户在使用被动模式（例如基于面部或虹膜识别）重新进行身份验证后，更快地查看应用中的内容。要提供此提示，请将 false 传递给 setConfirmationRequired() 方法。

图 2 显示了同一个对话框的两个版本。一个版本需要用户进行显式操作，另一个版本则不需要。

图 2. 无需用户确认的面部身份验证（上）和需要用户确认的面部身份验证（下）。

以下代码片段展示了如何呈现一个不需要用户显式操作即可完成身份验证流程的对话框

Kotlin

// Lets the user authenticate without performing an action, such as pressing a
// button, after their biometric credential is accepted.
promptInfo = BiometricPrompt.PromptInfo.Builder()
        .setTitle("Biometric login for my app")
        .setSubtitle("Log in using your biometric credential")
        .setNegativeButtonText("Use account password")
        .setConfirmationRequired(false)
        .build()

Java

// Lets the user authenticate without performing an action, such as pressing a
// button, after their biometric credential is accepted.
promptInfo = new BiometricPrompt.PromptInfo.Builder()
        .setTitle("Biometric login for my app")
        .setSubtitle("Log in using your biometric credential")
        .setNegativeButtonText("Use account password")
        .setConfirmationRequired(false)
        .build();

允许回退到非生物识别凭据

如果您希望您的应用允许使用生物识别或设备凭据进行身份验证，您可以通过将 DEVICE_CREDENTIAL 包含在传递给 setAllowedAuthenticators() 的值集中，声明您的应用支持设备凭据。

如果您的应用当前使用 createConfirmDeviceCredentialIntent() 或 setDeviceCredentialAllowed() 提供此功能，请切换到使用 setAllowedAuthenticators()。

其他资源

要详细了解 Android 上的生物识别身份验证，请查阅以下资源。

博客文章

从 FingerprintManager 迁移到 BiometricPrompt

显示生物识别身份验证对话框 通过收藏集保持井然有序 根据您的偏好保存内容并进行分类。

声明您的应用支持的身份验证类型

Kotlin

Java

检查生物识别身份验证是否可用

Kotlin

Java

确定用户如何进行身份验证

显示登录提示

Kotlin

Java

使用依赖于身份验证的加密解决方案

Kotlin

Java

仅使用生物识别凭据进行身份验证

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用生物识别或锁屏凭据进行身份验证

Kotlin

Java

Kotlin

Java

使用按次授权密钥进行身份验证

Kotlin

Java

无需用户显式操作即可进行身份验证

Kotlin

Java

允许回退到非生物识别凭据

其他资源

博客文章

显示生物识别身份验证对话框