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

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

Примеры того, что можно делать с помощью политики разрешений:

• Изменять поведение автовоспроизведения по умолчанию на мобильных устройствах и для сторонних видео.
• Ограничивать использование сайтом чувствительных устройств, таких как камера, микрофон или динамики.
• Разрешать iframe использовать API полноэкранного режима.
• Запрещать выполнение скриптов для элементов, которые не видны в области просмотра, чтобы повысить производительность.

Основные понятия и использование

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

К возможным подходам относятся:

• Для JavaScript API, которым требуется разрешение пользователя, возвращается сообщение «В доступе отказано».
• JavaScript API, предоставляющие доступ к функциям, возвращают значения false или вызывают ошибку.
• API вообще не предоставляются, как будто их не существует.
• Параметры, управляющие поведением функции, имеют другие значения по умолчанию.

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

Политика разрешений позволяет задавать политики двумя способами:

• HTTP-заголовок Permissions-Policy позволяет управлять использованием функций в полученных ответах и во всём встроенном на страницу контенте (в том числе в <iframe>).
• Атрибут <iframe> allow позволяет управлять использованием функций только в определённых <iframe>.

Эти способы независимы, но связаны между собой — подробности см. в разделе Наследование политик встроенным контентом.

Чтобы управлять каждой функцией, нужно написать политику, состоящую из следующих элементов:

• Директива, задающая имя функции, которой нужно управлять. См. список доступных директив.
• Список разрешённых источников — перечень источников, для которых нужно управлять функцией. Функцию можно включить для всех источников или для определённых источников либо запретить её использование для всех источников.

Несколько примеров приведены ниже.

Связь с API разрешений

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

• Политика разрешений позволяет серверу задавать, можно ли использовать функцию в определённом документе (или во встроенных в него <frame>). Такие функции называются управляемыми политикой — см. список директив политики разрешений.
• API разрешений ограничивает доступ к функциям на основе разрешений, предоставленных пользователем. Эти функции перечислены в реестре разрешений.

Идентификатор каждой функции одинаков для обоих механизмов, например, geolocation для API геолокации. Для большинства функций API из реестра разрешений также предусмотрена соответствующая директива политики разрешений. Одно из исключений — API уведомлений.

Как правило, если политика разрешений блокирует использование мощной функции, у пользователя даже не запросят разрешение на её использование, а метод query() API разрешений вернёт значение denied для свойства state.

См. также «Разрешения» > «Связь со спецификацией политики разрешений».

Списки разрешённых источников

Список разрешённых источников — это перечень, принимающий одно или несколько следующих значений в скобках, разделённых пробелами:

• *: функция будет разрешена в этом документе и во всех вложенных контекстах просмотра (<iframe>) независимо от их источника.
• () (пустой список разрешённых источников): функция отключена в контекстах просмотра верхнего уровня и во вложенных контекстах просмотра. Эквивалент для атрибута <iframe> allow — 'none'.
• self: функция будет разрешена в этом документе и во всех вложенных контекстах просмотра (<iframe>) только с тем же источником. Функция запрещена в документах с другими источниками во вложенных контекстах просмотра. self можно считать сокращённой записью https://your-site.example.com. Эквивалент для атрибута <iframe> allow — 'self'.
• 'src': функция будет разрешена в этом <iframe>, если загруженный в него документ имеет тот же источник, что и URL в его атрибуте src. Это значение используется только в атрибуте <iframe> allow и является значением списка разрешённых источников по умолчанию для <iframe>.
• "<origin>": функция разрешена для определённых источников (например, "https://a.example.com"). Источники следует разделять пробелами. Обратите внимание: источники в атрибутах <iframe> не заключаются в кавычки.

Значения * и () можно использовать только отдельно, а self и src можно сочетать с одним или несколькими источниками.

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

Таким образом, вместо

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

можно указать

("https://example.com" "https://*.example.com")

Примеры списков разрешённых источников:

• *
• ()
• (self)
• (src)
• ("https://a.example.com")
• ("https://a.example.com" "https://b.example.com")
• (self "https://a.example.com" "https://b.example.com")
• (src "https://a.example.com" "https://b.example.com")
• ("https://*.example.com")

Синтаксис заголовка Permissions-Policy

