Ключи доступа в нативных приложениях: нативная реализация vs. реализация через WebView

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

Примечание: System WebView и Embedded WebView часто комбинируют: System WebView обрабатывает вход в систему (с автоматическим доступом к учетным данным), а затем Embedded WebView отображает управление ключами доступа в настройках.

Ключевые факторы для принятия решения:

• Вход на основе OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• Хотите повторно использовать веб-аутентификацию в нативной оболочке? → Embedded WebView (WKWebView, Android WebView с WebKit 1.12.1+)
• Создаете приложение с нуля (native-first)? → Нативная реализация (Apple AuthenticationServices, Google Credential Manager)

Современные мобильные платформы предлагают три различных подхода к интеграции ключей доступа в ваше нативное приложение, каждый из которых имеет свои компромиссы в плане пользовательского опыта, технической сложности и совместимости с OAuth:

1. Нативная реализация: Встройте потоки работы с ключами доступа непосредственно в ваше приложение, используя API платформы (AuthenticationServices для iOS, Credential Manager для Android). Обеспечивает лучший пользовательский опыт с бесшовной биометрической аутентификацией, но требует средних или высоких затрат на техническую реализацию.

2. System WebView: Используйте браузерный компонент платформы (ASWebAuthenticationSession / SFSafariViewController для iOS, Chrome Custom Tabs для Android), чтобы обрабатывать аутентификацию. Отлично подходит для потоков входа на основе OAuth и использует общие учетные данные с системным браузером.

3. Embedded WebView: Встройте настраиваемое веб-представление (WKWebView для iOS, Android WebView) в ваше приложение, чтобы повторно использовать веб-аутентификацию с нативной оболочкой. Обеспечивает внешний вид, подобный нативному, без URL-строки и с полным контролем над интерфейсом веб-представления. Требует дополнительной настройки, включая разрешения и права (entitlements) для iOS, а также конфигурацию WebView с AndroidX WebKit 1.12.1+ (Android) для включения функциональности ключей доступа.

Правильный выбор зависит от архитектуры аутентификации вашего приложения, использования провайдеров OAuth, степени необходимого контроля над UI и того, создаете ли вы приложение с нуля или повторно используете веб-компоненты.

Нативная реализация ключей доступа обеспечивает оптимальный пользовательский опыт, где потоки аутентификации встроены непосредственно в UI вашего приложения с помощью специфичных для платформы API. Пользователи получают преимущества в виде нативных диалоговых окон, бесшовной биометрической проверки и максимально быстрого входа в систему.

Когда выбирать нативную реализацию:

• При создании нового нативного приложения или рефакторинге аутентификации на нативные экраны
• Если вы хотите обеспечить наилучший возможный пользовательский опыт с мгновенной, бесшумной аутентификацией
• Автоматические запросы на использование ключей доступа при запуске приложения: Нативные реализации могут использовать preferImmediatelyAvailableCredentials для автоматического отображения оверлея с ключами доступа, когда они доступны, обеспечивая самый быстрый вход без необходимости вводить идентификатор
• Требуется полный контроль над UI и потоком аутентификации
• Готовы инвестировать в реализацию для конкретной платформы (iOS Swift, Android Kotlin)

Ключевое преимущество: preferImmediatelyAvailableCredentials()

Нативные реализации могут использовать preferImmediatelyAvailableCredentials() для создания автоматического оверлея с ключами доступа, который появляется сразу при запуске приложения, если доступны ключи доступа. Этот поток без ввода имени пользователя обеспечивает максимально быстрый вход в систему — пользователи видят свои ключи доступа мгновенно, не вводя сначала идентификатор. Эта возможность эксклюзивна для нативных реализаций и недоступна в вариантах с WebView.

Хотя реализации с WebView могут использовать Conditional UI (предложения ключей доступа в полях ввода), автоматический оверлей в нативных приложениях обеспечивает превосходный UX с более высокими показателями использования ключей доступа, так как аутентификация начинается сразу при запуске приложения.

Обзор технических требований:

Нативная интеграция ключей доступа требует криптографического доверия между вашим приложением и веб-доменом. Без него ОС будет отклонять все операции WebAuthn. Ключевые требования:

1. Файлы ассоциации приложения и домена, размещенные в /.well-known/
2. Правильный Relying Party ID, соответствующий вашему веб-домену
3. Специфичные для платформы возможности (подробно в разделе 4)

Главное преимущество: ключи доступа, созданные на вашем веб-сайте, без проблем работают в вашем приложении и наоборот.

Нативная реализация ключей доступа на iOS включает использование фреймворка AuthenticationServices от Apple, который предоставляет API для операций WebAuthn:

Ключевые компоненты:

• ASAuthorizationController: Управляет потоком аутентификации
• ASAuthorizationPlatformPublicKeyCredentialProvider: Создает запросы на использование ключей доступа
• Три различных режима UI для обработки входов с помощью ключей доступа:
  • Вход через текстовое поле: Традиционное поле для имени пользователя с входом по ключу доступа, который начинается при нажатии кнопки
  • Модальный оверлей с ключами доступа: Диалоговое окно ОС со списком доступных ключей доступа
  • Conditional UI: Предложения ключей доступа в панели QuickType над клавиатурой

Советы по разработке

• Кэширование AASA: Apple агрессивно кэширует файл AASA (до 24 часов), что может затруднить тестирование. Решение: включите режим разработчика на тестовом устройстве и добавьте ?mode=developer к URL вашего AASA, чтобы принудительно загрузить свежую версию
• Тестирование производительности: Тестируйте с учетными записями iCloud, содержащими сотни учетных данных, чтобы оценить задержку в реальных условиях. Системный оверлей может показывать небольшую задержку при большом количестве сохраненных ключей доступа

Нативная реализация ключей доступа на Android использует Credential Manager API (или более старый FIDO2 API для обратной совместимости):

Ключевые компоненты:

• CredentialManager: Центральный API для всех операций с учетными данными
• CreatePublicKeyCredentialRequest: Для регистрации ключа доступа
• GetCredentialRequest: Для аутентификации с помощью ключа доступа
• Два основных режима UI:
  • Вход через текстовое поле: Традиционное поле для имени пользователя с входом по ключу доступа, который начинается при нажатии кнопки
  • Модальный оверлей с ключами доступа: Диалоговое окно ОС со списком доступных ключей доступа

Примечание: в нативных приложениях Android в настоящее время отсутствует аналог Conditional UI для iOS (предложения на клавиатуре), хотя Conditional UI работает в веб-приложениях.

Реализация ключей доступа нативно сопряжена с важными проблемами и уроками: интеграция на уровне ОС может выявить проблемы на разных устройствах и версиях ОС.

1. Например, наша команда столкнулась с такими проблемами, как агрессивное кэширование Apple файла apple-app-site-association (используемого для связывания учетных данных приложения и веба) и незначительными различиями в UI в запросах биометрии от некоторых OEM-производителей Android.
2. Более того, учтите, что в некоторых корпоративных сценариях на управляемых устройствах синхронизация ключей доступа может быть отключена политикой. В корпоративных средах, где синхронизация iCloud Keychain или Google Password Manager отключена, ключи доступа становятся привязанными к устройству и не перемещаются — это важный сценарий, который нужно предусмотреть (например, убедиться, что пользователи все еще могут войти в систему, если у них появится новый телефон).
3. Кроме того, сторонние приложения-менеджеры учетных данных могут влиять на процесс. Например, если у пользователя в качестве активного провайдера учетных данных установлен менеджер паролей, например 1Password, он часто будет перехватывать создание и хранение ключей доступа, имея приоритет над нативным менеджером учетных данных платформы.

Хотя вы можете реализовать ключи доступа, используя "сырые" API платформы, специализированные SDK значительно ускоряют разработку, обрабатывая сложность WebAuthn, крайние случаи и предоставляя встроенную телеметрию. SDK также предлагают макетные интерфейсы для модульного тестирования (что крайне важно, поскольку вы не можете тестировать биометрию в симуляторах).

Рекомендация: Для нативных реализаций мы рекомендуем использовать SDK от Corbado (iOS Swift Passkey SDK, Android Kotlin Passkey SDK), которые обрабатывают многочисленные крайние случаи, обнаруженные в ходе производственных развертываний, и предоставляют дополнительную телеметрию и возможности для тестирования.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

Corbado proved to be a trusted partner. Their hands-on, 24/7 support and on-site assistance enabled a seamless integration into VicRoads' complex systems, offering passkeys to 5 million users.

Passkeys, которые принимают миллионы. Быстро. Начните с платформы внедрения Corbado.

Начать бесплатно

System WebView используют нативный браузерный компонент платформы для обработки аутентификации внутри вашего приложения. В отличие от полностью нативных реализаций, System WebView отображают веб-контент, используя фактический системный браузер (Safari на iOS, Chrome на Android), сохраняя общие cookie, сохраненные учетные данные и знакомые индикаторы безопасности браузера.

Когда выбирать System WebView:

• Ваше приложение использует вход на основе OAuth: System WebView — это рекомендуемый подход для потоков OAuth2/OIDC, обеспечивающий безопасную аутентификацию.
• Существующая веб-аутентификация, которую вы хотите повторно использовать в мобильных приложениях.
• Необходимо поддерживать несколько методов аутентификации (пароли, вход через соцсети, ключи доступа) без переписывания нативно.
• Хотите поддерживать единую кодовую базу аутентификации для веба и мобильных устройств.

Ключевые преимущества:

• Совместимость с OAuth: Специально создано для потоков аутентификации OAuth/OIDC.
• Индикаторы безопасности: Пользователи видят фактический URL и SSL-сертификаты, что укрепляет доверие.
• Низкие затраты на реализацию: Требуется минимальный нативный код.
• Единообразный UX: Знакомый интерфейс браузера, которому пользователи уже доверяют.

Компоненты платформы:

• iOS: ASWebAuthenticationSession (рекомендуется для потоков аутентификации) или SFSafariViewController (для общего просмотра).
• Android: Chrome Custom Tabs (CCT).

Крупные компании, такие как Google и GitHub, приняли этот подход для добавления входа по ключу доступа в свои мобильные приложения через оверлеи WebView на существующих страницах веб-аутентификации. Это хорошо работает, когда полная перестройка аутентификации на нативную основу не является немедленно осуществимой.

iOS предоставляет два основных компонента System WebView для аутентификации:

ASWebAuthenticationSession (Рекомендуется для аутентификации):

• Специально создан для OAuth/OIDC и безопасных потоков входа.
• Автоматически запрашивает у пользователя разрешение на аутентификацию для приложения.
• Использует общие cookie и учетные данные с Safari.
• Поддерживает ключи доступа через iCloud Keychain.

SFSafariViewController (Общий просмотр):

• Полный опыт Safari внутри приложения.
• Показывает URL-строку и индикаторы безопасности.
• Не использует общие cookie Safari на iOS 11+; используйте ASWebAuthenticationSession, когда требуется общий доступ к сессии Safari.
• Менее настраиваемый, но вызывает больше доверия у пользователей.

Если ваше приложение использует вход на основе OAuth, ASWebAuthenticationSession — это рекомендуемый выбор, так как он специально разработан для сценариев аутентификации и обеспечивает лучший баланс безопасности и пользовательского опыта.

Chrome Custom Tabs (CCT) обеспечивают аутентификацию на базе Chrome внутри вашего приложения:

Ключевые особенности:

• Используют общие cookie и учетные данные с браузером Chrome.
• Показывают URL и индикаторы безопасности.
• Можно настроить цвет панели инструментов и брендинг.
• Предварительный прогрев для более быстрой загрузки.

Интеграция с OAuth: Chrome Custom Tabs являются эквивалентом ASWebAuthenticationSession на iOS, обеспечивая отличную поддержку OAuth при сохранении доступа к сохраненным ключам доступа.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

