Biometric authentication is no longer a feature reserved for native-only apps. Users expect to unlock their banking apps with a fingerprint or log into a health tracker with Face ID. If you maintain a Cordova app, you might wonder how to bridge the gap between a webview-based architecture and the secure hardware-backed biometric sensors on modern phones. The good news is that Cordova’s plugin ecosystem has matured enough in 2026 to make this integration not just possible, but reliable. This guide walks you through the exact steps to add Cordova biometric authentication to your cross-platform project, covering iOS, Android, and the gotchas that come with each.
Implementing biometric authentication in a Cordova app in 2026 requires a plugin that bridges JavaScript to native platform APIs. On iOS, you use the Keychain and Face ID APIs through a custom or maintained plugin. On Android, you tap into the BiometricPrompt API. The core challenge is handling fallback flows for devices without biometric sensors while keeping your user data secure and your app compliant with platform store policies.
Picking the Right Plugin for Cordova Biometric Authentication
Your first decision is the most important one. You need a plugin that talks to the operating system’s native biometric services. Avoid plugins that try to implement fingerprint matching in JavaScript. That approach is insecure and will get your app rejected from both the Apple Store and Google Play.
Look for a plugin that wraps these native APIs:
- iOS: Apple’s
BiometricManagerandKeychainAPIs. These handle Face ID and fingerprint enrollment and verification. - Android: The
BiometricPromptAPI, introduced in Android 10 and standard across all modern Android devices in 2026.
A solid choice in the Cordova ecosystem is cordova-plugin-biometry-keychain-access. It is open source and actively maintained. It exposes a simple JavaScript interface for enrollment and verification events.
Before you install anything, check your Cordova CLI version. Run cordova -v and make sure you are on at least version 12. Older versions have trouble resolving plugin dependencies for native modules.
Step by Step: Adding Biometric Login to Your Cordova App
Here is the practical flow. I will assume you have a standard Cordova project with www/ as your root and package.json at the top level.
1. Install the Plugin
Open your terminal in the project root and run:
cordova plugin add cordova-plugin-biometry-keychain-access
This pulls down the native stubs for both iOS and Android. The plugin will prompt you to configure the iOS keychain service identifier. For now, accept the default.
2. Request Biometric Permission (iOS Specific)
Apple requires your app to declare biometric intent in the manifest. Open your config.xml and add this inside the <platform name="ios"> block:
<preference name="ios-biometric-usage" value="authentication" />
Without this, the iOS runtime will silently deny your Face ID requests.
3. Write the JavaScript Wrapper
Create a file called biometric-auth.js in your www/js/ folder. Here is a minimal implementation:
var biometricAuth = {
enroll: function(userId) {
return new Promise(function(resolve, reject) {
cordova.plugins.biometry.enroll({
username: userId,
timeout: 30
}, function(result) {
resolve(result);
}, function(error) {
reject(error);
});
});
},
verify: function(userId) {
return new Promise(function(resolve, reject) {
cordova.plugins.biometry.verify({
username: userId
}, function(result) {
resolve(result.verified);
}, function(error) {
reject(error);
});
});
}
};
4. Wire It Into Your Login Screen
Call biometricAuth.verify() when the user taps the “Log in with fingerprint” button. If verification fails, fall back to a password field. The plugin returns a boolean. Do not store raw biometric data on your server. The plugin only returns a verification status.
5. Handle Android’s BiometricPrompt
Android uses a system dialog. When you call verify(), the operating system shows a native prompt to the user. You do not control the UI of that dialog. That is a good thing. It prevents spoofing. Make sure your Cordova app is not running in a sandboxed context that blocks system dialogs. Test on a physical Android device, not just an emulator.
Common Mistakes and How to Fix Them
Even experienced Cordova developers run into issues here. The table below maps the most frequent errors to their root causes and solutions.
| Mistake | Why It Happens | How to Fix It |
|---|---|---|
| Plugin fails to load on iOS | Missing ios-biometric-usage preference in config.xml |
Add the preference block shown in step 2 |
| Fingerprint prompt never shows on Android | App is running in a debug mode that suppresses system dialogs | Build with --release flag, or test on a device without USB debugging attached |
| Face ID returns “not available” on iOS | Device has no infrared camera or user denied permission | Check biometricAuth.isAvailable() before showing the biometric button |
| Enrollment succeeds but verification always fails | The plugin stored the biometric template in a different keychain slot | Clear the enrolled template with biometricAuth.remove(userId) and re-enroll |
| App crashes on older Android phones | The BiometricPrompt API is missing on Android 9 and below | Add a version check and hide the biometric button for unsupported OS versions |
Fallback Strategy: When Biometrics Are Not an Option
Not every device has a fingerprint reader or a Face ID camera. Some users opt out of biometrics entirely. Your authentication flow must degrade gracefully.
Here is what your login controller should check in order:
- Does the device have a biometric sensor available? Call the plugin’s availability method.
- Is the user already enrolled? If not, offer a guided enrollment process.
- If the sensor is missing or enrollment is declined, fall back to a standard password or PIN flow.
Do not force biometrics. Apple and Google both require that you provide a non-biometric alternative. A password manager integration or a one-time code via email are acceptable backups.
Security Considerations for 2026
Biometric data is sensitive. Treat it with the same care as a password hash. Follow these rules:
- Never transmit raw biometric data over the network. The plugin only returns a boolean verification result. That is all you need.
- Store biometric templates only in the device’s secure enclave. The plugin handles this automatically on both iOS and Android.
- Use the platform’s built-in liveness detection. Do not try to implement your own. Apple and Google update their anti-spoofing algorithms regularly. Trust them.
- Pair biometric authentication with a device-bound token. After a successful fingerprint scan, issue a short-lived JWT stored in the device keychain. This prevents replay attacks.
Expert advice from the Cordova security working group: “Always treat the biometric sensor as a second factor, never a sole factor. Combine it with something the user knows (a PIN) or something the user has (a registered device). This layered approach protects against the rare case of a false positive match.”
Testing Your Biometric Integration
Testing biometric code is harder than testing a button click. You cannot automate a fingerprint scan in a unit test. Here is a practical testing strategy:
- Use the plugin’s test mode. Most biometric plugins offer a
setTestMode(true)function that returns predefined responses. - On iOS, the simulator supports a mock Face ID enrollment. Go to Settings > Face ID & Passcode > Enroll a test face.
- On Android, use the
android biometric testtool from the Android SDK. It lets you simulate fingerprint touches. - Write integration tests that call your biometric wrapper functions. Run them on real hardware in your CI pipeline. Use a service like Sauce Labs or BrowserStack that offers physical device access.
For a deeper look at how to debug tricky plugin behavior, check out our guide on essential debugging tips for hybrid Cordova applications.
Updating Your Cordova Project for Platform Policy Changes
Both Apple and Google updated their biometric policies in early 2026. Here is what changed:
- Apple now requires that your app’s privacy policy explicitly state how biometric data is stored and that it never leaves the device.
- Google Play mandates a 30-second timeout on biometric prompts. If the user does not respond, the app must cancel the prompt and show an alternative login method.
Review your app’s privacy policy page. If you do not have one, create it before your next submission. The plugin handles the timeout automatically, but you must handle the cancellation event in your JavaScript. Listen for the biometry.cancelled event and route the user to the password fallback.
Building a Custom Plugin for Unique Needs
If the existing plugins do not fit your use case, you can build your own. Cordova supports native plugins written in C++ for iOS and Java for Android. This is an advanced path, but it gives you full control.
The process involves:
- Creating a new Cordova plugin skeleton with
cordova plugin create. - Writing the iOS native code using Apple’s
BiometricManagerclass. - Writing the Android native code using the
BiometricPrompt.Builder. - Exposing a JavaScript API that matches the native calls.
For a complete walkthrough of the plugin creation process, read our guide on mastering Cordova plugin development for cross-platform compatibility.
Most developers will not need a custom plugin. The maintained options are stable in 2026. But if you need to support a niche biometric sensor like iris scanning or voice recognition, a custom plugin is the way to go.
Performance Impact on Your Cordova App
Biometric operations are fast. A fingerprint scan takes about 200 milliseconds on modern hardware. Face ID takes closer to 500 milliseconds on iOS. These calls happen on a native thread, so they do not block your JavaScript event loop.
However, the enrollment process can take up to 10 seconds because the device needs to capture multiple samples. During enrollment, show a progress indicator to the user. Do not let the app appear frozen.
If you notice lag after adding the biometric plugin, profile your app’s startup time. The plugin loads native libraries that can add 100 to 300 milliseconds to your app’s cold start. That is usually acceptable, but you can optimize by optimizing Cordova app startup time for better user experience.
Future Proofing Your Biometric Code
Operating systems update their biometric APIs every few years. iOS 18 and Android 16 both introduced new privacy controls. Here is how to keep your integration working:
- Abstract your biometric calls behind a service class. If the plugin API changes, you only update one file.
- Subscribe to the plugin’s GitHub repository for breaking change announcements.
- Test your app against developer previews of iOS and Android releases. Cordova’s community usually posts compatibility notes within days of a new OS beta.
For a broader look at keeping your app stable across OS updates, see our piece on 5 ways to future proof your Cordova apps against OS updates.
Putting It All Together
You now have a clear path to add Cordova biometric authentication to your app. Start by choosing a maintained plugin. Install it and add the required platform preferences. Write a simple JavaScript wrapper for enrollment and verification. Always provide a fallback for devices without biometric sensors. Test on real hardware, not just simulators. Keep your privacy policy updated.
Biometric login is not a gimmick. It reduces friction for your users and increases security by tying authentication to a physical characteristic they always have with them. Your Cordova app can deliver this experience without rewriting the entire stack in native code. The plugins are ready. The APIs are stable. The only missing piece is your implementation.
Go ahead and add that fingerprint button to your login screen. Your users will thank you.