Заголовок ответа HTTP Permissions-Policy предоставляет механизм для разрешения и запрета использования функций браузера в документе или внутри любых элементов <iframe> в этом документе.

О нарушениях политики можно сообщать с помощью Reporting API. Отчёты могут отправляться на сервер, указанный по имени в параметре report-to для конкретной директивы, либо на конечную точку сервера с именем "default" (сопоставление имён конечных точек сервера и URL-адресов настраивается с помощью HTTP-заголовка ответа Reporting-Endpoints). Отчёты также можно отслеживать на странице, для которой применяется политика, с помощью ReportingObserver. Формат отчёта и дополнительные сведения приведены в PermissionsPolicyViolationReport.

Для получения дополнительной информации смотрите основную статью о Permissions Policy.

Синтаксис

# Single directive
Permissions-Policy: <directive>=<allowlist>

# Single directive with reporting endpoint
Permissions-Policy: <directive>=<allowlist>;report-to=<endpoint>

# Multiple directives, with and without server reporting endpoints
Permissions-Policy: <directive>=<allowlist>, <directive>=<allowlist>;report-to=<endpoint>, ...

Заголовок можно использовать для установки списков разрешений (allowlists) для одной или нескольких директив, а также опционального параметра report-to для конкретной директивы, указывающего конечную точку сервера для отправки отчётов о нарушениях политики. Записи для каждой директивы разделяются запятыми.

<directive>

Директива Permissions Policy, к которой применяется allowlist. Список допустимых имён директив приведён в разделе Директивы ниже.

<allowlist>

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

* (подстановочный знак)

Функция будет разрешена в этом документе и во всех вложенных контекстах просмотра (<iframe>) независимо от их источника.

() (пустой список разрешений)

Функция отключена в контекстах просмотра верхнего уровня и во вложенных контекстах просмотра. Эквивалентом для атрибутов allow тега <iframe> является 'none'.

self

Функция будет разрешена в этом документе и во всех вложенных контекстах просмотра (<iframe>) только того же источника. Функция запрещена в документах с другого источника во вложенных контекстах просмотра. self можно рассматривать как сокращение для https://your-site.example.com. Эквивалентом для атрибутов allow тега <iframe> является self.

src

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

"<origin>"

Функция разрешена для определённых источников (например, "https://a.example.com"). Источники должны разделяться пробелами. Обратите внимание, что источники в атрибутах allow тега <iframe> не заключаются в кавычки.

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

Примечание: Директивы имеют список разрешений по умолчанию, который для HTTP-заголовка Permissions-Policy всегда является одним из *, self или none, и определяет поведение по умолчанию, если они явно не указаны в политике. Они указываются на отдельных страницах описания директив. Для атрибутов allow тега <iframe> поведением по умолчанию всегда является src.

report-to=<endpoint> Необязательный

Параметр report-to можно использовать для указания имени конечной точки отчётов, куда будут отправляться отчёты при нарушении политики для связанной директивы. Имя конечной точки и связанный с ней URL-адрес должны быть указаны в отдельном заголовке ответа HTTP Reporting-Endpoints.

Если параметр опущен, отчёты будут отправляться в конечную точку отчётов default, если она была определена. Дополнительные сведения см. в разделе Reporting API.

Там, где это поддерживается, вы можете включать подстановочные знаки в источники Permissions Policy. Это означает, что вместо явного указания нескольких различных поддоменов в списке разрешений вы можете указать их все в одном источнике с помощью подстановочного знака.

Поэтому вместо:

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

Вы можете указать:

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

Директивы

accelerometer

Определяет, разрешено ли текущему документу собирать информацию об ускорении устройства через интерфейс Accelerometer.

ambient-light-sensor

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

aria-notify

Определяет, разрешено ли текущему документу использовать метод ariaNotify() для запуска объявлений программы чтения с экрана.

attribution-reporting

Определяет, разрешено ли текущему документу использовать Attribution Reporting API.

autoplay

Определяет, разрешено ли текущему документу автоматически воспроизводить медиафайлы, запрошенные через интерфейс HTMLMediaElement. Когда эта политика отключена и действий со стороны пользователя не было, Promise, возвращаемый методом HTMLMediaElement.play(), будет отклонён с ошибкой NotAllowedError DOMException. Атрибут autoplay в элементах <audio> и <video> будет игнорироваться.

bluetooth

Определяет, разрешено ли использование Web Bluetooth API. Когда эта политика отключена, методы объекта Bluetooth, возвращаемого Navigator.bluetooth, либо вернут false, либо отклонят возвращённый Promise с ошибкой SecurityError DOMException.

browsing-topics