Embedded WebView предоставляют полный контроль над рендерингом веб-контента в вашем приложении, позволяя напрямую манипулировать cookie, сессиями и навигацией без URL-строки. Однако этот контроль сопряжен с дополнительными техническими требованиями для включения функциональности ключей доступа.

Когда выбирать Embedded WebView:

• Опыт, подобный нативному: Ваше приложение уже встраивает аутентификацию в кастомизированный веб-компонент для сохранения нативного вида, и вы хотите сохранить этот последовательный пользовательский опыт.
• Нужен контроль над сессией/cookie: Ваше приложение требует прямой манипуляции токенами аутентификации и состоянием сессии после завершения аутентификации OAuth.
• Существующий поток аутентификации, где System WebView возвращает код авторизации, но не сессию во встроенных контекстах.
• Необходимо поддерживать состояние аутентификации на нескольких встроенных веб-экранах.
• Только собственная аутентификация: Ваше приложение обрабатывает аутентификацию напрямую, для реализаций ключей доступа от третьих сторон см. здесь.
• AndroidX WebKit 1.12.1+ с определением функций во время выполнения.
• Приемлемо ограничение Conditional UI для входа (не поддерживается в Embedded WebView), что не актуально для настроек управления.

Важный контекст:

Многие приложения используют гибридный подход: System WebView обрабатывает начальную аутентификацию OAuth (где ключи доступа работают без проблем), а затем переключаются на Embedded WebView для пост-аутентификации, чтобы управлять ключами доступа в настройках. Проблемы возникают при попытке использовать ключи доступа напрямую в Embedded WebView.

Технические требования:

Embedded WebView требуют дополнительной настройки по сравнению с System WebView:

1. iOS: Права Associated Domains, конфигурация файла AASA.
2. Android: AndroidX WebKit 1.12.1+ с конфигурацией WebAuthn в WebView (требуется определение функций).
3. Обе платформы: Правильно настроенные файлы ассоциации well-known и Digital Asset Links.

Компоненты платформы:

• iOS: WKWebView
• Android: android.webkit.WebView

Компромиссы:

• Средняя сложность: Требует конфигурации WebView (Android WebKit 1.12.1+) и настройки прав (iOS).
• Более низкое принятие ключей доступа: Пользователи могут столкнуться с большим трением по сравнению с нативной реализацией.
• Conditional UI не поддерживается: Автозаполнение полей ввода ключами доступа не работает в Embedded WebView на Android.
• Ограниченная поддержка платформы: Некоторые функции могут работать нестабильно (например, автоматическое создание ключей доступа).

При реализации ключей доступа через WebView крайне важно понимать разницу между System WebView и Embedded WebView. Три подхода, описанные выше (Нативная реализация, System WebView и Embedded WebView), служат разным целям.

На iOS у вас есть несколько вариантов отображения веб-контента в приложении:

• WKWebView — это настраиваемый WebView, который является частью фреймворка WebKit (представлен в iOS 8). Он дает вам большой контроль над внешним видом и поведением веб-контента.
• SFSafariViewController — это контроллер представления от Apple, который действует как облегченный браузер Safari внутри вашего приложения. Он использует движок Safari. На iOS 11+ у него отдельное хранилище cookie, и он не делится cookie с Safari. Используйте ASWebAuthenticationSession, когда требуется общий доступ к сессии Safari.
• SFAuthenticationSession / ASWebAuthenticationSession — это специализированные сессии веб- аутентификации (доступны с iOS 11/12), предназначенные специально для OAuth/OpenID или других безопасных потоков входа. Они также используют Safari под капотом, но сосредоточены на потоках аутентификации и автоматически обрабатывают такие вещи, как общие cookie и Single Sign-On (SSO).

На Android основные варианты:

• Android WebView — это стандартный виджет WebView (android.webkit.WebView), который по сути является мини-браузером, который можно встроить в ваши activities. Он очень гибко настраивается, но работает в процессе вашего приложения.
• Chrome Custom Tabs (CCT) — это функция, которая открывает вкладку на базе Chrome в контексте вашего приложения. Custom Tabs выглядят как часть вашего приложения, но работают на движке браузера Chrome (если он установлен) с такими функциями, как предварительная загрузка, общие cookie и знакомая URL-строка для доверия пользователя.

В следующих разделах мы подробнее рассмотрим эти типы WebView для iOS и Android и обсудим, какой из них может быть наиболее подходящим для потоков аутентификации с ключами доступа.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Платформа Apple предоставляет три варианта WebView, перечисленные выше. Ваш выбор повлияет на то, насколько гладко можно будет использовать ключи доступа внутри приложения:

Для тестирования различного поведения WebView в iOS мы рекомендуем приложение WebView - WKWebView and UIWebView rendering.

WKWebView — это универсальный компонент WebView для iOS. Разработчики могут встроить WKWebView для рендеринга веб-контента с высокой степенью контроля над UI и поведением. WKWebView использует тот же движок рендеринга, что и Safari, поэтому он очень производителен и поддерживает современные веб- функции. Теоретически, WKWebView может обрабатывать WebAuthn (и, следовательно, ключи доступа), если настроен правильно, но учтите, что некоторые расширенные функции браузера могут быть ограничены из соображений безопасности. Одна вещь, на которую стоит обратить внимание, — это то, что WKWebView по умолчанию не делится cookie или данными связки ключей с мобильным Safari. Пользователям может потребоваться заново входить в систему, потому что их сессия в WebView изолирована от сессии Safari. Также, поскольку содержимое WKWebView может быть полностью настроено приложением, пользователь не видит адресной строки или UI Safari — что отлично для брендинга, но это означает, что у пользователя меньше подсказок для проверки подлинности страницы (что является проблемой для защиты от фишинга). Некоторые приложения даже злоупотребляли WKWebView для внедрения скриптов или изменения контента (например, было отмечено, что TikTok внедрял отслеживающий JS через свой встроенный браузер), поэтому нужно быть осторожным и использовать WKWebView безопасным, заслуживающим доверия образом.

