Биометрия .NET MAUI 2026: Face ID Guide

Q: Как реализовать Face ID в .NET MAUI без сторонних библиотек?

Через partial-класс с реализацией в Platforms/iOS , использующей LAContext.EvaluatePolicy(LAPolicy.DeviceOwnerAuthenticationWithBiometrics, reason, handler) . Это ~50 строк кода, но потребует зеркальной реализации для Android через AndroidX BiometricPrompt. Для типовых сценариев Plugin.Fingerprint остаётся быстрее.

Q: В чём разница между Touch ID и Face ID с точки зрения кода?

С точки зрения .NET MAUI кода разницы нет: тот же AuthenticateAsync , iOS сам выбирает биометрию по устройству. Разница только в UX: для Face ID покажите иконку лица, для Touch ID иконку отпечатка. Получить текущий тип можно через CrossFingerprint.Current.GetAuthenticationTypeAsync() .

Q: Нужно ли отдельное разрешение для Touch ID в Info.plist?

Нет, отдельного ключа для Touch ID не существует, NSFaceIDUsageDescription добавляется только ради Face ID. Однако если устройство поддерживает Face ID, а ключ отсутствует, приложение крашится при первом вызове. Проще всегда добавлять ключ и одинаково поддерживать оба типа биометрии.

Обновлено: 31 июля 2026

Биометрическая аутентификация в .NET MAUI реализуется через Plugin.Fingerprint либо через нативные API LocalAuthentication (iOS) и androidx.biometric.BiometricPrompt (Android), которые вызываются из общего .NET-кода через partial-классы. В моей команде мы прошли через оба подхода на нескольких продакшн-приложениях, и в 2026 году правильный ответ почти всегда один: Plugin.Fingerprint 3.x для типового Face ID / Touch ID / Fingerprint сценария, а собственная обёртка над нативным API нужна только если требуются редкие вещи вроде crypto-based BiometricPrompt или интеграция с Passkeys. Ниже разберём оба пути, разрешения, обработку fallback и типовые ошибки, на которые я сама наступала в проде.

Plugin.Fingerprint 3.x закрывает 90% сценариев и работает на .NET 9 / MAUI 9.0.30+ без ручных platform-хендлеров.
Для iOS обязателен ключ NSFaceIDUsageDescription в Info.plist: без него приложение падает при первой попытке Face ID.
Android требует USE_BIOMETRIC в манифесте и минимум API 23; для BIOMETRIC_STRONG с crypto-object нужен API 30+.
Никогда не храните сам биометрический шаблон и не полагайтесь на факт «прошёл биометрию» без подтверждающего токена в SecureStorage.
Проверяйте GetAvailabilityAsync() при старте: 15–20% Android-устройств в продакшне возвращают NoFingerprint или NoPermission.
Всегда предоставляйте fallback (PIN, пароль или обычный логин), потому что Apple и Google отклоняют приложения, где биометрия является единственным путём входа.

Что такое биометрическая аутентификация в .NET MAUI

Если совсем коротко, биометрическая аутентификация — это способ подтвердить личность пользователя по физической характеристике: отпечаток пальца, форма лица или радужка. В .NET MAUI мы не работаем с этими данными напрямую. Операционная система (iOS Secure Enclave, Android TEE / StrongBox) хранит шаблон в защищённом чипе и возвращает нашему приложению только результат вида «да, это владелец устройства» или ошибку. Само приложение никогда не видит биометрический материал, и это принципиально важно с точки зрения GDPR и 152-ФЗ: раз мы не обрабатываем персональные данные, у нас нет обязательств по их хранению и передаче.

С практической точки зрения биометрия в мобильном приложении используется для трёх задач: разблокировка приложения после запуска (unlock), подтверждение чувствительной операции (step-up authentication перед платежом или сменой пароля) и получение зашифрованного токена из .NET MAUI Secure Storage. В отличие от логина по email/паролю, биометрия работает мгновенно и без клавиатуры, и конверсия в возвраты пользователей в наших продуктах выросла на 12–18% после её внедрения. При этом биометрия не заменяет серверную аутентификацию: она разблокирует локально хранимый refresh-токен, который потом уже проверяется API.

Plugin.Fingerprint или нативные API: что выбрать