Управляет доступом к Topics API. Если политика явно запрещает использование Topics API, любые попытки вызвать метод Document.browsingTopics() или отправить запрос с заголовком Sec-Browsing-Topics завершатся ошибкой с NotAllowedError DOMException.

camera

Определяет, разрешено ли текущему документу использовать устройства ввода видео. Promise, возвращаемый методом getUserMedia(), будет отклонён с ошибкой NotAllowedError DOMException, если разрешение не предоставлено.

captured-surface-control

Определяет, разрешено ли документу использовать Captured Surface Control API. Промис, возвращаемый основными методами API, будет отклонён с ошибкой NotAllowedError DOMException, если разрешение не предоставлено.

ch-ua-high-entropy-values

Определяет, разрешено ли документу использовать метод NavigatorUAData.getHighEntropyValues() для получения данных с высокой энтропией (high-entropy user-agent data). Если разрешение не предоставлено, метод вернёт только низкоэнтропийные данные: brands, mobile и platform.

compute-pressure

Управляет доступом к Compute Pressure API.

cross-origin-isolated

Определяет, может ли текущий документ рассматриваться как изолированный от других источников (cross-origin isolated).

deferred-fetch

Управляет выделением квоты fetchLater() источника верхнего уровня.

deferred-fetch-minimal

Управляет выделением общей квоты fetchLater() для подфреймов других источников.

display-capture

Определяет, разрешено ли текущему документу использовать метод getDisplayMedia() для захвата содержимого экрана. Когда эта политика отключена, промис, возвращаемый getDisplayMedia(), будет отклонён с ошибкой NotAllowedError DOMException, если не получено разрешение на захват содержимого экрана.

encrypted-media

Определяет, разрешено ли текущему документу использовать Encrypted Media Extensions API (EME). Когда эта политика отключена, Promise, возвращаемый методом Navigator.requestMediaKeySystemAccess(), будет отклонён с ошибкой SecurityError DOMException.

fullscreen

Определяет, разрешено ли текущему документу использовать Element.requestFullscreen(). Когда эта политика отключена, возвращаемый Promise отклоняется с ошибкой TypeError.

gamepad

Определяет, разрешено ли текущему документу использовать Gamepad API. Когда эта политика отключена, вызовы Navigator.getGamepads() будут вызывать исключение SecurityError DOMException, а события gamepadconnected и gamepaddisconnected не будут срабатывать.

geolocation

Определяет, разрешено ли текущему документу использовать интерфейс Geolocation. Когда эта политика отключена, вызовы getCurrentPosition() и watchPosition() приведут к тому, что колбэки этих функций будут вызваны с кодом GeolocationPositionError, равным PERMISSION_DENIED.

gyroscope

Определяет, разрешено ли текущему документу собирать информацию об ориентации устройства через интерфейс Gyroscope.

hid

Определяет, разрешено ли текущему документу использовать WebHID API для подключения к нестандартным или экзотическим устройствам пользовательского интерфейса, таким как альтернативные клавиатуры или геймпады.

identity-credentials-get

Определяет, разрешено ли текущему документу использовать Federated Credential Management API (FedCM).

idle-detection

Определяет, разрешено ли текущему документу использовать Idle Detection API для определения того, взаимодействуют ли пользователи со своими устройствами, например, для отправки статуса «доступен»/«отошёл» в чат-приложениях.

language-detector

Управляет доступом к функционалу определения языка Translator and Language Detector APIs.

local-fonts

Определяет, разрешено ли текущему документу собирать данные о локально установленных шрифтах пользователя через метод Window.queryLocalFonts() (см. также Local Font Access API).

local-network

Определяет, разрешено ли текущему документу выполнять сетевые запросы к локальным адресам.

local-network-access

Определяет, разрешено ли текущему документу выполнять сетевые запросы к локальным адресам и адресам loopback. Эта директива политики является псевдонимом для более детализированных директив local-network и loopback-network.

loopback-network

Определяет, разрешено ли текущему документу выполнять сетевые запросы к адресам loopback.

magnetometer

Определяет, разрешено ли текущему документу собирать информацию об ориентации устройства через интерфейс Magnetometer.

microphone

Определяет, разрешено ли текущему документу использовать устройства аудиоввода. Когда эта политика отключена, Promise, возвращаемый методом MediaDevices.getUserMedia(), будет отклонён с ошибкой NotAllowedError DOMException.

midi

Определяет, разрешено ли текущему документу использовать Web MIDI API. Когда эта политика отключена, Promise, возвращаемый методом Navigator.requestMIDIAccess(), будет отклонён с ошибкой SecurityError DOMException.

on-device-speech-recognition

Управляет доступом к функционалу распознавания речи на устройстве Web Speech API.

otp-credentials