SFSafariViewController предоставляет опыт использования Safari внутри приложения. Когда вы открываете URL с помощью SFSafariViewController, это почти как открыть его в настоящем браузере Safari, за исключением того, что пользователь остается в UI вашего приложения. Преимущество для ключей доступа значительно: поскольку это, по сути, Safari, пользователю доступны его iCloud Keychain и сохраненные ключи доступа. Обратите внимание, что на iOS 11+ cookie не являются общими. Это означает, что если у пользователя уже есть ключ доступа для вашего сайта, Safari сможет его найти и даже отобразить автозаполнение Conditional UI для легкого входа. SFSafariViewController менее настраиваемый (вы не можете сильно изменить его панель инструментов), но он автоматически обрабатывает множество функций безопасности и конфиденциальности. Отображается URL-строка с иконкой замка для HTTPS, что дает пользователям уверенность в том, что они находятся на правильном домене. В целом, SFSafariViewController считается более безопасным, чем "сырой" WKWebView, и его проще реализовать (Apple предоставляет его как готовый компонент). Основной компромисс — вы жертвуете некоторым контролем над внешним видом. Для потока аутентификации это обычно приемлемо. Приоритетом здесь является безопасность и простота входа, в чем SFSafariViewController преуспевает, используя контекст Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Эти классы (последний — более новое, дружественное к Swift название) созданы специально для потоков входа, таких как OAuth или OpenID Connect. Когда вам нужно аутентифицировать пользователя через веб-страницу (возможно, у внешнего IdP), эти сессии являются рекомендуемым выбором на iOS. Они очень похожи на SFSafariViewController в том, что используют браузер Safari под капотом и делятся cookie/хранилищем с Safari. Ключевое отличие в том, что SFAuthenticationSession всегда будет запрашивать у пользователя, что приложение хочет аутентифицироваться с помощью веб-страницы (для осведомленности пользователя), и он автоматически будет использовать существующую сессию Safari пользователя, если она доступна.

Преимущество заключается в бесшовном опыте SSO – если пользователь уже вошел в систему у провайдера в Safari, эта сессия может использовать этот cookie, чтобы избежать еще одного входа. Для ключей доступа это важно, потому что это означает, что любой ключ доступа, хранящийся в Safari/iCloud Keychain, также может быть использован здесь. Официальное руководство Apple — использовать ASWebAuthenticationSession для всего, что похоже на поток входа. Плюсы — повышенная конфиденциальность (ваше приложение никогда не видит учетные данные или cookie, Safari обрабатывает это) и встроенная поддержка SSO. Минус в том, что он ограничен потоками аутентификации (вы бы не использовали его просто для рендеринга произвольного веб-контента в вашем приложении). В общем, если вы выбираете подход с WebView на iOS, ASWebAuthenticationSession обычно является лучшим выбором для реализации ключей доступа, потому что он безопасен, делится состоянием с Safari и специально создан для аутентификации.

Want to find out how many people use passkeys?

View Adoption Data

На Android выбор WebView сводится к классическому WebView и Chrome Custom Tabs:

Для тестирования различного поведения WebView в Android мы рекомендуем приложение WebView vs Chrome Custom Tabs.

Android WebView (android.webkit.WebView) — это компонент, который позволяет встраивать веб-страницы в макет вашего activity. Он похож на WKWebView в том, что дает вам полный контроль: вы можете перехватывать навигацию, внедрять JavaScript, настраивать UI и т.д. Он также работает в процессе вашего приложения. Использование WebView для ключей доступа означает, что ваше приложение загружает вашу веб-страницу входа, и эта страница может инициировать церемонию WebAuthn с ключом доступа. Современный Android WebView поддерживает WebAuthn (при условии, что реализация WebView на устройстве обновлена через Android System WebView или компонент Chrome). Важное соображение: по умолчанию Android WebView не делится cookie или сохраненными учетными данными с браузером Chrome пользователя. Таким образом, любой ключ доступа, созданный или использованный в WebView, может быть неизвестен Chrome, и наоборот. Эта изоляция может быть хороша для безопасности (ваше приложение не может читать cookie браузера), но она может заставить пользователей снова входить в систему, если они уже аутентифицировались в Chrome. Другая проблема — доверие. Обычный WebView не показывает URL или иконку замка SSL, поэтому пользователям приходится полностью доверять вашему приложению, что оно их не обманет. Google даже запретил использование WebView для входа в Google через OAuth из-за потенциальных рисков фишинга. С точки зрения производительности, WebViews в порядке, но они могут быть медленнее или более ресурсоемкими, чем использование браузера пользователя по умолчанию, особенно при загрузке тяжелых страниц.

Chrome Custom Tabs (CCT) — это гибридный подход. Они позволяют вашему приложению открывать страницу, отрендеренную Chrome, которая выглядит как часть вашего приложения. Вы можете настроить цвет панели инструментов, добавить логотип приложения и т.д., но контент рендерится Chrome в отдельном процессе. Для ключей доступа у CCT есть несколько преимуществ: они делятся cookie и учетными данными пользователя с Chrome, что означает, что если у пользователя есть ключ доступа, сохраненный через Chrome (Google Password Manager), Custom Tab может получить к нему доступ. Пользователь также увидит фактический URL и индикаторы безопасности, что укрепляет доверие. Производительность часто лучше — Chrome можно "прогреть" в фоновом режиме для более быстрой загрузки. И что важно, безопасность на высоком уровне: поскольку это, по сути, приложение Chrome, такие вещи, как Google Safe Browsing, защищают сессию, и ваше приложение не может внедрять произвольные скрипты на страницу (предотвращая определенные атаки).

Недостатком является то, что это требует, чтобы у пользователя был установлен и обновлен Chrome (или поддерживаемый браузер). У большинства пользователей Android он есть, но на некоторых устройствах в определенных регионах это может быть проблемой. В целом, если вы выбираете подход с встроенным вебом на Android, Chrome Custom Tabs рекомендуются для потоков с ключами доступа, так как они обеспечивают хороший баланс интеграции и безопасности. Фактически, они во многом аналогичны SFSafariViewController/ASWebAuthSession на iOS — использование браузера по умолчанию для аутентификации.