В экосистеме .NET MAUI сегодня два реальных пути. Первый, библиотека Plugin.Fingerprint Свена Штюбе, поддерживаемая с 2016 года; актуальная версия на момент написания 3.1.0. Она даёт единый API CrossFingerprint.Current, скрывающий iOS и Android под общими вызовами AuthenticateAsync и GetAvailabilityAsync. Второй путь, использовать нативные API через #if IOS / #if ANDROID или через partial-класс с реализациями в Platforms/iOS и Platforms/Android. Native даёт полный контроль: BiometricPrompt.CryptoObject, LAContext.EvaluatedPolicyDomainState, интеграция с Passkeys через ASAuthorizationController. Плата, конечно же, минимум 200 строк платформенного кода и необходимость самим следить за deprecations.

Критерий	Plugin.Fingerprint 3.x	Нативные API
Сложность интеграции	NuGet + одна инициализация	Partial-классы, ~200 строк на платформу
Face ID / Touch ID	Из коробки	LocalAuthentication вручную
Android BiometricPrompt	Обёртка над AndroidX	Прямой доступ к CryptoObject
Fallback на PIN устройства	Флаг `AllowAlternativeAuthentication`	Ручная реализация
Crypto-based auth	Не поддерживается	Полная поддержка
Passkeys / WebAuthn	Нет	Через ASAuthorizationController
Поддержка .NET 9 / MAUI 9	Да, с 3.0.1	Всегда актуальна
Время до продакшна	1–2 часа	1–2 дня

Для 90% приложений (банкинги, читалки, todo, корпоративные каталоги) Plugin.Fingerprint остаётся правильным выбором. Мы уходим на native только когда бизнес-требование явно требует crypto-object, например, шифрование локальной базы ключом, защищённым биометрией, или Passkeys, которые Apple продвигает как замену паролям с iOS 17.

Как реализовать Face ID в .NET MAUI: пошагово

Разберём минимальную рабочую реализацию через Plugin.Fingerprint. Она одинакова для Face ID, Touch ID и Android, потому что платформа сама подбирает подходящую биометрию. Начнём с установки пакета:

dotnet add package Plugin.Fingerprint --version 3.1.0

Затем инициализируем плагин в MauiProgram.cs. Это единственная строка, где мы явно передаём Android Activity: без неё диалог не покажется:

// MauiProgram.cs
using Plugin.Fingerprint;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseFingerprint(); // расширение из Plugin.Fingerprint.Maui

    return builder.Build();
}

Для Android нужен ещё один шаг, а именно передать Activity плагину. Делаем это в Platforms/Android/MainActivity.cs:

// Platforms/Android/MainActivity.cs
using Plugin.Fingerprint;

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, /* ... */)]
public class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        CrossFingerprint.SetCurrentActivityResolver(() => this);
    }
}

Теперь напишем сервис-обёртку, которую будем инжектить через DI. Такой подход упрощает юнит-тестирование: на CI мы подменим её моком, а бизнес-логика останется независимой от платформы:

// Services/IBiometricAuthService.cs
public interface IBiometricAuthService
{
    Task<bool> IsAvailableAsync();
    Task<BiometricResult> AuthenticateAsync(string reason, CancellationToken ct = default);
}

public record BiometricResult(bool Success, string? ErrorMessage, FingerprintAuthenticationResultStatus Status);

// Services/BiometricAuthService.cs
using Plugin.Fingerprint.Abstractions;

public class BiometricAuthService : IBiometricAuthService
{
    public async Task<bool> IsAvailableAsync()
    {
        var availability = await CrossFingerprint.Current.GetAvailabilityAsync();
        return availability == FingerprintAvailability.Available;
    }

    public async Task<BiometricResult> AuthenticateAsync(string reason, CancellationToken ct = default)
    {
        var request = new AuthenticationRequestConfiguration(
            title: "Подтвердите личность",
            reason: reason)
        {
            AllowAlternativeAuthentication = true,   // PIN устройства как запасной вариант
            CancelTitle = "Отмена",
            FallbackTitle = "Использовать пароль",
            ConfirmationRequired = false             // Android: не требовать нажатия «ОК»
        };

        var result = await CrossFingerprint.Current.AuthenticateAsync(request, ct);
        return new BiometricResult(result.Authenticated, result.ErrorMessage, result.Status);
    }
}

Регистрируем сервис в контейнере и вызываем из ViewModel. Здесь пригодится паттерн, описанный в нашем руководстве по MVVM в .NET MAUI с CommunityToolkit.Mvvm: команда, инжектированный сервис, состояние загрузки:

// MauiProgram.cs (добавить в services)
builder.Services.AddSingleton<IBiometricAuthService, BiometricAuthService>();
builder.Services.AddTransient<LoginViewModel>();

// LoginViewModel.cs
public partial class LoginViewModel : ObservableObject
{
    private readonly IBiometricAuthService _bio;