Определяет, разрешено ли текущему документу использовать WebOTP API для запроса одноразового пароля (OTP) из специальным образом отформатированного SMS-сообщения, отправленного сервером приложения, то есть через navigator.credentials.get({otp: ..., ...}).

payment

Определяет, разрешено ли текущему документу использовать Payment Request API. Когда эта политика включена, конструктор PaymentRequest() будет выбрасывать исключение SecurityError DOMException.

picture-in-picture

Определяет, разрешено ли текущему документу воспроизводить видео в режиме «картинка в картинке» с помощью соответствующего API.

private-state-token-issuance

Управляет использованием операций token-request токенов приватного состояния.

private-state-token-redemption

Управляет использованием операций token-redemption и send-redemption-record токенов приватного состояния.

publickey-credentials-create

Определяет, разрешено ли текущему документу использовать Web Authentication API для создания новых учётных данных на основе асимметричных ключей, то есть через navigator.credentials.create({publicKey: ..., ...}).

publickey-credentials-get

Определяет, разрешено ли текущему документу использовать Web Authentication API для получения уже сохранённых учётных данных с открытым ключом, то есть через navigator.credentials.get({publicKey: ..., ...}).

screen-wake-lock

Определяет, разрешено ли текущему документу использовать Screen Wake Lock API, чтобы указывать, что устройство не должно выключать или затемнять экран.

serial

Определяет, разрешено ли текущему документу использовать Web Serial API для связи с последовательными устройствами, подключёнными напрямую через последовательный порт либо через USB- или Bluetooth-устройства, эмулирующие последовательный порт.

speaker-selection

Определяет, разрешено ли текущему документу использовать Audio Output Devices API для перечисления и выбора динамиков.

storage-access

Определяет, разрешено ли документу, загруженному в контексте стороннего ресурса (т. е. встроенному в <iframe>), использовать Storage Access API для запроса доступа к неразделяемым cookie.

translator

Управляет доступом к функционалу перевода Translator and Language Detector APIs.

summarizer

Управляет доступом к Summarizer API.

usb

Определяет, разрешено ли текущему документу использовать WebUSB API.

web-share

Определяет, разрешено ли текущему документу использовать метод Navigator.share() интерфейса Web Share API для отправки текста, ссылок, изображений и другого контента в произвольные места назначения по выбору пользователя, например, в мобильные приложения.

window-management

Определяет, разрешено ли текущему документу использовать Window Management API для управления окнами на нескольких дисплеях.

xr-spatial-tracking

Определяет, разрешено ли текущему документу использовать WebXR Device API для взаимодействия с сессией WebXR.

Примеры

Базовое использование

Заголовок Permissions-Policy

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

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=*

iframes

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

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

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

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

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

Это важно: по умолчанию, если <iframe> переходит на другой источник, политика не применяется к источнику, на который переходит <iframe>. Если указать источник, на который переходит <iframe>, в атрибуте allow, политика Permissions Policy, примененная к исходному <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>

Запрет доступа к расширенным возможностям

Компания SecureCorp Inc. хочет отключить API микрофона (например, MediaDevices.getUserMedia()) и Geolocation в своем приложении. Это можно сделать с помощью следующего заголовка ответа:

Permissions-Policy: microphone=(), geolocation=()

Указав () для списка источников, указанные возможности будут отключены для всех контекстов просмотра (включая все <iframe>), независимо от их источника.

Комбинирование политик HTTP-заголовка и <iframe>

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

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 на серверную конечную точку.

Приведенные ниже заголовки ответа блокируют геолокацию и определяют имя конечной точки отчетов для этой возможности как "geo_endpoint". HTTP-заголовок ответа Reporting-Endpoints используется для определения URL-адреса этого имени конечной точки.

Reporting-Endpoints: geo_endpoint="https://example.com/reports"
Permissions-Policy: geolocation=();report-to=geo_endpoint

Reporting-Endpoints: default="https://example.com/reports"
Permissions-Policy: geolocation=()

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

navigator.geolocation.getCurrentPosition(
  () => {},
  () => {},
);

Отправляемые на конечную точку полезные данные отчета могут выглядеть следующим образом:

[
  {
    "age": 48512,
    "body": {
      "columnNumber": 29,
      "disposition": "enforce",
      "lineNumber": 44,
      "message": "Permissions policy violation: geolocation access has been blocked because of a permissions policy applied to the current document.",
      "featureId": "geolocation",
      "sourceFile": "https://example.com/"
    },
    "type": "permissions-policy-violation",
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36"
  }
]

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

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

Смотрите также

• Permissions Policy
• Permissions-Policy-Report-Only
• Document.featurePolicy и FeaturePolicy
• Content-Security-Policy
• Referrer-Policy
• Reporting-Endpoints
• PermissionsPolicyViolationReport
• ReportingObserver
• Reporting API