(Кстати: WKWebView vs SFSafariViewController от Apple и WebView vs CCT от Android имеют много параллелей. И Safari VC, и Chrome Tabs делятся состоянием браузера и обеспечивают лучшую безопасность, в то время как WKWebView/Android WebView дают больше контроля, но изолируют веб-контент. Для ключей доступа обмен состоянием (cookie, хранилища учетных данных) обычно желателен, чтобы к ключу доступа можно было беспрепятственно получить доступ и создать его.)

Независимо от того, какой подход к реализации вы выберете, для включения функциональности ключей доступа должны быть выполнены определенные технические требования. В этом разделе представлено исчерпывающее руководство по настройке файлов ассоциации well-known, прав iOS и конфигурации Android WebView.

Примечание об управляемых устройствах: Поведение ключей доступа значительно меняется на управляемых устройствах, где политики Mobile Device Management (MDM) контролируют хранение учетных данных. Для тестирования ключей доступа на управляемых устройствах см. Passkeys на управляемых устройствах iOS и Android.

Нативные и Embedded WebView потоки требуют файлы ассоциации для установления криптографического доверия между вашим приложением и веб-доменом. System WebView (ASWebAuthenticationSession) и Chrome Custom Tabs не требуют ассоциации приложения с сайтом.

Файл AASA устанавливает связь между вашим приложением iOS и вашим веб-доменом, позволяя ключам доступа работать на обеих платформах.

Расположение файла: https://yourdomain.com/.well-known/apple-app-site-association

Требования к конфигурации:

• Разместите по адресу /.well-known/apple-app-site-association на вашем домене
• Сервируйте через HTTPS с действительным SSL-сертификатом
• Content-Type: application/json
• Никаких перенаправлений на пути .well-known
• Включите Team ID и Bundle ID вашего приложения

Пример файла AASA:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

Кэширование и тестирование AASA:

Apple агрессивно кэширует файлы AASA (до 24-48 часов) с помощью CDN, что может затруднить разработку и тестирование. Чтобы обойти кэширование во время разработки:

1. Включите режим разработчика на вашем тестовом устройстве
2. Добавьте ?mode=developer к вашему ассоциированному домену в Xcode
3. Это заставит iOS загрузить последнюю версию файла AASA напрямую с вашего сервера

⚠️ Важно: НЕ используйте ?mode=developer в производственных релизах. Этот параметр предназначен только для разработки — его использование в продакшене помешает iOS правильно обнаружить ваш файл AASA, что нарушит функциональность ключей доступа.

Валидация: Используйте Валидатор AASA от Apple для проверки вашей конфигурации.

Android использует Digital Asset Links для проверки связи между вашим приложением и веб-сайтом.

Расположение файла: https://yourdomain.com/.well-known/assetlinks.json

Требования к конфигурации:

• Разместите по адресу /.well-known/assetlinks.json на вашем домене
• Сервируйте через HTTPS с действительным сертификатом
• Content-Type: application/json
• Включите отпечаток SHA256 вашего приложения (из сертификата подписи)

Пример файла assetlinks.json:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

Валидация: Используйте Генератор Digital Asset Links от Google для создания и проверки вашей конфигурации.

Приложениям iOS требуются соответствующие права для доступа к функциональности ключей доступа. Требования немного различаются в зависимости от вашего подхода к реализации.

Файл прав (часто называемый Runner.entitlements в приложениях на Flutter или YourApp.entitlements в нативных проектах iOS) определяет специальные разрешения и возможности, предоставляемые системой Apple. Для ключей доступа этот файл настраивает Associated Domains.

Расположение файла: Обычно в вашем проекте Xcode по адресу ios/Runner/Runner.entitlements

Нативная реализация и Embedded WebView требуют возможности Associated Domains для связывания вашего приложения с вашим веб-доменом. System WebView (ASWebAuthenticationSession) не требует этого, так как работает в контексте Safari.

Настройка в Xcode:

1. Откройте ваш проект в Xcode
2. Выберите вашу цель приложения
3. Перейдите на вкладку "Signing & Capabilities"
4. Нажмите "+ Capability" и добавьте "Associated Domains"
5. Добавьте ваш домен с префиксом webcredentials:

Пример конфигурации:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

Несколько доменов: Если вашему приложению нужно работать с несколькими доменами, вам могут понадобиться Related Origin Requests (ROR).

Android Embedded WebView получили нативную поддержку WebAuthn с AndroidX WebKit 1.12, что устранило необходимость в пользовательском коде JavaScript-моста. System WebView (Chrome Custom Tabs) не требует никакой конфигурации — учетные данные работают автоматически.

Требования:

• AndroidX WebKit 1.12.1 или новее (рекомендуется 1.14.0+)
• Настроены Digital Asset Links
• APK WebView с поддержкой WebAuthn (проверьте через определение функций)
• Примечание: библиотека AndroidX Credentials НЕ требуется для WebAuthn в WebView, только для полностью нативных реализаций

Реализация:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Проверка поддержки веб-аутентификации
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Включение веб-аутентификации
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Включение JavaScript
    webView.settings.javaScriptEnabled = true
}

Ключевые моменты:

• JavaScript-мост не нужен: WebAuthn работает нативно в WebView
• Требуется определение функций: Всегда проверяйте WebViewFeature.WEB_AUTHENTICATION во время выполнения
• Conditional UI не поддерживается: mediation:"conditional" (автозаполнение полей ввода ключами доступа) не работает в Embedded WebView
• Резервная стратегия: Если функция недоступна, используйте вместо этого Chrome Custom Tabs

Примечания к версиям:

• Используйте WebKit 1.12.1 или новее (в 1.12.0 была проблема с доступностью во время выполнения)
• Поддержка функции зависит от версии APK WebView пользователя — старые APK на устройстве не предоставят эту функцию

До AndroidX WebKit 1.12.0 нативной поддержки WebAuthn в Embedded WebView не существовало. Командам приходилось либо:

1. Использовать Chrome Custom Tabs или Auth Tab (рекомендуется)
2. Создавать собственный JavaScript-мост

Если вам нужно поддерживать старые версии Android или устройства без обновленных APK WebView, см. руководство по интеграции Credential Manager с WebView от Android для подхода с кодом моста. Однако, мы настоятельно рекомендуем использовать нативный подход с WebKit 1.12.1+ для современных приложений.

Рекомендация: Используйте нативную поддержку WebAuthn с AndroidX WebKit 1.12.1+. Если она недоступна во время выполнения, переключайтесь на Chrome Custom Tabs, которые обеспечивают отличную поддержку ключей доступа с общими учетными данными.

При реализации ключей доступа в нативных приложениях вам необходимо установить доверие между вашим приложением и веб-доменом(ами). В этом разделе рассматривается, как обрабатывать одиночные домены, несколько связанных доменов (ROR) и как проверять правильность настройки ваших файлов ассоциации well-known.

Для приложений, использующих один домен (например, kayak.com), вам понадобятся:

• Один файл AASA для iOS по адресу https://kayak.com/.well-known/apple-app-site-association
• Один файл assetlinks.json для Android по адресу https://kayak.com/.well-known/assetlinks.json
• Право Associated Domains, настроенное с webcredentials:kayak.com

Related Origins (ROR) — это функция WebAuthn, которая позволяет одному набору ключей доступа работать на нескольких связанных доменах (например, kayak.com, kayak.de, kayak.co.uk). ROR использует эндпоинт /.well-known/webauthn на каждом сайте для определения связанных источников, а НЕ файлы AASA или assetlinks.

Ключевые моменты:

• Конфигурация ROR: Каждый домен размещает /.well-known/webauthn со списком связанных источников
• Файлы ассоциации приложения (AASA/assetlinks): Используются только для сопоставления приложений с их соответствующими веб-сайтами
• iOS 18+ Embedded WebView: Поддерживает ROR при правильной настройке
• Права Associated Domains: Включите все домены, с которыми ваше приложение должно аутентифицироваться

Пример конфигурации:

Если ваше приложение работает с kayak.com и kayak.de, оба домена должны:

• Размещать свои соответствующие файлы AASA с одинаковыми Team ID и Bundle ID
• Быть перечислены в правах Associated Domains вашего приложения
• Иметь правильно настроенные и доступные файлы well-known

Перед запуском проверьте, что ваши файлы well-known правильно настроены и доступны. Apple и Google предоставляют тестовые URL на базе CDN для проверки доступности файлов:

Использование этих тестовых URL:

• Нажмите на ссылки, чтобы проверить, могут ли Apple/Google получить ваши файлы well-known
• Параметр Apple ?nocache=1 принудительно загружает свежую версию, обходя кэш CDN
• Если файлы недоступны по этим URL, функциональность ключей доступа в вашем приложении работать не будет
• Замените kayak.com или kayak.de на ваши собственные домены в приведенных выше шаблонах URL

Подводный камень при тестировании: Убедитесь, что все домены имеют правильно настроенные файлы well-known. Отсутствующий или неправильно настроенный файл на любом домене может нарушить функциональность ключей доступа для этого домена.

Дополнительная информация: WebAuthn Relying Party ID в нативных приложениях

Выбор правильного подхода к реализации зависит от архитектуры аутентификации вашего приложения, требований к OAuth и необходимости контроля сессии. Используйте это дерево решений, чтобы определить лучший путь вперед.

Начните с этих ключевых вопросов:

1. Использует ли ваше приложение аутентификацию на основе OAuth (OAuth2, OIDC, провайдеры входа через соцсети)?

   • Да → System WebView (Раздел 1.2)
     • iOS: Используйте ASWebAuthenticationSession
     • Android: Используйте Chrome Custom Tabs
     • Отличная поддержка OAuth с общими учетными данными

2. Хотите ли вы повторно использовать веб-аутентификацию в нативной оболочке (без URL-строки, полный контроль над UI)?

   • Да → Embedded WebView (Раздел 1.3) с конфигурацией
     • iOS: WKWebView + права Associated Domains
     • Android: WebView + конфигурация AndroidX WebKit 1.12.1+
     • Обеспечивает нативный внешний вид при повторном использовании веб-компонентов
     • Примечание: Conditional UI не поддерживается в Embedded WebView
   • Нет → Рассмотрите System WebView или Нативную реализацию

3. Создаете ли вы новое нативное приложение или у вас есть нативные экраны входа?

   • Да → Нативная реализация (Раздел 1.1)
     • Лучший пользовательский опыт
     • Мгновенная, бесшумная аутентификация
     • Требует разработки под конкретную платформу

4. У вас есть существующая веб-аутентификация, которую вы хотите повторно использовать?

   • Да → System WebView для быстрой реализации
   • Нет → Нативная реализация для оптимального UX

Вот как каждый подход показывает себя по ключевым аспектам:

Объяснение аспектов:

• Создание Passkeys: Насколько легко пользователи могут создавать ключи доступа с помощью этого подхода
• Использование Passkeys: Опыт аутентификации при использовании существующих ключей доступа
• Управление Passkeys: Как пользователи просматривают, редактируют или удаляют ключи доступа
• Техническая сложность: Усилия по разработке и текущее обслуживание
• Поддержка OAuth: Насколько хорошо подход справляется с потоками аутентификации OAuth2/OIDC
• Время настройки: Типичные сроки реализации

Рекомендация: System WebView

Если ваше приложение аутентифицируется через OAuth2, OIDC или провайдеров входа через соцсети (Google, GitHub, Microsoft и т.д.), System WebView является оптимальным выбором:

• iOS: ASWebAuthenticationSession специально создан для потоков OAuth
• Android: Chrome Custom Tabs обеспечивают бесшовную интеграцию с OAuth
• Преимущества: Минимальный нативный код, автоматическое использование общих учетных данных
• Реализация: Добавьте WebAuthn на вашу страницу веб-аутентификации, затем загрузите ее через System WebView