Общий синтаксис выглядит так:

Permissions-Policy: <directive>=<allowlist>

Например, чтобы полностью запретить доступ к геолокации, нужно сделать следующее:

Permissions-Policy: geolocation=()

А чтобы разрешить доступ для части источников, нужно сделать следующее:

Permissions-Policy: geolocation=(self "https://a.example.com" "https://b.example.com")

Одновременно можно управлять несколькими функциями: для этого отправьте заголовок со списком политик, разделённых запятыми, или отдельный заголовок для каждой политики.

Например, следующие варианты эквивалентны:

Permissions-Policy: picture-in-picture=(), geolocation=(self "https://example.com"), camera=*;

Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self "https://example.com")
Permissions-Policy: camera=*

Синтаксис встроенного фрейма

Чтобы функция была включена в <iframe>, его разрешённый источник также должен входить в список разрешённых источников родительской страницы. В связи с этим наследованием политик рекомендуется указывать в HTTP-заголовке максимально широкий допустимый набор источников для функции, а затем задавать необходимое подмножество в каждом <iframe>.

Общий синтаксис выглядит так:

<iframe src="<origin>" allow="<directive> <allowlist>"></iframe>

Например, чтобы полностью запретить доступ к геолокации, нужно сделать следующее:

<iframe src="https://example.com" allow="geolocation 'none'"></iframe>

Чтобы применить политику к текущему источнику и другим источникам, нужно сделать следующее:

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

Важно: по умолчанию, если <iframe> переходит к другому источнику, политика не применяется к источнику, на который переходит <iframe>. Если указать источник, на который переходит <iframe>, в атрибуте allow, политика разрешений, применённая к исходному <iframe>, будет применена к источнику, на который переходит <iframe>.

Одновременно можно управлять несколькими функциями, указав в атрибуте allow список директив политики, разделённых точками с запятой.

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

Отдельно стоит упомянуть значение src. Как упоминалось выше, использование этого значения в списке разрешённых источников означает, что соответствующая функция будет разрешена в этом <iframe>, если загруженный в него документ имеет тот же источник, что и URL в его атрибуте src. Это значение является значением allowlist по умолчанию для функций, перечисленных в allow, поэтому следующие варианты эквивалентны:

<iframe src="https://example.com" allow="geolocation 'src'"></iframe>
<iframe src="https://example.com" allow="geolocation"></iframe>

Изолированные фреймы и политика разрешений

<fencedframe> взаимодействуют с политиками разрешений так же, как <iframe>, но с гораздо более строгими ограничениями. С помощью установленных для них политик разрешений можно включить только определённые функции, предназначенные для использования в <fencedframe>. Другие функции, управляемые политикой, в этом контексте недоступны.

Подробнее см. в разделе Политики разрешений, доступные изолированным фреймам.

Наследование политик встроенным контентом

Скрипты наследуют политику своего контекста просмотра независимо от источника. Это означает, что скрипты верхнего уровня наследуют политику основного документа.

Все <iframe> наследуют политику родительской страницы. Если у <iframe> есть атрибут allow и у родительской страницы есть Permissions-Policy, политики родительской страницы и атрибута allow объединяются с использованием наиболее ограничительного подмножества. Чтобы функция была включена в <iframe>, источник должен входить в список разрешённых источников как родительской страницы, так и атрибута allow.

Отключение функции в политике — необратимое переключение. Если родительский фрейм отключил функцию для дочернего фрейма, дочерний фрейм не может включить её снова; то же относится и ко всем его потомкам.

Примеры

Сочетание HTTP-заголовка и политик <iframe>

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

Permissions-Policy: geolocation=(self "https://trusted-ad-network.com")

В наших рекламных <iframe> мы можем разрешить доступ для источника https://trusted-ad-network.com следующим образом:

<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

Если в <iframe> загрузится другой источник, у него не будет доступа к геолокации:

<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

Спецификации

Совместимость с браузерами

См. также

• Permissions-Policy HTTP-заголовок
• атрибут allow у iframe
• Управление функциями браузера с помощью Permissions Policy: руководство по использованию, которое также содержит несколько ссылок на демонстрации.
• Политики разрешений и функций на chromestatus.com
• Конфиденциальность, разрешения и информационная безопасность