Kotlin Biometric Authentication: Complete Guide with Examples

Biometric authentication has become an essential feature in modern mobile apps. It lets users verify their identity using a fingerprint, face scan, or iris scan — much more convenient and secure than typing passwords. The Biometric library for Kotlin (part of AndroidX) provides a unified API for working with all biometric sensors on Android devices.

Why use this library? First, it abstracts away the differences in biometric sensor implementations across manufacturers. Second, it automatically handles scenarios where biometrics are unavailable (e.g., no scanner on the device) or locked. Third, the library integrates tightly with Android Keystore, allowing you to create cryptographically secure keys that can only be used after successful user authentication.

In this article, we'll dive deep into every aspect of working with the Biometric library for Kotlin: from installation and a minimal example to advanced techniques and common pitfalls. You'll learn how to add biometric authentication to your app, make it secure, and deliver a great user experience.

Installation

To use the Biometric library in your Android Kotlin project, add the following dependency to your module-level build.gradle file:

dependencies {
    implementation("androidx.biometric:biometric:1.2.0-alpha05")
}

Also, make sure to declare the biometric sensor permission in your AndroidManifest.xml:

If your app targets Android 12 (API 31) and above, it's recommended to add the permission for precise biometric type detection:

Quick Start: Minimal Working Example

Let's create a simple Activity that launches biometric authentication when a button is pressed and displays the result in a Toast.

import android.os.Bundle
import android.widget.Button
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.biometric.BiometricManager
import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import java.util.concurrent.Executors

class MainActivity : AppCompatActivity() {

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

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val authButton: Button = findViewById(R.id.auth_button)

        // Check if biometrics are available on the device
        val biometricManager = BiometricManager.from(this)
        when (biometricManager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_STRONG)) {
            BiometricManager.BIOMETRIC_SUCCESS -> {
                // Biometrics available, set up the dialog
                setupBiometricPrompt()
            }
            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> {
                Toast.makeText(this, "No biometric sensor on this device", Toast.LENGTH_LONG).show()
            }
            BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> {
                Toast.makeText(this, "Biometric sensor temporarily unavailable", Toast.LENGTH_LONG).show()
            }
            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> {
                Toast.makeText(this, "No biometric data enrolled", Toast.LENGTH_LONG).show()
            }
        }