Пример: Приложения для путешествий, такие как kayak.com и kayak.de используют OAuth для аутентификации. System WebView позволяет им поддерживать существующую инфраструктуру OAuth, добавляя поддержку ключей доступа через свои страницы веб-аутентификации.

Рекомендация: Гибридный подход

Используйте System WebView для начальной аутентификации OAuth, затем Embedded WebView для пост-аутентификационных сессий:

1. Начальная аутентификация: System WebView обрабатывает OAuth + вход по ключу доступа
2. Управление сессией: Переключитесь на Embedded WebView для аутентифицированного веб-контента, где вам нужен контроль cookie/сессии
3. Техническая настройка: Настройте требования как для System, так и для Embedded WebView — для Android убедитесь, что включен AndroidX WebKit 1.12.1+ (см. Раздел 5)

Когда использовать: Приложения, которые аутентифицируются через OAuth, но затем должны отображать аутентифицированный веб-контент, где требуется прямая манипуляция сессией.

Рекомендация: Нативная реализация

Создаете с нуля или у вас есть нативные экраны? Выбирайте полностью нативный подход:

• iOS: Используйте фреймворк AuthenticationServices
• Android: Используйте Credential Manager API
• Преимущества: Лучший UX, мгновенная аутентификация, полный контроль
• Уникальное преимущество: Используйте preferImmediatelyAvailableCredentials для отображения автоматического оверлея с ключами доступа при запуске приложения — эксклюзивно для нативных реализаций и обеспечивает самые высокие коэффициенты конверсии
• Рекомендация по SDK: Используйте SDK от Corbado (iOS, Android) для ускорения разработки с проверенной в продакшене обработкой крайних случаев

Для новых приложений: Настоятельно рекомендуем создавать нативный вход с первого дня. Это обеспечит оптимальный UX и позволит избежать будущих миграций с WebView на нативную реализацию.

Рекомендация: Поэтапная миграция

• Этап 1: Passkeys в System WebView - Добавьте поддержку ключей доступа к существующему веб-входу, загрузите через System WebView (ASWebAuthenticationSession/Chrome Custom Tabs). Быстрая победа с минимальным нативным кодом.
• Этап 2: Нативный перехват - Добавьте нативную проверку ключей доступа перед показом WebView. Пример: kayak.com сначала пытается выполнить нативную аутентификацию по ключу доступа, при необходимости переключаясь на WebView. Обеспечивает быстрый биометрический вход, сохраняя обратную совместимость.
• Этап 3: Полностью нативная реализация - Постепенно переходите на нативную аутентификацию для пользователей с ключами доступа, сохраняя WebView для устаревших методов.

Этот поэтапный подход позволяет постепенно вносить улучшения, не нарушая работу существующих пользователей.

Подробные инструкции по настройке см. в Разделе 5.

Тестирование ключей доступа в нативных приложениях требует структурированного, многоуровневого подхода. Следуйте пирамиде тестирования: модульные тесты (изолированная логика), интеграционные тесты (церемония WebAuthn на симуляторах/эмуляторах) и системные тесты (сквозные на физических устройствах).

Основные категории тестов:

• Основные сценарии: Регистрация, аутентификация, кросс-девайсные потоки, удаление ключа доступа
• Покрытие платформ: iOS (нативная), Android (нативная), веб-браузеры на разных версиях ОС
• Ассоциация доменов: Проверка доступности файлов AASA (iOS) и Digital Asset Links (Android)
• Сценарии отмены: Тестирование отмены пользователем на системных запросах и экранах биометрии
• Обработка ошибок: Сбои бэкенда, таймауты сети, несоответствие учетных данных
• Крайние случаи: Отключенная блокировка экрана, отключенные iCloud/Google Password Manager
• Потоки OAuth: Полная сквозная интеграция OAuth + passkey
• Управляемые устройства: Среды, контролируемые MDM (см. тестирование на управляемых устройствах)
• Сторонние менеджеры: Совместимость с 1Password, Bitwarden, Dashlane
• Кросс-девайсная аутентификация: Потоки с QR-кодом и тестирование гибридного транспорта
• Специфика Embedded WebView: Если используется Embedded WebView, проверьте конфигурацию WebKit 1.12.1+ на Android
• Мониторинг в продакшене: Панель для отслеживания показателей успеха, сбоев и задержек

Для получения исчерпывающего руководства по тестированию, включая стратегии автоматизации, специфичные для платформ подводные камни и полный предстартовый чек-лист, см. наше специальное руководство: Тестирование потоков Passkey в нативных приложениях iOS и Android.

Рассмотрите возможность предлагать пользователям создать ключ доступа после успешного традиционного входа (пароль, OAuth). Такой подход постепенного перехода:

• Не нарушает существующие потоки аутентификации
• Позволяет плавно вернуться к прежнему состоянию, если пользователь отказывается
• Увеличивает внедрение ключей доступа со временем, не навязывая изменений
• Хорошо работает со всеми тремя подходами к реализации

Пример: После входа через OAuth с помощью System WebView покажите нативный запрос: "Включить более быстрый вход с помощью Face ID?" Если пользователь соглашается, создайте ключ доступа через веб-страницу, загруженную в System WebView.

Решение о том, как реализовать ключи доступа — через нативную реализацию, System WebView или Embedded WebView — является ключевым выбором дизайна, который влияет на безопасность, пользовательский опыт и сложность разработки. Универсального ответа не существует.

Для приложений на основе OAuth: System WebView (ASWebAuthenticationSession, Chrome Custom Tabs) является рекомендуемой отправной точкой. Он обеспечивает отличную поддержку OAuth, минимальные усилия по реализации и автоматическое совместное использование учетных данных.

