Kontrolowanie funkcji przeglądarki za pomocą zasad uprawnień

Zarządzaj dostępem strony i iframe’ów innych firm na stronie do funkcji przeglądarki.

Kevin K. Lee

Zasady dotyczące uprawnień, wcześniej znane jako zasady dotyczące funkcji, umożliwiają deweloperowi kontrolowanie funkcji przeglądarki dostępnych na stronie, w jej elementach iframe i zasobach podrzędnych przez zadeklarowanie zestawu zasad, które przeglądarka ma egzekwować. Te zasady są stosowane do źródeł podanych na liście źródeł w nagłówku odpowiedzi. Lista źródeł może zawierać źródła tego samego pochodzenia i źródła różnych pochodzeń. Umożliwia ona deweloperowi kontrolowanie dostępu do funkcji przeglądarki przez źródła własne i firmy zewnętrzne.

Użytkownik podejmuje ostateczną decyzję o zezwoleniu na dostęp do bardziej zaawansowanych funkcji i musi wyraźnie wyrazić zgodę, akceptując prośbę.

Zasady dotyczące uprawnień umożliwiają witrynie najwyższego poziomu określenie, do czego ona i jej podmioty zewnętrzne zamierzają używać funkcji, i zwalniają użytkownika z obowiązku określania, czy prośba o dostęp do funkcji jest uzasadniona. Na przykład za pomocą zasady uprawnień deweloper może zablokować funkcję geolokalizacji dla wszystkich podmiotów zewnętrznych, dzięki czemu będzie mieć pewność, że żaden z nich nie uzyska dostępu do geolokalizacji użytkownika.

Zmiany w zasadach dotyczących uprawnień

Zasady dotyczące uprawnień były wcześniej znane jako zasady dotyczące funkcji. Kluczowe pojęcia pozostają takie same, ale oprócz nazwy wprowadziliśmy kilka ważnych zmian.

Używanie pól strukturalnych

Pola strukturalne zapewniają zestaw wspólnych struktur danych, które ujednolicają analizowanie i serializowanie wartości pól nagłówka HTTP. Więcej informacji o polach strukturalnych znajdziesz w poście na blogu Fastly „Improving HTTP with structured header fields” (w języku angielskim).

  geolocation 'self' https://example.com; camera 'none'

  geolocation=(self "https://example.com"), camera=()

Łączenie nagłówków z atrybutem allow tagu iframe

Za pomocą Feature Policy możesz dodać funkcję do ramki z innej domeny, dodając domenę do listy domen w nagłówku lub dodając atrybut allow do tagu iframe. Jeśli w ramach zasad dotyczących uprawnień dodasz do listy źródeł ramkę z innego źródła, tag iframe dla tego źródła musi zawierać atrybut allow. Jeśli odpowiedź nie zawiera nagłówka Permissions Policy, lista źródeł ma domyślną wartość *. Dodanie atrybutu allow do elementu iframe umożliwia dostęp do tej funkcji.

Dlatego zalecamy deweloperom wyraźne ustawienie w odpowiedzi nagłówka Permissions Policy, aby ramki iframe z innych domen, które nie są wymienione na liście domen, nie miały dostępu do tej funkcji, nawet jeśli występuje w niej wartość allow.

Zasady dotyczące funkcji można nadal stosować po Chrome 88, ale działają one jako alias zasad dotyczących uprawnień. Poza składnią nie ma różnicy w logice. Jeśli używane są jednocześnie nagłówki Permissions Policy i Feature Policy, nagłówek Permissions-Policy ma wyższy priorytet i zastępuje wartość podaną w nagłówku Feature-Policy.

Jak korzystać z zasad dotyczących uprawnień?

Krótkie omówienie

Zanim przejdziemy do szczegółów, przyjrzyjmy się typowemu scenariuszowi, w którym jesteś właścicielem witryny i chcesz kontrolować, jak Twoja witryna i kod innej firmy korzystają z funkcji przeglądarki.

