Узнайте из нашего руководства, как создавать Passkeys и входить в систему с их помощью в междоменных iframe. Мы расскажем об iframe в WebAuthn, политиках безопасности и практической реализации.
Vincent
Created: July 15, 2025
Updated: July 16, 2025
See the original blog version in English here.
Our mission is to make the Internet a safer place, and the new login standard passkeys provides a superior solution to achieve that. That's why we want to help you understand passkeys and its characteristics better.
Браузер | Междоменный вход ( navigator.credentials.get ) | Междоменное создание ( navigator.credentials.create ) |
---|---|---|
Chrome/Edge | ✅ Chrome 84 (июль 2020 г.) | ✅ Chrome 123 (март 2024 г.) |
Firefox | ✅ Firefox 118 (сентябрь 2023 г.) | ✅ Firefox 123 (февраль 2024 г.) |
Safari | ✅ Safari 15.5 (май 2022 г.) | ❌ Не поддерживается |
Условные обозначения
✅ = поддерживается ❌ = не поддерживается
Неделя за неделей все больше организаций объявляют о внедрении Passkeys (например, недавно это сделали Visa, Mastercard или Vercel). По мере того как разработчики и менеджеры продуктов из других компаний следуют этим примерам, обсуждается все больше сценариев применения Passkeys.
Один из вопросов, который нам постоянно задают, — это как Passkeys работают в iframe, поскольку iframe широко используются в современной веб-разработке для бесшовного встраивания контента из разных источников. В контексте Passkeys и WebAuthn использование iframe сопряжено с рядом проблем, особенно в части безопасности и взаимодействия с пользователем.
Эта статья представляет собой исчерпывающее руководство по использованию Passkeys и WebAuthn в iframe. Мы:
Прочитав эту статью, вы получите четкое представление о том, как эффективно использовать Passkeys внутри iframe.
Recent Articles
♟️
Mastercard Identity Check: все, что нужно знать эмитентам и мерчантам
♟️
Ключи доступа для платежных провайдеров: как создать сторонний SDK
♟️
Сервер контроля доступа EMV 3DS: Passkeys, FIDO и SPC
♟️
Динамическое связывание с Passkeys: Secure Payment Confirmation (SPC)
♟️
Ландшафт платежных Passkeys: 4 основные модели интеграции
iframe, или встроенные фреймы, — это HTML-элементы, которые позволяют разработчикам встраивать один HTML-документ внутрь другого. Эта возможность широко используется для включения контента из внешних источников, таких как видео, карты и другие веб-страницы, на сайт.
Давайте рассмотрим различные типы iframe.
Базовый iframe — это наиболее распространенный тип. Он просто встраивает контент с другого URL-адреса на текущую страницу.
<iframe src="https://example.com"></iframe>
Такой iframe часто используется для включения статического контента, например статьи, на веб-страницу.
Адаптивные iframe спроектированы так, чтобы их размер подстраивался под размер экрана или контейнера, в котором они находятся. Это гарантирует, что встроенный контент будет хорошо выглядеть на всех устройствах, включая настольные компьютеры, планшеты и мобильные телефоны.
<iframe src="https://example.com" style="width: 100%; height: 500px;"></iframe>
Также можно использовать медиазапросы CSS, чтобы iframe динамически подстраивался под размер области просмотра.
Безопасный iframe, или iframe в «песочнице» (sandboxed iframe), ограничивает действия, которые можно выполнять внутри него. Это полезно для встраивания контента из ненадежных источников или для повышения безопасности.
<iframe src="https://example.com" sandbox></iframe>
Атрибут sandbox может включать различные ограничения, например:
<iframe src="https://example.com" sandbox="allow-scripts allow-same-origin"></iframe>
Атрибут sandbox позволяет запускать скрипты, но ограничивает потенциально опасные действия, такие как отправка форм или использование плагинов.
Междоменные iframe (cross-origin iframe) встраивают контент с другого домена. Они часто используются для интеграции сторонних сервисов, таких как платежные шлюзы или виджеты социальных сетей. Из-за ограничений безопасности такие iframe имеют ограниченный доступ к содержимому встраивающей страницы, и наоборот.
Междоменный (cross-origin) означает, что загружаемый контент поступает из другого
источника (origin), где источник определяется комбинацией схемы (протокола), хоста
(домена) и номера порта. Например, https://example.com
и http://example.com
считаются
разными источниками, потому что они используют разные схемы (HTTP и HTTPS).
Аналогично, поддомены рассматриваются как отдельные источники по отношению к их
родительским доменам. Например, https://example.com
и https://sub.example.com
являются
междоменными, хотя у них общий базовый домен. Такое разделение гарантирует, что скрипты и
данные с одного поддомена не могут напрямую взаимодействовать с данными другого без явного
разрешения, что повышает безопасность.
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.
Крупные компании доверяют Corbado защиту своих пользователей и создание более удобного входа с помощью Passkeys. Получите бесплатную консультацию по Passkeys прямо сейчас.
Получить бесплатную консультациюВот примеры, иллюстрирующие концепции междоменного и однодоменного происхождения:
Пример междоменного (cross-origin) iframe:
Встраивание контента с https://payment.example.com на веб-страницу, размещенную на https://www.mystore.com. Они являются междоменными, так как у них разные домены.
Пример однодоменного (same-origin) iframe:
Встраивание контента с https://www.example.com/shop на веб-страницу, размещенную на https://www.example.com/blog. Они являются однодоменными, так как у них одинаковые схема, хост и порт.
Междоменные iframe отличаются от базовых тем, что их источник находится на другом домене, в то время как у односайтового iframe источник находится на том же домене, куда он встроен.
<iframe src="https://anotherdomain.com"></iframe>
Использование Passkeys в iframe открывает новые возможности и накладывает ограничения, которые разработчикам необходимо понимать. В основном это касается установки правильных разрешений и обеспечения безопасного взаимодействия пользователя во встроенном контексте.
Исторически Web Authentication API был по умолчанию отключен в междоменных iframe, в первую очередь из соображений безопасности. Это ограничение означало, что разработчикам приходилось перенаправлять пользователей или использовать всплывающие окна для аутентификации, что ухудшало пользовательский опыт.
В Passkeys / WebAuthn есть две основные операции (также называемые церемониями):
Эти две операции поддерживались и поддерживаются в междоменных iframe по-разному:
Сначала стала возможной аутентификация через междоменные iframe, но создание ключа в таком контексте еще не было доступно, потому что не было никого с подходящим сценарием использования.
Недавние улучшения (например, в Chrome 123) добавили поддержку создания Passkeys в междоменных iframe при определенных условиях. Однако на май 2024 года не все браузеры полностью поддерживают создание Passkeys через междоменные iframe, хотя вход возможен в большинстве из них.
Более того, поддержка междоменных iframe (для операций регистрации и аутентификации) уже включена в разрабатываемую спецификацию WebAuthn Level 3. Некоторым браузерам (например, Safari) еще предстоит догнать спецификацию. К сожалению, Apple пока не объявила, разрешит ли и когда разрешит междоменную регистрацию Passkeys в Safari. Это сняло бы самое значительное техническое ограничение на использование Passkeys в междоменных iframe.
В следующих частях статьи мы будем исходить из того, что используются междоменные iframe.
Следующие таблицы дают обзор поддержки браузерами/стандартами аутентификации в iframe и входа с помощью Passkeys в контексте междоменных iframe:
Браузер/Стандарт | Контекст основного домена (First-Party) | Контекст стороннего домена (Third-Party) |
---|---|---|
Требуется в WebAuthn Level 2 | ✔️ | ✔️ |
Требуется в WebAuthn Level 3 | ✔️ | ✔️ |
Реализовано в Chrome | ✔️ | ✔️ |
Реализовано в Firefox | ✔️ | ✔️ |
Реализовано в Safari | ✔️ | ✔️ |
На май 2024 года создание Passkey в междоменном iframe возможно еще не во всех браузерах. Следующая таблица дает обзор поддержки браузерами/стандартами регистрации/создания Passkeys в междоменных iframe:
Браузер/Стандарт | Контекст основного домена (First-Party) | Контекст стороннего домена (Third-Party) |
---|---|---|
Требуется в WebAuthn Level 2 | ✔️ Подробнее | ❌ |
Требуется в WebAuthn Level 3 | ✔️ Подробнее | ✔️ Подробнее |
Реализовано в Chrome | ✔️ Подробнее | ✔️ Подробнее |
Реализовано в Firefox | ✔️ Подробнее | ✔️ Подробнее |
Реализовано в Safari | ✔️ Подробнее | Ожидается решение о реализации |
Если вас интересует более подробная информация об этой разработке и поддержке, рекомендуем ознакомиться с этим issue на GitHub и этим Pull Request.
Существует два основных сценария использования Passkeys в междоменных iframe.
Включение Passkeys в междоменных iframe имеет решающее значение для сценариев федеративной идентификации, где задействовано несколько доменов, но должны использоваться одни и те же учетные записи пользователей.
Рассмотрим следующий сценарий. Вы — международная компания, как KAYAK, и у вас есть разные домены для разных регионов:
Однако у вас есть одна центральная система управления идентификацией, которая позволяет пользователям входить в систему с одной и той же учетной записью и учетными данными на всех этих доменах. Стандарт WebAuthn создавал бы проблему для таких сценариев, поскольку Passkeys могут быть привязаны только к одному домену (Relying Party ID), например, www.kayak.com.
Чтобы преодолеть эту проблему, вы бы использовали iframe с источником www.kayak.com на всех остальных своих доменах. То есть вы встраиваете iframe с источником www.kayak.com на www.kayak.us и на www.kayak.de (междоменный iframe). В противном случае использование ваших Passkeys, привязанных к «www.kayak.com», на этих других доменах было бы невозможно из-за устойчивости Passkeys к фишингу.
К слову: в качестве альтернативы можно было бы использовать новую функцию WebAuthn Related Origin Requests (RoR). Эта функция позволяет «связанным источникам» получать доступ к Passkeys без iframe, но пока она поддерживается не всеми браузерами.
Для бесшовных платежных потоков использование Passkeys в междоменных iframe также играет важную роль. Рассмотрим следующий сценарий: клиент хочет купить новые туфли на сайте продавца (например, www.amazon.com). Сайт этого продавца позволяет клиенту оплатить через банковский счет (например, в www.revolut.com), и для этого требуется, чтобы пользователь вошел на сайт банка (это упрощенный процесс). Пользователь входит на сайт банка с помощью Passkey, который привязан к Relying Party ID банка, например, «revolut.com».
Чтобы избежать перенаправления пользователя с сайта продавца (www.amazon.com) на сайт банка (www.revolut.com) в процессе оформления заказа и позволить ему войти в свой банковский аккаунт, можно использовать междоменный iframe. Таким образом, пользователь остается на www.amazon.com и использует для аутентификации в междоменном iframe тот Passkey, который он создал для www.revolut.com.
Таким образом, интеграция Passkeys через междоменные iframe в платежные потоки обеспечивает безопасные и оптимизированные транзакции между потребителями, продавцами и банками:
Потребители | Продавцы | Банки |
---|---|---|
|
|
|
В контексте платежей и Passkeys мы также рекомендуем ознакомиться с нашей статьей о Secure Payment Confirmation (SPC) и динамической привязке с помощью Passkeys. Обязательно обратите внимание на ограничения для стороннего контекста в нативных приложениях, описанные ниже.
Кроме того, для более глубокого понимания междоменных платежных потоков с использованием Passkeys, см. нашу статью Passkeys для платежных провайдеров: как создать сторонний SDK.
В целом, интеграция Passkeys в iframe дает несколько преимуществ, в основном за счет улучшения пользовательского опыта и безопасности. Вот разбивка этих преимуществ:
Улучшенный пользовательский опыт
Повышенная безопасность
Реализация Passkeys в iframe включает несколько ключевых шагов для обеспечения безопасности и функциональности. Мы предоставляем подробное руководство для разработчиков. Пожалуйста, ознакомьтесь также с примером реализации на https://cross-origin-iframe.vercel.app/.
HTTP-заголовок Permissions-Policy
помогает разрешить или запретить использование
определенных функций браузера в документе или внутри элемента iframe. Чтобы включить вход
с помощью Passkey в iframe, вы должны установить политики разрешений
publickey-credentials-get
и
publickey-credentials-create.
Эти политики позволяют встроенному контенту вызывать необходимые методы WebAuthn API для
аутентификации (navigator.credentials.get({publicKey})
) и
создания Passkey
(navigator.credentials.create({publicKey})
).
<iframe src="https://passkeys.eu" allow="publickey-credentials-get; publickey-credentials-create"></iframe>
HTTP Permissions Policy
ранее называлась Feature Policy
. В рамках Feature Policy
можно было предоставить доступ к функции междоменному iframe, либо добавив источник в
список источников заголовка, либо включив атрибут allow
в тег iframe. С
Permissions Policy
добавление междоменного фрейма в список источников требует, чтобы тег
iframe для этого источника также включал атрибут allow
. Если в ответе отсутствует
заголовок Permissions Policy
, список источников по умолчанию равен *
(все источники).
Включение атрибута allow
в iframe предоставляет доступ к функции.
Чтобы гарантировать, что междоменные iframe, не указанные в списке источников, будут
заблокированы от доступа к функции, даже если присутствует атрибут allow
, разработчики
могут явно установить заголовок Permissions Policy
в ответе.
В Chrome 88+ все еще можно использовать Feature Policy
, но он действует как псевдоним
для Permissions Policy
. Помимо синтаксических различий, логика остается той же. Когда
одновременно используются заголовки Permissions Policy
и Feature Policy
, заголовок
Permissions Policy
имеет приоритет и переопределит значение, установленное заголовком
Feature Policy
. Пожалуйста, ознакомьтесь также с этой
статьей от команды Chrome
для получения более подробной информации о реализации.
Убедитесь, что HTTP-заголовки ответа от URL-адреса источника iframe включают соответствующую ´Permissions-Policy`. Это критически важно для поддержки междоменных iframe.
Permissions-Policy: publickey-credentials-get=*, publickey-credentials-create=*
Для более детального контроля вы можете указать конкретные источники, которым разрешено встраивать контент iframe.
Permissions-Policy: publickey-credentials-get=("https://passkeys.eu"), publickey-credentials-create=("https://passkeys.eu")
Убедитесь, что контент iframe требует действия пользователя для запуска аутентификации с помощью Passkey. Это можно сделать с помощью обработчиков событий для кликов или отправки форм внутри iframe. Этот процесс также называется временной активацией (transient activation).
document.getElementById('loginPasskeyButton').addEventListener('click', async () => { try { const [publicKeyCredentialRequestOptions](/glossary/publickeycredentialrequestoptions) = { /* Параметры конфигурации */ }; const credential = await navigator.credentials.get({publicKey: publicKeyCredentialRequestOptions}); // Обработка созданных учетных данных } catch (err) { console.error('Ошибка аутентификации через Passkey:', err); } });
В этом контексте также ознакомьтесь с нашей статьей о требованиях к жестам пользователя в Safari.
Ниже вы найдете полный пример кода файла index.html
, размещенного на
https://cross-origin-iframe.vercel.com, который
использует междоменный iframe для Passkeys через
https://passkeys.eu.
<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="Permissions-Policy" content="publickey-credentials-get=*; publickey-credentials-create=*" /> <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self'; frame-src https://passkeys.eu;" /> <title>Демонстрация междоменного iframe с Passkeys</title> <style> body { font-family: Arial, sans-serif; padding: 20px; display: flex; flex-direction: column; justify-content: center; align-items: center; height: 100vh; margin: 0; } h1 { width: 100%; text-align: center; } .iframe-container { width: 80%; max-width: 800px; height: 80%; max-height: 600px; border: 1px solid #ccc; box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); margin-top: 20px; } iframe { width: 100%; height: 100%; border: none; } @media (max-width: 768px) { h1 { width: 95%; } .iframe-container { width: 95%; } } </style> </head> <body> <h1>Демонстрация междоменного iframe с Passkeys</h1> <div class="iframe-container"> <iframe src="https://passkeys.eu" allow="publickey-credentials-create; publickey-credentials-get" ></iframe> </div> </body> </html>
При реализации Passkeys в iframe могут возникнуть проблемы, которые разработчикам необходимо решить для обеспечения плавного и безопасного пользовательского опыта. Вот подробный разбор распространенных проблем и способов их преодоления.
Проблема: Неправильная настройка политик разрешений может помешать iframe получить доступ к WebAuthn API.
«NotAllowedError - The 'publickey-credentials-create' feature is not enabled in this document. Permissions Policy may be used to delegate Web Authentication capabilities to cross-origin child frames.»
Если вы неправильно добавите политики разрешений, браузер выдаст следующую ошибку:
Решение:
allow
и HTTP-заголовки: Убедитесь, что
атрибут allow
и HTTP-заголовки установлены правильно. Проверьте, что разрешения
publickey-credentials-get
и publickey-credentials-create
включены как в элемент
iframe, так и в HTTP-заголовки ответа сервера.<meta/>
для
определения политик разрешений вместо установки заголовков на вашем веб-сервере.Permissions-Policy
называлась Feature-Policy
. Отдельные элементы Feature-Policy
разделялись запятой, а
не точкой с запятой (что является стандартом для Permissions-Policy
).
Permissions-Policy
в iframe все еще следует синтаксису Feature-Policy
и, таким
образом, использует запятые. Однако атрибуты sandbox
/ allow
по-прежнему разделяются
точкой с запятой (см. фрагмент кода выше).Совет: Чтобы правильно проверить, что ваши заголовки Permission-Policy
установлены
верно, мы рекомендуем открыть инструменты разработчика вашего браузера, перейти в
Application (здесь: в инструментах разработчика Chrome), затем в Frames и найти
источник iframe (здесь: passkeys.eu/). Если Permissions-Policy
установлена правильно,
publickey-credential-create
и publickey-credential-get
должны быть перечислены среди
Разрешенных функций (Allowed Features):
Проблема: Создание Passkey или вход с помощью Passkey в междоменном iframe не работает, и вы видите следующую ошибку в консоли браузера.
"NotAllowedError - The origin of the document is not the same as its ancestors."
Эта ошибка появляется при использовании браузера Safari и попытке создать Passkey из iframe, поскольку Safari не поддерживает создание Passkey в междоменном iframe (см. выше).
Решение: Здесь вы мало что можете сделать, так как Safari пока не поддерживает создание Passkey из междоменного iframe.
Blocked a frame with origin "https://passkeys.eu" from accessing a frame with origin "https://cross-origin-iframe.vercel.app". Protocols, domains, and ports must match.
Эта ошибка не связана напрямую с Passkeys, а скорее с междоменными iframe в Safari в целом. В рамках инициативы Safari / WebKit по блокировке сторонних cookie или доступа к LocalStorage в стороннем контексте, часть логики JavaScript может быть нарушена.
Решение: Здесь вам нужно убедиться, что вы не используете сторонние cookie внутри своих iframe, так как это вызывает ошибку.
Проблема: Проблемы совместимости iframe с браузерами возникают, когда разные браузеры имеют разный уровень поддержки WebAuthn, разрешений iframe и атрибутов безопасности, что приводит к нестабильному поведению.
Решение: Чтобы смягчить эти проблемы совместимости, протестируйте реализацию в нескольких браузерах, чтобы обеспечить совместимость и выявить любые специфичные для браузера проблемы.
Шаги:
Проблема: При использовании iframe, требующих Passkeys, внутри нативных приложений, необходимо делать важное различие между контекстом основного домена (first-party) и сторонним контекстом (third-party):
Во встроенном WebView (EWV), таком как WKWebView на iOS или WebView на Android, вызывающее приложение имеет обширный контроль над веб-сессией (например, может перехватывать запросы). Эта конфигурация обычно поддерживает Passkeys только в том случае, если домен Passkey (Relying Party ID) совпадает с доменом приложения (контекст основного домена). Однако в стороннем сценарии — например, в междоменном потоке платежного провайдера — встроенный WebView обычно не может получить доступ к необходимым учетным данным Passkey, потому что приложение продавца и сервис платежного провайдера имеют разные источники. Требуемые «привязки» для Passkeys (между доменом, учетными данными и источником) не будут совпадать во встроенном контексте.
Это ограничение заставляет многие приложения использовать подход с системным WebView (например, ASWebAuthenticationSession на iOS или Custom Tabs на Android). Системные WebView изолируют сторонний сайт (например, платежного провайдера) в безопасной, похожей на браузер среде, которая корректно разрешает междоменные Passkeys — если сам браузер это поддерживает. Тем не менее, помните, что существующие ограничения iframe в Safari также применяются к ASWebAuthenticationSession, поэтому, если Safari не разрешает определенные операции с Passkey в сторонних iframe, то же самое будет справедливо и для системного WebView. В настоящее время «нативного» решения нет; лучшая практика для сложных потоков — таких как оформление заказа с участием внешних платежных провайдеров — это открывать системный WebView, а не встроенный.
Решение: Для платежных провайдеров (и других третьих сторон, полагающихся на Passkeys между доменами) тщательно планируйте интеграцию, чтобы убедиться, что пользователь переводится из встроенного WebView в системный. Хотя это менее бесшовный опыт, чем чисто встроенный поток, часто это единственный способ гарантировать, что функциональность Passkey будет работать со сторонними сервисами.
Для получения более подробной информации об обработке сторонних Passkeys в нативных приложениях и WebView, ознакомьтесь со статьей Passkeys для платежных провайдеров: сторонний SDK для платежей с Passkeys.
Хотя обсуждаемые выше темы применимы к различным сценариям, они особенно важны для платежных провайдеров, где многодоменные потоки (например, сайт продавца и платежный шлюз) должны встраивать аутентификацию пользователей в междоменные iframe. В таких конфигурациях:
pay.provider.com
), даже если они встроены в сайт
продавца.Чтобы справиться с этими проблемами и создать безопасный, бесшовный опыт, подобный Apple Pay, платежные провайдеры часто применяют гибридный подход — сочетая интеграцию на основе iframe с запасным вариантом в виде перенаправления для Safari (или старых браузеров). В некоторых случаях потоки через системный браузер (например, ASWebAuthenticationSession на iOS) становятся обязательными, если встроенный WebView вообще не позволяет использовать Passkeys.
Для глубокого погружения в эти специфичные для платежей сценарии — включая сравнение iframe и перенаправления, соображения по нативным приложениям и лучшие практики для высокого уровня внедрения Passkeys, см. нашу специальную статью:
60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle
В частности:
Permissions-Policy
, представленные здесь.Это дополнительное руководство предоставляет углубленные стратегии для обеспечения безопасности транзакций, преодоления междоменных ограничений Safari и оптимизации использования Passkeys в сторонних контекстах. Сочетая технические шаги из этой статьи с теми методами, которые ориентированы на платежи, вы можете предоставить беспрепятственный, устойчивый к фишингу процесс оформления заказа непосредственно внутри iframe, открывая новый уровень безопасности и UX для онлайн-платежей.
Интеграция Passkeys в iframe значительно улучшает аутентификацию пользователей, повышая как безопасность, так и пользовательский опыт. Это позволяет осуществлять бесшовную аутентификацию без необходимости перенаправлений или всплывающих окон, обеспечивая единообразный UX в различных разделах и на разных сайтах.
Реальные примеры, такие как интеграция Passkeys в Shopify в их компонент входа, демонстрируют практические преимущества и гибкость этого подхода.
Enjoyed this read?
🤝 Join our Passkeys Community
Share passkeys implementation tips and get support to free the world from passwords.
🚀 Subscribe to Substack
Get the latest news, strategies, and insights about passkeys sent straight to your inbox.
Related Articles
Table of Contents