Для приложений native-first: Переходите на нативную реализацию как можно скорее. Нативный вход с ключом доступа предлагает самый бесшовный UX с эксклюзивными возможностями, такими как preferImmediatelyAvailableCredentials, который включает автоматический оверлей с ключами доступа при запуске приложения — то, чего не могут предоставить реализации с WebView. С первоклассной поддержкой ключей доступа в iOS и Android, реальные успехи демонстрируют высокое внедрение. Инструментарий (включая SDK с открытым исходным кодом и библиотеки платформ) созрел, чтобы сделать нативную интеграцию достижимой в разумные сроки. Хотя вы должны помнить о политиках управления устройствами, межплатформенной синхронизации и сторонних провайдерах, эти проблемы можно решить с помощью тщательной инженерии и тестирования. Результатом является вход в приложение, который радует пользователей своей простотой и скоростью, значительно повышая безопасность.

Для требований к встроенному фрейму WebView: Embedded WebView обычно используется в двух реальных сценариях. Во-первых, приложения на основе OAuth часто используют System WebView для начального потока входа, а затем переключаются на Embedded WebView для отображения опций управления ключами доступа на экранах настроек, где требуется контроль сессии, хотя некоторые приложения упрощают это, используя System WebView для обоих потоков. Во-вторых, приложения, которые уже встроили свой поток аутентификации во фреймы WebView до принятия ключей доступа, продолжают этот паттерн для согласованности. Embedded WebView с нативной поддержкой WebAuthn (AndroidX WebKit 1.12.1+) требует конфигурации и настройки (разрешения, права, настройки WebView), но больше не нуждается в пользовательском коде JavaScript-моста. Обратите внимание, что Conditional UI не поддерживается в Embedded WebView. Выбирайте этот подход, когда поддерживаете существующие встроенные паттерны аутентификации или когда вам нужен контроль сессии/cookie для экранов после аутентификации.

В конечном итоге, ключи доступа в нативных приложениях представляют собой огромный скачок вперед как в удобстве для пользователя, так и в безопасности. Независимо от того, реализованы ли они через нативную реализацию, System WebView или Embedded WebView, они устраняют риски фишинга и бремя управления паролями для ваших пользователей. Реальные внедрения, такие как интеграция ключей доступа в нативное приложение VicRoads, демонстрируют, что подходы native-first обеспечивают самое высокое внедрение и удовлетворенность пользователей при правильном выполнении с такими функциями, как автоматические оверлеи с ключами доступа. Следуя лучшим практикам для удобной аутентификации и выбирая подход к реализации, который соответствует архитектуре вашего приложения — native-first для новых приложений, System WebView для потоков OAuth или Embedded WebView для существующих встроенных паттернов — вы можете предложить беспарольный, биометрический вход, который действительно реализует видение ключей доступа: простая, безопасная и приятная аутентификация для всех.

Если ключи доступа не работают в вашем нативном приложении, проверьте эти распространенные проблемы в зависимости от подхода к реализации:

• Файлы обслуживаются по HTTPS с действительным сертификатом
• Правильный MIME-тип: application/json
• Нет перенаправлений на пути .well-known
• iOS: Team ID и Bundle ID в файле AASA точно совпадают
• Android: Отпечаток SHA256 в assetlinks.json совпадает с вашим сертификатом подписи
• Relying Party ID совпадает с вашим доменом (без протокола, без порта)
• Нет завершающих слэшей в RP ID
• Origin WebAuthn: https://your-domain.com (а не app://)

• iOS: В Xcode включена возможность Associated Domains с webcredentials:yourdomain.com
• Android: Digital Asset Links объявлены в AndroidManifest.xml
• У пользователя включена блокировка экрана (биометрия или PIN-код)
• Протестируйте с помощью Валидатора AASA от Apple и инструмента Digital Asset Links от Google
• Убедитесь, что файл Runner.entitlements содержит правильные ассоциированные домены

• iOS: Используется ASWebAuthenticationSession (рекомендуется) или SFSafariViewController
• Android: Используются Chrome Custom Tabs (а не обычный WebView)
• iOS: Убедитесь, что при необходимости настроены Associated Domains
• Проверьте, что cookie/учетные данные являются общими с системным браузером
• Убедитесь, что на странице веб-аутентификации правильно реализован WebAuthn

• iOS: Настроен с правильными правами (entitlements)
• iOS: Associated Domains включают все соответствующие домены
• iOS: Файл AASA доступен и правильно отформатирован
• iOS: Тестируйте с ?mode=developer во время разработки (удалите для продакшена)
• Android: В проект включен AndroidX WebKit 1.12.1+ (или новее)
• Android: Проверка функции во время выполнения для WebViewFeature.WEB_AUTHENTICATION
• Android: setWebAuthenticationSupport() вызван с WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: В настройках WebView включен JavaScript
• Android: Версия APK WebView пользователя поддерживает функцию WebAuthn (используйте определение функции, а не версию ОС)
• Conditional UI не используется (не поддерживается в Embedded WebView)
• Резервное переключение на Chrome Custom Tabs, если функция WebAuthn недоступна

• Проверьте, активен ли у пользователя нестандартный провайдер учетных данных (1Password, Bitwarden и т.д.)
• Убедитесь, что провайдер поддерживает ключи доступа (не все менеджеры паролей это делают)
• Протестируйте с нативным менеджером учетных данных платформы (iCloud Keychain, Google Password Manager)

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• Обычно означает: Отсутствие прав (entitlements) (iOS) или недоступность/не включенность функции WebView (Android Embedded WebView)
• Проверьте: Конфигурацию Associated Domains, доступность файла AASA, версию WebKit, определение функции, вызов setWebAuthenticationSupport()

Не появляется запрос на использование ключа доступа

• Может означать: Не загружается AASA/assetlinks.json, неправильный тип WebView, кэшированный файл AASA
• Попробуйте: Проверить файлы ассоциации, использовать ?mode=developer на iOS для тестирования, проверить тип WebView

Для детальной отладки см. нашу статью о Relying Party ID в нативных приложениях.

Нативные SDK от Corbado:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Пакет для Flutter

Документация платформ:

• Apple: Поддержка ключей доступа
• Google: Credential Manager

Инструменты для валидации:

• Валидатор AASA от Apple
• Генератор Digital Asset Links от Google