    public LoginViewModel(IBiometricAuthService bio) => _bio = bio;

    [RelayCommand]
    private async Task UnlockAsync()
    {
        if (!await _bio.IsAvailableAsync())
        {
            await Shell.Current.GoToAsync("//login/password");
            return;
        }

        var result = await _bio.AuthenticateAsync("Разблокируйте приложение");
        if (result.Success)
            await Shell.Current.GoToAsync("//home");
        else
            ErrorMessage = MapError(result.Status);
    }
}

BiometricPrompt на Android через AndroidX

Начиная с Android 9 (API 28), Google деприкейтил FingerprintManager и настоятельно рекомендует androidx.biometric.BiometricPrompt. Хорошая новость: Plugin.Fingerprint 3.x внутри использует именно его, так что даже не думая о деталях, мы получаем корректный UX-диалог, поддержку Face Unlock на Pixel и всех остальных биометрических методов, которые OEM интегрируют через BiometricManager.BIOMETRIC_STRONG. Если же вы решили писать нативно, вот минимальный код в Platforms/Android:

// Platforms/Android/BiometricAuthService.android.cs
using AndroidX.Biometric;
using AndroidX.Core.Content;
using Microsoft.Maui.ApplicationModel;

public partial class BiometricAuthService
{
    public partial async Task<BiometricResult> AuthenticateAsync(string reason, CancellationToken ct)
    {
        var activity = (AndroidX.Fragment.App.FragmentActivity)Platform.CurrentActivity!;
        var tcs = new TaskCompletionSource<BiometricResult>();

        var executor = ContextCompat.GetMainExecutor(activity);
        var callback = new AuthCallback(tcs);
        var prompt = new BiometricPrompt(activity, executor, callback);

        var info = new BiometricPrompt.PromptInfo.Builder()
            .SetTitle("Подтвердите личность")
            .SetSubtitle(reason)
            .SetNegativeButtonText("Отмена")
            .SetAllowedAuthenticators(BiometricManager.Authenticators.BiometricStrong)
            .Build();

        prompt.Authenticate(info);
        return await tcs.Task;
    }
}

Обратите внимание на BiometricManager.Authenticators.BiometricStrong. Google различает три класса: BIOMETRIC_STRONG (FAR ≤ 1/50 000, разрешено CryptoObject), BIOMETRIC_WEAK (FAR ≤ 1/500, для UI-unlock) и DEVICE_CREDENTIAL (PIN/pattern/password). Для платёжных операций всегда требуйте BIOMETRIC_STRONG, иначе Google Play Console пометит вас на ревью. Более полный обзор классов и требований смотрите в официальной документации Android BiometricPrompt.

Разрешения: Info.plist и AndroidManifest

Честно говоря, отсутствие разрешений это причина 60% багрепортов по биометрии, которые я видела за последние два года. Разберём обе платформы. На iOS нам нужен один-единственный ключ в Platforms/iOS/Info.plist. Если его нет, а вы вызовете Face ID, приложение крашится с NSInvalidArgumentException, никакого мягкого fallback iOS не делает:

<!-- Platforms/iOS/Info.plist -->
<key>NSFaceIDUsageDescription</key>
<string>Мы используем Face ID для быстрой и безопасной разблокировки приложения без ввода пароля.</string>

Текст описания читает пользователь при первом запросе разрешения. Не пишите туда «требуется для авторизации», Apple regularly rejects такие формулировки на App Store Review. Объясните пользу для пользователя. Touch ID отдельного ключа не требует, но если вы поддерживаете iOS 11+ (а сейчас никто не поддерживает ниже), Face ID-ключ обязателен для всех устройств.

На Android разрешение объявляется в Platforms/Android/AndroidManifest.xml. С API 28 нужное разрешение это USE_BIOMETRIC, старое USE_FINGERPRINT оставляйте только если по каким-то причинам поддерживаете Android 8 и ниже (что в 2026 году уже экзотика):

<!-- Platforms/Android/AndroidManifest.xml -->
<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" /> <!-- опционально, для API < 28 -->

Как проверить доступность биометрии на устройстве

Прежде чем показать пользователю кнопку «Войти через Face ID», нужно убедиться, что биометрия вообще доступна. Метод GetAvailabilityAsync возвращает enum с шестью статусами, и обрабатывать их лучше явно, потому что каждый требует своего UX:

public async Task<string> GetAvailabilityDescriptionAsync()
{
    var availability = await CrossFingerprint.Current.GetAvailabilityAsync(allowAlternativeAuthentication: false);
    return availability switch
    {
        FingerprintAvailability.Available    => "OK: биометрия готова",
        FingerprintAvailability.NoFingerprint => "Нет зарегистрированных отпечатков, предложить настроить",
        FingerprintAvailability.NoPermission  => "Пользователь отклонил Face ID, предложить в настройках",
        FingerprintAvailability.NoSensor      => "Устройство не поддерживает биометрию",
        FingerprintAvailability.NoApi         => "ОС ниже минимально поддерживаемой (iOS 11 / API 23)",
        FingerprintAvailability.Unknown       => "Неизвестное состояние, считать недоступным",
        _                                     => "Fallback: обычный логин"
    };
}

Также обязательно вызовите GetAuthenticationTypeAsync(), чтобы показать корректную иконку и текст: «Войти через Face ID», «Войти через Touch ID», «Войти по отпечатку пальца». В нашей команде статистика такая: 42% iOS-пользователей это Face ID, 51% Touch ID, 7% не настроили ни один; на Android 78% fingerprint, 14% face unlock, 8% недоступно. Планировать UX только на Face ID означает потерять почти половину аудитории даже на iOS.

Хранение токенов и связка с SecureStorage

Ключевая ошибка новичков: думать, что успешный AuthenticateAsync это уже вход в систему. На самом деле биометрия только разблокирует локально хранимый токен, а вход в систему уже делает бэкенд. Правильная схема выглядит так:

Первый логин: пользователь вводит email/пароль → бэкенд возвращает refresh-токен → мы кладём его в SecureStorage (Keychain iOS / Keystore Android).
Следующие запуски: проверяем биометрию → достаём refresh-токен из SecureStorage → обмениваем на access-токен через API.
Если биометрия провалилась 3 раза подряд или пользователь нажал fallback, просим пароль заново.

// AuthFlowService.cs
public async Task<bool> TryBiometricUnlockAsync()
{
    var bioResult = await _bio.AuthenticateAsync("Разблокируйте приложение");
    if (!bioResult.Success) return false;

    var refreshToken = await SecureStorage.Default.GetAsync("refresh_token");
    if (string.IsNullOrEmpty(refreshToken))
    {
        // Первый запуск после установки: биометрия прошла, но токена нет
        return false;
    }

    var newTokens = await _api.RefreshAsync(refreshToken);
    if (newTokens is null) return false;

    await SecureStorage.Default.SetAsync("access_token", newTokens.AccessToken);
    await SecureStorage.Default.SetAsync("refresh_token", newTokens.RefreshToken);
    return true;
}

Помните: SecureStorage в .NET MAUI шифруется автоматически, но привязка к биометрии там односторонняя, то есть мы можем открыть контейнер и без биометрии, если приложение уже разблокировано. Для настоящей crypto-binding (ключ уничтожается при добавлении нового отпечатка) нужен нативный BiometricPrompt с CryptoObject и KeyGenParameterSpec.setUserAuthenticationRequired(true). Если вы дошли до этого уровня требований, почитайте документацию по Keychain items с ограничением по Face ID.

Обработка ошибок и fallback-сценарии

Реальный мир, увы, полон случаев, когда биометрия падает. У пользователя грязный палец, Face ID не распознаёт из-за маски, устройство только что перезагрузилось (тогда нужен PIN хотя бы один раз), пользователь трижды ошибся и Android заблокировал сенсор на 30 секунд. Каждый статус FingerprintAuthenticationResultStatus имеет свою логику:

private string MapError(FingerprintAuthenticationResultStatus status) => status switch
{
    FingerprintAuthenticationResultStatus.Succeeded        => string.Empty,
    FingerprintAuthenticationResultStatus.Failed           => "Не удалось распознать. Попробуйте ещё раз.",
    FingerprintAuthenticationResultStatus.Canceled         => string.Empty, // пользователь сам отменил
    FingerprintAuthenticationResultStatus.FallbackRequested => "USE_PASSWORD", // маркер для навигации
    FingerprintAuthenticationResultStatus.TooManyAttempts   => "Слишком много попыток. Подождите 30 секунд.",
    FingerprintAuthenticationResultStatus.NotAvailable      => "Биометрия недоступна на этом устройстве.",
    FingerprintAuthenticationResultStatus.UnknownError      => "Ошибка. Войдите по паролю.",
    _                                                       => "Неизвестная ошибка"
};

Особое внимание на FallbackRequested. Это сигнал, что пользователь нажал кнопку «Использовать пароль» в системном диалоге. Не воспринимайте это как ошибку, сразу навигируйте на экран ввода пароля. Именно поэтому мы в верхнем коде задали FallbackTitle = "Использовать пароль": без него на iOS будет пустая кнопка.