• Twoja witryna to https://your-site.example.
• Twoja witryna zawiera element iframe z tej samej domeny (https://your-site.example).
• Witryna zawiera element iframe z domeny https://trusted-site.example, której ufasz.
• W Twojej witrynie wyświetlają się też reklamy dostarczane przez https://ad.example.
• Chcesz zezwolić na geolokalizację tylko w przypadku Twojej witryny i zaufanej witryny, a nie w przypadku reklamy.

W takim przypadku użyj tego nagłówka:

Permissions-Policy: geolocation=(self "https://trusted-site.example")

W przypadku tagu iframe zaufanej witryny ustaw jawnie atrybut allow:

<iframe src="https://trusted-site.example" allow="geolocation">

W tym przykładzie lista źródeł w nagłówku zezwala na korzystanie z funkcji geolokalizacji tylko Twojej witrynie (self) i trusted-site.example. ad.example nie może korzystać z geolokalizacji.

1. Twoja witryna your-site.example może korzystać z funkcji geolokalizacji za zgodą użytkownika.
2. Ramka iframe z tej samej domeny (your-site.example) może korzystać z tej funkcji bez użycia atrybutu allow.
3. Element iframe wyświetlany z innej subdomeny (subdomain.your-site-example), która nie została dodana do listy źródeł i ma ustawiony atrybut allow w tagu iframe, nie może korzystać z tej funkcji. Różne subdomeny są traktowane jako witryny tego samego rodzaju, ale o różnych źródłach.
4. Ramka iframe z innej domeny (trusted-site.example), która została dodana do listy domen i ma ustawiony atrybut allow w tagu iframe, może korzystać z tej funkcji.
5. Ramka iframe z innej domeny (trusted-site.example) dodana do listy domen bez atrybutu allow nie może korzystać z tej funkcji.
6. Ramka iframe z innej domeny (ad.example), która nie została dodana do listy domen, nie może korzystać z tej funkcji, nawet jeśli atrybut allow jest uwzględniony w tagu iframe.

Permissions-Policy Nagłówek odpowiedzi HTTP

Permissions-Policy: <feature>=(<token>|<origin(s)>)

Użyj nagłówka Permissions-Policy w odpowiedzi z serwera, aby ustawić dozwolone źródła dla funkcji. Wartość nagłówka może zawierać kombinację tokenów i ciągów tekstowych z nazwami domen. Dostępne tokeny to * w przypadku wszystkich elementów origin i self w przypadku tego samego elementu origin.

Jeśli nagłówek dotyczy kilku funkcji, oddziel je przecinkami. Jeśli podajesz wiele źródeł, rozdziel je spacjami. W przypadku nagłówków, które zawierają źródło będące żądaniem z innej domeny, tag iframe musi zawierać atrybut allow.

Oto kilka przykładowych par klucz-wartość:

• Składnia: [FEATURE]=*
  • Zasady zastosowane do wszystkich elementów origin
  • Przykład: geolocation=*
• Składnia: [FEATURE]=(self)
  • Zasady zastosowane w przypadku tej samej domeny
  • Przykład: geolocation=(self)
• Składnia: [FEATURE]=(self [ORIGIN(s)])
  • Zasady zastosowane do tego samego pochodzenia i określonych pochodzeń
  • Przykład: geolocation=(self "https://a.example" "https://b.example")
  • self to skrót od https://your-site.example
• Składnia: [FEATURE]=([ORIGIN(s)])
  • Zasady zastosowane do tego samego pochodzenia i określonych pochodzeń
  • Przykład: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Gdy używasz tej składni, jednym ze źródeł powinien być źródło aplikacji osadzającej. Jeśli strona osadzająca nie ma przyznanych uprawnień, ramki iframe osadzone na tej stronie również zostaną zablokowane, mimo że zostały dodane do listy źródeł, ponieważ zasady uprawnień delegują uprawnienia. Możesz też użyć tokena self.
• Składnia: [FEATURE]=()
  • Funkcja zablokowana dla wszystkich elementów origin
  • Przykład: geolocation=()

Różne subdomeny i ścieżki

Różne subdomeny, np. https://your-site.example i https://subdomain.your-site.example, są uznawane za pochodzące z tej samej witryny, ale z różnych źródeł. Dlatego dodanie subdomeny do listy źródeł nie umożliwia dostępu do innej subdomeny tej samej witryny. Każda osadzona subdomena, która ma korzystać z tej funkcji, musi zostać dodana oddzielnie do listy źródeł. Jeśli na przykład dostęp do tematów przeglądania użytkownika jest dozwolony tylko w przypadku tej samej domeny z nagłówkiem Permissions-Policy: browsing-topics=(self), element iframe z innej subdomeny tej samej witryny, https://subdomain.your-site.example, nie będzie miał dostępu do tematów.

Różne ścieżki, np. https://your-site.example i https://your-site.example/embed, są traktowane jako pochodzące z tego samego źródła i nie muszą być wymienione na liście źródeł.

Atrybut allow elementu iframe

W przypadku użycia w innej domenie element iframe musi mieć w tagu atrybut allow, aby uzyskać dostęp do tej funkcji.

Składnia: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

Na przykład:

<iframe src="https://trusted-site.example" allow="geolocation">

Obsługa nawigacji w elementach iframe

Domyślnie, jeśli element iframe przechodzi do innego pochodzenia, zasada nie jest stosowana do pochodzenia, do którego przechodzi element iframe. Jeśli w atrybucie allow podasz źródło, do którego przechodzi element iframe, zasady dotyczące uprawnień zastosowane do pierwotnego elementu iframe zostaną zastosowane do źródła, do którego przechodzi element iframe.

<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">

Możesz zobaczyć, jak to działa, na demonstracji nawigacji w elemencie iframe.

Przykładowe konfiguracje zasad uprawnień

Przykłady tych konfiguracji znajdziesz w wersji demonstracyjnej.

Funkcja jest dozwolona we wszystkich elementach origin

Permissions-Policy: geolocation=*

<iframe src="https://trusted-site.example" allow="geolocation">
<iframe src="https://ad.example" allow="geolocation">

Gdy lista źródeł jest ustawiona na token *, funkcja jest dozwolona w przypadku wszystkich źródeł na stronie, w tym samego źródła i wszystkich elementów iframe. W tym przykładzie wszystkie kody wyświetlane z domeny https://your-site.example oraz kody wyświetlane z elementu iframe https://trusted-site.example i domeny https://ad.example mają dostęp do funkcji geolokalizacji w przeglądarce użytkownika. Pamiętaj, że atrybut allow musi być ustawiony w samym elemencie iframe, a pochodzenie musi być dodane do listy pochodzeń w nagłówku.

Ten rodzaj konfiguracji możesz zobaczyć w wersji demonstracyjnej.

Funkcja dozwolona tylko w przypadku tego samego pochodzenia

Permissions-Policy: geolocation=(self)

Użycie tokena self umożliwia korzystanie z geolokalizacji tylko w przypadku tej samej domeny. Witryny z innych domen nie będą miały dostępu do tej funkcji. W tym przykładzie dostęp do geolokalizacji będzie mieć tylko https://trusted-site.example (self). Użyj tej składni, jeśli chcesz, aby funkcja była dostępna tylko na Twojej stronie.

Ten rodzaj konfiguracji możesz zobaczyć w wersji demonstracyjnej.

Funkcja dozwolona w przypadku tej samej domeny i określonych domen zewnętrznych

Permissions-Policy: geolocation=(self "https://trusted-site.example")

Ta składnia umożliwia korzystanie z geolokalizacji zarówno w przypadku własnych usług (https://your-site.example), jak i usług https://trusted-site.example. Pamiętaj, aby wyraźnie dodać atrybut allow do tagu iframe. Jeśli istnieje inny element iframe z wartością <iframe src="https://ad.example" allow="geolocation">, element https://ad.example nie będzie miał dostępu do funkcji geolokalizacji. Tylko oryginalna strona i https://trusted-site.example, która znajduje się na liście źródeł i ma atrybut allow w tagu iframe, będzie mieć dostęp do funkcji użytkownika.

Ten rodzaj konfiguracji możesz zobaczyć w wersji demonstracyjnej.

Funkcja zablokowana we wszystkich elementach origin

Permissions-Policy: geolocation=()

Jeśli lista źródeł jest pusta, funkcja jest blokowana dla wszystkich źródeł. Ten rodzaj konfiguracji możesz zobaczyć w wersji demonstracyjnej.

Korzystanie z interfejsu JavaScript API

Obecny interfejs JavaScript API zasad dotyczących funkcji jest dostępny jako obiekt w dokumencie lub elemencie (document.featurePolicy or element.featurePolicy). Interfejs JavaScript API zasad dotyczących uprawnień nie został jeszcze wdrożony.

Interfejs Feature Policy API może być używany w przypadku zasad określonych przez interfejs Permissions Policy, ale z pewnymi ograniczeniami. W kwestii implementacji interfejsu JavaScript API pozostały pytania, a propozycja zakłada przeniesienie logiki do interfejsu Permissions API. Jeśli masz jakieś przemyślenia, dołącz do dyskusji.

featurePolicy.allowsFeature(feature)

• Zwraca wartość true, jeśli funkcja jest dozwolona w przypadku domyślnego pochodzenia.
• Działanie jest takie samo w przypadku obu zasad skonfigurowanych przez zasady dotyczące uprawnień i poprzednie zasady dotyczące funkcji.
• Gdy funkcja allowsFeature() jest wywoływana w elemencie iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), zwracana wartość wskazuje, czy w elemencie iframe jest ustawiony atrybut allow.

featurePolicy.allowsFeature(feature, origin)

• Zwraca wartość true, jeśli funkcja jest dozwolona w przypadku określonego pochodzenia.
• Jeśli metoda jest wywoływana w przypadku document, nie informuje już, czy funkcja jest dozwolona w przypadku określonego pochodzenia, jak to miało miejsce w przypadku zasad dotyczących funkcji. Teraz ta metoda informuje, że funkcja może być dozwolona w przypadku danego pochodzenia. Musisz dodatkowo sprawdzić, czy element iframe ma ustawiony atrybut allow. Deweloper musi przeprowadzić dodatkową kontrolę atrybutu allow w elemencie iframe, aby określić, czy funkcja jest dozwolona w przypadku źródła innej firmy.

Sprawdzanie funkcji w ramce iframe za pomocą obiektu element

Możesz użyć funkcji element.allowsFeature(feature), która uwzględnia atrybut allow, w przeciwieństwie do funkcji document.allowsFeature(feature, origin).

const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')

featurePolicy.allowedFeatures()

• Zwraca listę funkcji dozwolonych w przypadku użycia domyślnego pochodzenia.
• Działanie jest takie samo w przypadku obu zasad ustawionych przez zasady dotyczące uprawnień i zasady dotyczące funkcji.
• Jeśli powiązany węzeł jest elementem iframe, atrybut allow jest brany pod uwagę.

featurePolicy.features()

• Zwraca listę funkcji dostępnych w przeglądarce.
• Działanie jest takie samo w przypadku obu zasad ustawionych przez zasady dotyczące uprawnień i zasady dotyczące funkcji.

Integracja z Narzędziami deweloperskimi w Chrome

Sprawdź, jak działają zasady dotyczące uprawnień w narzędziach deweloperskich.

1. Otwórz Narzędzia deweloperskie w Chrome.
2. Otwórz panel Aplikacja, aby sprawdzić dozwolone i niedozwolone funkcje każdej ramki.
3. Na pasku bocznym wybierz ramkę, którą chcesz sprawdzić. Zobaczysz listę funkcji, których może używać wybrana ramka, oraz listę funkcji, które są w niej zablokowane.

Migracja z Feature-Policy

Jeśli używasz nagłówka Feature-Policy, możesz wykonać te czynności, aby przejść na zasady dotyczące uprawnień.

Zastąp nagłówki Feature Policy nagłówkami Permissions Policy

Nagłówki Feature Policy są obsługiwane tylko w przeglądarkach opartych na Chromium, a nagłówki Permissions Policy są obsługiwane od Chrome 88, więc można bezpiecznie zaktualizować istniejące nagłówki za pomocą Permissions Policy.

Feature-Policy:
  autoplay *;
  geolocation 'self';
  camera 'self' 'https://trusted-site.example';
  fullscreen 'none';

Permissions-Policy:
  autoplay=*,
  geolocation=(self),
  camera=(self "https://trusted-site.example"),
  fullscreen=()

Aktualizacja wykorzystania document.allowsFeature(feature, origin)

Jeśli do sprawdzania dozwolonych funkcji w przypadku elementów iframe używasz metody document.allowsFeature(feature, origin), użyj metody allowsFeature(feature) dołączonej do elementu iframe, a nie do elementu document, który go zawiera. Metoda element.allowsFeature(feature) uwzględnia atrybut allow, a metoda document.allowsFeature(feature, origin) nie.

Sprawdzanie dostępu do funkcji u partnera document

Jeśli chcesz nadal używać document jako węzła podstawowego, musisz przeprowadzić dodatkowe sprawdzenie atrybutu allow w tagu iframe.

<iframe id="some-iframe" src="https://example.com" allow="camera"></iframe>

Permissions-Policy: camera=(self "https://example.com")

const isCameraPolicySet = document.featurePolicy.allowsFeature('camera', 'https://example.com')

const someIframeEl = document.getElementById('some-iframe')
const hasCameraAttributeValue = someIframeEl.hasAttribute('allow')
&& someIframeEl.getAttribute('allow').includes('camera')

const isCameraFeatureAllowed = isCameraPolicySet && hasCameraAttributeValue

Zamiast aktualizować istniejący kod za pomocą document, zalecamy wywoływanie allowsFeature() na obiekcie element, tak jak w poprzednim przykładzie.

Interfejs API do raportowania

Interfejs Reporting API zapewnia spójny mechanizm raportowania dla aplikacji internetowych, a interfejs Reporting API do zgłaszania naruszeń zasad dotyczących uprawnień jest dostępny jako funkcja eksperymentalna.

Jeśli chcesz przetestować funkcję eksperymentalną, postępuj zgodnie z instrukcjami i włącz flagę w chrome://flags/#enable-experimental-web-platform-features. Po włączeniu tego ustawienia możesz obserwować naruszenia zasad dotyczących uprawnień w Narzędziach deweloperskich na karcie Aplikacja:

Poniższy przykład pokazuje, jak może wyglądać nagłówek interfejsu Reporting API:

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;

W obecnej implementacji możesz otrzymywać raporty o naruszeniach zasad, które wystąpiły w tym przedziale czasu, konfigurując punkt końcowy o nazwie „default”, jak w poprzednim przykładzie. Podramki będą wymagać własnej konfiguracji raportowania.

Więcej informacji

Więcej informacji o zasadach dotyczących uprawnień znajdziesz w tych materiałach:

• Specyfikacje zasad dotyczących uprawnień
• Wyjaśnienie zasad dotyczących uprawnień
• Lista funkcji kontrolowanych przez zasady.