API доступа к хранилищу

API доступа к хранилищу предоставляет возможность содержимому стороннего сайта, загруженному в контексте третьей стороны (например, встроенному в <iframe>), получить доступ к куки сторонних сайтов и неразделенным данным состояния, к которым обычно имелся доступ только в контексте сайта-владельца (то есть при загрузке напрямую в вкладке браузера).

API доступа к хранилищу актуален для браузеров, которые по умолчанию блокируют доступ к куки сторонних сайтов и неразделенным данным состояния для повышения конфиденциальности (например, для предотвращения отслеживания). Существуют законные случаи использования куки сторонних сайтов и неразделенных данных состояния, которые мы по-прежнему хотим поддерживать, даже с этими ограничениями по умолчанию. Примерами являются единый вход (SSO) с поставщиками федеративной идентификации (IdP) или сохранение пользовательских данных, таких как данные местоположения или предпочтения просмотра, на разных сайтах.

API предоставляет методы, которые позволяют встроенным ресурсам проверять, имеют ли они доступ к куки сторонних сайтов, и, если нет, запрашивать этот доступ у пользователя.

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

Семантика блокировки функций и политик для куки сторонних сайтов и неразделенных данных состояния отличается от браузера к браузеру, но основная функциональность одинакова. Ресурсы сторонних сайтов, встроенные в контексте третьей стороны, не получают доступ к тем же данным состояния, что и при загрузке в контексте первого уровня. Это делается с добрыми намерениями — поставщики браузеров хотят принять меры для лучшей защиты конфиденциальности и безопасности своих пользователей. Примерами являются уменьшение возможности отслеживания активности пользователя по разным сайтам и меньшая уязвимость к атакам, таким как межсайтовая подделка запроса ( CSRF).

Однако существуют законные случаи использования встроенного содержимого стороннего сайта для доступа к куки сторонних сайтов и неразделенным данным состояния, которые известны тем, что нарушаются вышеупомянутые функции и политики. Предположим, у вас есть ряд различных сайтов, которые предоставляют доступ к различным продуктам — heads-example.com, shoulders-example.com, knees-example.com, и toes-example.com.

Или вы можете разделить свое содержимое или услуги на разные домены стран для целей локализации — example.com, example.ua, example.br, и т. д. — или каким-либо другим способом.

У вас могут быть дополнительные утилитарные сайты с компонентами, встроенными во все другие сайты, например, для предоставления SSO (sso-example.com) или общих персонализированных услуг (services-example.com). Эти утилитарные сайты захотят поделиться своими данными со встроенными сайтами через куки. Они не могут использовать куки первого уровня, так как находятся на разных доменах, и куки третьих сторон больше не будут работать в браузерах, которые их блокируют.

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

API доступа к хранилищу предназначен для решения этой проблемы; встроенное содержимое стороннего сайта может запрашивать неограниченный доступ к куки сторонних сайтов и неразделенным данным состояния на основе каждого кадра с помощью метода Document.requestStorageAccess(). Он также может проверить, есть ли у него уже доступ с помощью метода Document.hasStorageAccess().

Важно отметить, что API доступа к хранилищу необходим только для предоставления доступа к неразделенным куки сторонних сайтов. Это означает куки, хранящиеся традиционным способом с ранних дней интернета — все куки, установленные на одном сайте, хранятся в одном хранилище куки. Это в отличие от разделенных куки, где встроенным ресурсам в каждом верхнем уровне сайта предоставляется уникальное хранилище куки, что делает отслеживание пользователей по сайтам с помощью этих куки невозможным.

Браузеры имеют различные механизмы разделения доступа к куки сторонних сайтов, например Firefox Total Cookie Protection и Cookies Having Independent Partitioned State (CHIPS).

Когда мы говорим о куки сторонних сайтов в контексте API доступа к хранилищу, мы подразумеваем неразделенные куки сторонних сайтов.

Встроенное содержимое, которому нужен законный доступ к куки сторонних сайтов или неразделенным данным состояния, может запрашивать доступ с помощью API доступа к хранилищу следующим образом:

1. Он может вызвать метод Document.hasStorageAccess(), чтобы проверить, есть ли у него необходимый доступ.
2. Если нет, он может запросить доступ с помощью метода Document.requestStorageAccess().
3. В зависимости от браузера, пользователю будет предложено разрешить доступ к запрошенному встраиваемому элементу несколько разными способами.
   • Safari показывает запросы для всего встроенного содержимого, которое ранее не получило доступ к хранилищу.
   • Firefox запрашивает разрешение у пользователей только после того, как источник запросил доступ к хранилищу на более чем пороговое количество сайтов.
   • Chrome показывает запросы для всего встроенного содержимого, которое ранее не получило доступ к хранилищу. Однако он автоматически предоставит доступ и пропустит запросы, если встроенное содержимое и сайт-встраиватель являются частью того же набора связанных сайтов.
4. Доступ предоставляется или отказывается на основе соответствия содержимого всем требованиям безопасности — см. Меры безопасности для общих требований и Вариации, специфичные для браузера для некоторых браузерных требований к безопасности. Природа API Promise-based позволяет выполнять код для обработки случаев успеха и неудачи.
   • Современное поведение спецификации диктует, что доступ предоставляется на уровне фрейма — каждый отдельный встроенный элемент имеет блокировку доступа к куки сторонних сайтов по умолчанию и должен вызвать requestStorageAccess(), чтобы получить доступ. Если встроенный элемент получил доступ, а встроенные элементы того же сайта затем вызывают requestStorageAccess(), их обещания выполнятся автоматически. Но им все равно нужно получить доступ.
   • Исключением из поведения «блокировка по умолчанию» является случай, когда встроенный элемент выполняет успешную requestStorageAccess(), а затем выполняет навигацию по тому же источнику (например, перезагружает себя). В таких случаях доступ к хранилищу переносится из предыдущей навигации.
   • В более ранних версиях спецификации доступ предоставлялся на уровне страницы (Safari — единственный браузер, который все еще использует эту модель). Когда один встроенный элемент получил доступ к куки сторонних сайтов через requestStorageAccess(), все остальные встроенные элементы того же сайта автоматически получали доступ. Это нежелательное поведение с точки зрения безопасности — например, если shop.example.com встроил locator.users.com для того, чтобы пользователи могли использовать свои данные местоположения при совершении покупок, и locator.users.com вызвал requestStorageAccess(), shop.example.com и любые другие встроенные сайты могли получить доступ к его кукам, но также получить доступ к кукам private.users.com, что не предназначалось для интеграции. Подробнее о мотивации этой изменения.
5. После предоставления доступа ключ разрешения хранится в браузере со структурой <top-level site, embedded site>. Например, если сайт-встраиватель — embedder.com, а встроенный элемент — locator.example.com, ключ будет <embedder.com, example.com>. Встроенные элементы того же сайта (docs.example.com, profile.example.com, и т. д.) смогут затем вызвать requestStorageAccess() и обещание выполнится автоматически, как упоминалось ранее.
   • Более ранние версии спецификации использовали более конкретную структуру ключа разрешения <top-level site, embedded origin>, что означало, что встроенные элементы того же сайта, но с другим происхождением, не соответствовали ключу разрешения и должны были пройти весь процесс отдельно.

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

1. Вызов должен быть связан с жестом пользователя (временной активацией), таким как нажатие или клик. Это предотвращает спам от встраиваемого контента на странице или от чрезмерного количества запросов на доступ. Обратите внимание, что это не требуется, если:

   • Разрешение на использование API уже предоставлено, например, другим ресурсом того же сайта, вызывающим requestStorageAccess().
   • Вызывающая сторона является документом верхнего уровня или документом того же сайта, что и документ верхнего уровня. В таких случаях, вызов requestStorageAccess(), вероятно, вообще не нужен.

2. Документ и документ верхнего уровня не должны иметь null происхождение.

3. Происхождения, с которыми пользователь никогда не взаимодействовал в качестве первого источника, не имеют понятия о хранилище первого источника. С точки зрения пользователя, у них есть только отношения третьего источника с этим происхождением. Запросы на доступ автоматически отклоняются, если браузер обнаруживает, что пользователь не взаимодействовал с встраиваемым контентом в контексте первого источника недавно (в Firefox «недавно» означает в течение 30 дней).

