Biometrics Authentication

Overview

Biometrics Authentication gives Unity projects a single, cross-platform method for prompting the user to authenticate with their device biometrics:

• iOS — Face ID, Touch ID via LAContext
• macOS — Touch ID, Apple Watch unlock via LAContext
• Android — BiometricPrompt (Android 9+) with legacy FingerprintManager fallback
• WebGL — WebAuthn where the browser supports it

No native plumbing in your project, no Info.plist edits, no AndroidManifest surgery. Import the package and call one method.

Requirements

• Unity 2020.3 LTS or newer
• iOS 11+ / macOS 10.12+ / Android API 23+ / a WebAuthn-capable browser
• A device with biometrics configured (simulator Face ID works on iOS)

Installation

Unity Asset Store

Import Biometrics Authentication. The package auto-configures:

• iOS — adds NSFaceIDUsageDescription to the generated Xcode project,
• Android — adds USE_BIOMETRIC permission and updates AndroidManifest.xml,
• WebGL — drops in the WebAuthn JavaScript bridge under Plugins/WebGL/.

UPM via Git URL

https://github.com/simple-yet-efficient/biometrics-authentication.git

Quick start

using SyE.BiometricsAuthentication;
using UnityEngine;

public class LoginScreen : MonoBehaviour
{
    public void OnLoginTap()
    {
        Biometrics.Authenticate(
            onSuccess: () => {
                Debug.Log("Authenticated!");
                LoadHomeScene();
            },
            onFailure: () => {
                Debug.LogWarning("Authentication failed or cancelled.");
                ShowPasswordFallback();
            }
        );
    }
}

That's the entire API surface you need for 90% of apps. The plugin takes care of checking whether biometrics are available, what kind of biometric is configured, and what reason string to show on the OS prompt.

API reference

Biometrics.Authenticate(onSuccess, onFailure, reason?)

Prompts the user for biometric authentication.

• onSuccess — Action, invoked on successful auth.
• onFailure — Action, invoked on any failure, cancellation, or unsupported platform.
• reason (optional) — string shown on the OS prompt. Defaults to "Authenticate to continue". On iOS this appears below the Face ID / Touch ID UI; on Android it's the subtitle of the BiometricPrompt dialog.

Biometrics.Authenticate(
    onSuccess: Unlock,
    onFailure: ShowError,
    reason: "Confirm it's you to export your save file."
);

Biometrics.IsSupported()

Returns true if the current device can run biometric auth and has at least one biometric enrolled. Use this to decide whether to show a "Sign in with Face ID" button at all.

if (Biometrics.IsSupported()) {
    biometricButton.SetActive(true);
}

Platform notes

iOS / macOS

• Face ID requires NSFaceIDUsageDescription — the plugin inserts a sensible default, but you should customise it in your Xcode project for App Store review.
• Authentication is performed against LAContext with LAPolicyDeviceOwnerAuthenticationWithBiometrics. There's no passcode fallback by default. If you want passcode fallback, use Biometrics.AuthenticateWithDeviceCredential(...).

Android

• The package sets android:minSdkVersion to 23 in a merged manifest overlay. If your project targets lower, adjust before building.
• BiometricPrompt is used on API 28+; API 23–27 uses the legacy FingerprintManager wrapper.
• Custom ProGuard rules aren't required — the plugin ships with keep rules for the Android bridge.

WebGL

• Uses WebAuthn under the hood. The first call will prompt the user to register a credential; subsequent calls authenticate against it.
• Works in Chrome, Safari 14+, Edge, and Firefox 60+. Older browsers return onFailure — wire a password-based fallback.

Security model

The plugin does not store passwords or tokens. It only asks the OS whether the current user is the device owner. On success, you decide what that unlocks — typically:

• a cached refresh token from your own auth server,
• a local secret stored in the iOS Keychain / Android Keystore,
• a UI state change in a purely local app.

The plugin never sends anything over the network.

Troubleshooting

Symptom	Likely cause	Fix
onFailure fires immediately on Android	USE_BIOMETRIC not granted	Rebuild — the plugin adds it automatically; check AndroidManifest.xml
iOS app crashes on launch	Missing NSFaceIDUsageDescription	Edit the generated Xcode project's Info.plist
WebGL prompt never appears	Not on HTTPS	WebAuthn requires HTTPS (or http://localhost)
Custom prompt reason ignored	Using overload without reason	Pass the third arg

Support

• Issues: github.com/simple-yet-efficient/biometrics-authentication/issues
• Email: support@simpleyetefficient.com

Covered by the Unity Asset Store Standard EULA.