Android BiometricPrompt：允许设备凭据时面部认证失效问题

问题场景 #

在集成指纹、面部及设备凭据（PIN/密码/图案）的Biometric认证时，Android 10系统的三星A30s/A31出现以下异常：

• 同时集成三类认证方式时，Biometric弹窗仅识别指纹，不显示面部选项，仅提供设备凭据跳转按钮；
• 仅集成面部+设备凭据时，Biometric弹窗被直接跳过，自动进入设备凭据输入界面，无法选择面部认证；
• 不集成设备凭据时，所有生物识别组合均正常工作。

核心原因 #

Android 10（API 29）的BiometricPrompt API对弱生物识别（面部通常归为此类）+设备凭据的组合支持存在厂商实现差异：

1. 三星在Android 10的ROM中，启用setDeviceCredentialAllowed(true)后，会优先强生物识别（指纹），隐藏弱生物识别选项；
2. Android 10并未提供细粒度的认证方式组合控制（该能力从Android 11/API 30的setAllowedAuthenticators开始引入），导致厂商对混合认证的逻辑实现不一致；
3. 当仅存在弱生物识别+设备凭据时，三星ROM直接跳过生物识别弹窗， fallback到设备凭据界面。

解决方案 #

针对Android 10及以下版本，拆分生物识别与设备凭据的认证流程，避免在同一个Prompt中混合弱生物识别与设备凭据，具体实现如下：

1. 检测设备支持的生物识别类型

添加工具方法，获取当前设备可用的生物识别类型：

import android.content.Context
import android.content.pm.PackageManager
import android.hardware.biometrics.BiometricManager
import android.os.Build

fun getSupportedBiometricTypes(context: Context): Int {
    val biometricManager = BiometricManager.from(context)
    val authResult = biometricManager.canAuthenticate(
        BiometricManager.Authenticators.BIOMETRIC_STRONG or BiometricManager.Authenticators.BIOMETRIC_WEAK
    )
    
    if (authResult != BiometricManager.BIOMETRIC_SUCCESS) return 0
    
    var supportedTypes = 0
    val packageManager = context.packageManager
    
    // 检测指纹（强生物识别）
    if (packageManager.hasSystemFeature(PackageManager.FEATURE_FINGERPRINT)) {
        supportedTypes = supportedTypes or BiometricManager.Authenticators.BIOMETRIC_STRONG
    }
    
    // 检测面部（弱生物识别，Android 10+支持）
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q && 
        packageManager.hasSystemFeature(PackageManager.FEATURE_FACE)) {
        supportedTypes = supportedTypes or BiometricManager.Authenticators.BIOMETRIC_WEAK
    }
    
    return supportedTypes
}

2. 分版本构建PromptInfo

修改原有的createPromptInfo方法，针对Android 10及以下版本单独处理：

import android.app.Activity
import androidx.biometric.BiometricPrompt
import android.os.Build
import androidx.appcompat.app.AppCompatActivity

@Suppress("DEPRECATION")
fun createPromptInfo(activity: AppCompatActivity): BiometricPrompt.PromptInfo {
    val supportedBiometrics = getSupportedBiometricTypes(activity)
    
    return BiometricPrompt.PromptInfo.Builder().apply {
        setTitle(activity.getString(R.string.title))
        setSubtitle(activity.getString(R.string.subtitle))
        setConfirmationRequired(false)
        
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            // Android 11+ 使用细粒度控制，支持所有组合
            setAllowedAuthenticators(
                supportedBiometrics or BiometricManager.Authenticators.DEVICE_CREDENTIAL
            )
        } else {
            // Android 10及以下：先优先生物识别，设备凭据作为后续 fallback
            if (supportedBiometrics != 0) {
                setDeviceCredentialAllowed(false)
            } else {
                // 无可用生物识别，直接启用设备凭据
                setDeviceCredentialAllowed(true)
            }
        }
    }.build()
}

3. 拆分认证流程

在调用BiometricPrompt认证时，添加失败回调，当生物识别失败/取消时，再弹出设备凭据认证：

fun startBiometricAuth(activity: AppCompatActivity) {
    val promptInfo = createPromptInfo(activity)
    val biometricPrompt = BiometricPrompt(activity, 
        object : BiometricPrompt.AuthenticationCallback() {
            override fun onAuthenticationFailed() {
                super.onAuthenticationFailed()
                // 生物识别失败，启动设备凭据认证
                if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
                    val deviceCredentialPrompt = BiometricPrompt.PromptInfo.Builder()
                        .setTitle(activity.getString(R.string.title))
                        .setDeviceCredentialAllowed(true)
                        .build()
                    BiometricPrompt(activity, this@startBiometricAuth).authenticate(deviceCredentialPrompt)
                }
            }
            
            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                super.onAuthenticationError(errorCode, errString)
                // 用户取消或其他错误，同样启动设备凭据认证
                if (errorCode != BiometricPrompt.ERROR_USER_CANCELED && 
                    Build.VERSION.SDK_INT < Build.VERSION_CODES.R) {
                    val deviceCredentialPrompt = BiometricPrompt.PromptInfo.Builder()
                        .setTitle(activity.getString(R.string.title))
                        .setDeviceCredentialAllowed(true)
                        .build()
                    BiometricPrompt(activity, this@startBiometricAuth).authenticate(deviceCredentialPrompt)
                }
            }
            
            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                super.onAuthenticationSucceeded(result)
                // 认证成功逻辑
            }
        })
    
    biometricPrompt.authenticate(promptInfo)
}

额外注意事项 #

• 确保在AndroidManifest中声明生物识别权限：

<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" /> <!-- 兼容旧版本 -->

• 对于Android 10的三星设备，建议在应用内引导用户确认面部识别已在系统设置中启用并设置为优先选项。

内容的提问来源于stack exchange，提问作者Tuan