4. Окно документа должно быть в безопасном контексте.

5. Встроенные <iframe> с ограниченным доступом по умолчанию не могут получить доступ к хранилищу по соображениям безопасности. Поэтому API также добавляет allow-storage-access-by-user-activation маркер sandbox. Веб-сайт, который встраивает этот элемент, должен добавить его, чтобы запросы на доступ к хранилищу завершились успешно, вместе с allow-scripts и allow-same-origin для выполнения скрипта вызова API и его выполнения в источнике, который может использовать куки/состояние:

   <iframe
     sandbox="allow-storage-access-by-user-activation
                   allow-scripts
                   allow-same-origin">
     …
   </iframe>
   

6. Использование этой функции может быть заблокировано политикой storage-access Политики разрешений, установленной на вашем сервере.

Хотя API одинаков, веб-сайты, использующие API доступа к хранилищу, должны ожидать различий в уровне и объёме доступа к кукам третьих сторон в разных браузерах из-за различий в политиках доступа к хранилищу.

• Куки должны иметь SameSite=None явно установленные, так как значение по умолчанию для Chrome — SameSite=Lax (SameSite=None — по умолчанию в Firefox и Safari).
• Куки должны иметь атрибут Secure.
• Разрешения на доступ к хранилищу действуют в течение 30 дней с момента последнего взаимодействия пользователя. Взаимодействие с встроенным контентом продлевает этот срок ещё на 30 дней. Это не происходит, когда вызывается Document.requestStorageAccessFor(), так как пользователь уже на странице.

• Если встроенное происхождение tracker.example уже получило доступ к кукам третьих сторон в происхождении верхнего уровня foo.example, и пользователь посещает страницу из foo.example, встраивающую страницу из tracker.example менее чем за 30 дней, встроенное происхождение получит доступ к кукам третьих сторон сразу при загрузке.
• Разрешения на доступ к хранилищу действуют в течение 30 календарных дней.

Документация по новой политике Firefox по блокированию отслеживающих куков, связанных с доступом к хранилищу, содержит подробное описание сферы действия разрешений на доступ к хранилищу.

• Разрешения на доступ к хранилищу действуют в течение 30 дней с момента последнего взаимодействия пользователя. Успешное использование API доступа к хранилищу сбрасывает этот счётчик.

• См. Использование API доступа к хранилищу для руководства по реализации с примерами кода.
• См. Демонстрацию API доступа к хранилищу для демонстрации в реальном времени.

Document.hasStorageAccess()

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

Document.hasUnpartitionedCookieAccess()

Новое имя для Document.hasStorageAccess().

Document.requestStorageAccess()

Разрешает контенту, загруженному в контексте третьей стороны (т. е., встроенному в <iframe>), запрашивать доступ к кукам третьих сторон и неразделенным данным состояния; возвращает Promise, который разрешается, если доступ предоставлен, и отклоняется, если доступ запрещен.

Document.requestStorageAccessFor() Экспериментальная

Предлагаемое расширение API доступа к хранилищу, которое позволяет сайтам верхнего уровня запрашивать доступ к кукам третьих сторон от имени встроенного контента, происходящего с другого сайта в том же наборе связанных веб-сайтов. Возвращает Promise, который разрешается, если доступ предоставлен, и отклоняется, если доступ запрещен.

Permissions.query(), имя функции "storage-access"

В поддерживающих браузерах это может запросить, предоставлен ли доступ к кукам третьих сторон в целом, то есть другому встроенному элементу того же сайта. Если да, то вы можете вызвать requestStorageAccess() без взаимодействия пользователя, и обещание будет разрешено автоматически.

Permissions.query(), имя функции "top-level-storage-access" Экспериментальная

Отдельное имя функции, используемое для запроса, предоставлено ли разрешение на доступ к кукам третьих сторон через requestStorageAccessFor(). Если да, то вам не нужно вызывать requestStorageAccessFor() снова.

• Использование Storage Access API
• Представление Storage Access API (блог WebKit)