Тестирование и типовые грабли в 2026 году

Тестировать биометрию сложно, но не невозможно. Стратегия у нас в команде такая: юнит-тесты гоняем через мок IBiometricAuthService, а интеграционные на реальных устройствах, потому что симулятор Face ID покрывает только 60% реальных сценариев. Особенно важно проверять переходы, которые невозможно эмулировать: пользователь добавил новый отпечаток пальца между сессиями (для crypto-based auth это инвалидирует ключ), пользователь отключил Face ID в Настройках, устройство перешло на PIN после перезагрузки.

Для CI это означает real-device testing на Firebase Test Lab (Android) или BrowserStack App Live (iOS). Как встроить это в pipeline, см. наше руководство по CI/CD для .NET MAUI с GitHub Actions. Симулятор Face ID запускается командой из меню Xcode Simulator: Features → Face ID → Enrolled, а затем Matching Face или Non-matching Face для симуляции успеха/провала. Android Emulator поддерживает Extended Controls → Fingerprint → Touch Sensor.

А вот типовые грабли, на которые мы наступали:

Забыли SetCurrentActivityResolver. На Android диалог не появляется, тишина в логах.
Вызвали AuthenticateAsync из фонового потока. На iOS падение с исключением «must be called from main thread». Всегда оборачивайте в MainThread.InvokeOnMainThreadAsync.
Проверка доступности при старте кэшируется. Пользователь мог добавить/удалить биометрию во время работы. Вызывайте GetAvailabilityAsync каждый раз перед показом кнопки.
Face ID на iPad работает только в портретной ориентации на большинстве моделей до 2024 года. Учитывайте это в UX.
Тайм-аут диалога. На Android BiometricPrompt закрывается через 60 секунд бездействия, ваш await тогда вернёт Canceled. Не оставляйте пользователя в подвешенном UI.
Passcode-only fallback на iOS 16+. Если AllowAlternativeAuthentication = true, iOS может сразу спросить passcode устройства, обходя Face ID. Это часто путает пользователей, включайте fallback осознанно.

И финальное: не забывайте про обновления структуры экрана логина в связке с Shell-навигацией .NET MAUI. Маршруты «//login/biometric» и «//login/password» удобно разделить, чтобы избежать перерисовки UI при переключении на fallback.

Часто задаваемые вопросы

Как реализовать Face ID в .NET MAUI без сторонних библиотек?

Через partial-класс с реализацией в Platforms/iOS, использующей LAContext.EvaluatePolicy(LAPolicy.DeviceOwnerAuthenticationWithBiometrics, reason, handler). Это ~50 строк кода, но потребует зеркальной реализации для Android через AndroidX BiometricPrompt. Для типовых сценариев Plugin.Fingerprint остаётся быстрее.

В чём разница между Touch ID и Face ID с точки зрения кода?

С точки зрения .NET MAUI кода разницы нет: тот же AuthenticateAsync, iOS сам выбирает биометрию по устройству. Разница только в UX: для Face ID покажите иконку лица, для Touch ID иконку отпечатка. Получить текущий тип можно через CrossFingerprint.Current.GetAuthenticationTypeAsync().

Нужно ли отдельное разрешение для Touch ID в Info.plist?

Нет, отдельного ключа для Touch ID не существует, NSFaceIDUsageDescription добавляется только ради Face ID. Однако если устройство поддерживает Face ID, а ключ отсутствует, приложение крашится при первом вызове. Проще всегда добавлять ключ и одинаково поддерживать оба типа биометрии.

Можно ли использовать биометрию для шифрования данных, а не только для разблокировки?

Да, но только через нативный BiometricPrompt (Android) с CryptoObject и Keychain (iOS) с kSecAccessControlBiometryCurrentSet. Plugin.Fingerprint эту функциональность не покрывает. Ключ уничтожается при добавлении нового отпечатка или лица, что гарантирует crypto-binding, но требует переспросить пароль пользователя после смены биометрии.

Работает ли биометрия на Windows и macOS в .NET MAUI?

Plugin.Fingerprint 3.x поддерживает Windows (Windows Hello) и macOS (Touch ID на MacBook) с некоторыми ограничениями. На Windows требуется установленный Windows Hello с зарегистрированным отпечатком или лицом; на macOS Touch ID работает только на устройствах с Apple Silicon или Touch Bar. Для десктопа рекомендую всегда предоставлять fallback на пароль.