Kontrolowanie funkcji przeglądarki za pomocą zasad dotyczących uprawnień

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

Kevin K. Lee

Zasady dotyczące uprawnień (znane wcześniej jako Zasady dotyczące funkcji) pozwalają deweloperowi na: kontrolować funkcje przeglądarki dostępne dla strony i jej elementy iframe; zasobów 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ł nagłówka odpowiedzi. Lista źródeł może zawierać te same domeny lub zasoby z innych domen deweloper może kontrolować dostęp aplikacji i usług innych firm do funkcji przeglądarki.

To użytkownik podejmuje ostateczną decyzję, jeśli zezwoli na dostęp do bardziej zaawansowanych funkcji, dlatego musi udzielić wyraźnej zgody za pomocą odpowiedniego promptu.

Zasada dotycząca uprawnień pozwala witrynie najwyższego poziomu na definiowanie tego, stron zamierzających z nich korzystać, i zdejmuje z użytkownika ciężar decydowania czy prośba o dostęp do funkcji jest uzasadniona. Na przykład: zablokowanie funkcji geolokalizacji dla wszystkich osób trzecich za pomocą zasad uprawnień; deweloper może mieć pewność, że żadna inna firma nie uzyska dostępu do geolokalizację.

Zmiany w zasadach dotyczących uprawnień

Zasada uprawnień była wcześniej znana jako zasada funkcji. Najważniejsze pojęcia się nie zmieniają, ale oprócz nazwy wprowadziliśmy kilka ważnych zmian.

Wykorzystanie uporządkowanych pól

Uporządkowane pola zapewniają zestaw wspólnych struktur danych, które pozwalają ustandaryzować analizę i serializację wartości pól nagłówka HTTP. Więcej informacji o ustrukturyzowanych polach znajdziesz w poście na blogu Fastly „Ulepszanie HTTP za pomocą uporządkowanych pól nagłówka”.

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

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

Łączenie nagłówków za pomocą atrybutu iframe allow

Dzięki zasadzie funkcji możesz dodać funkcję do ramki z innej domeny, dodając źródło do listy źródeł nagłówka lub dodając atrybut allow do tagu iframe. Zgodnie z zasadami dotyczącymi uprawnień, jeśli do listy źródeł dodasz ramkę z innej domeny, tag iframe tego źródła musi zawierać atrybut allow. Jeśli odpowiedź nie zawiera nagłówka Permissions Policy, uznaje się, że lista źródeł ma wartość domyślną *. Dodanie atrybutu allow do elementu iframe umożliwia dostęp do tej funkcji.

Dlatego zalecamy, aby deweloperzy w odpowiedzi ustawiali w odpowiedzi nagłówek Permissions Policy, tak aby elementy iframe z innych domen, których nie ma na liście źródeł, nie miały dostępu do tej funkcji, nawet jeśli obecne jest allow.

Zasady funkcji nadal mogą być używane po Chrome 88, ale działają jako alias zasad uprawnień. Poza składnią nie ma różnicy w logice. Jeśli używane są jednocześnie nagłówki Zasady dotyczące uprawnień i Zasady dotyczące funkcji, nagłówek Permissions-Policy będzie miał wyższy priorytet i zastąpi 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ć sposób, w jaki witryna i kody innych firm korzystają z funkcji przeglądarki.

• Twoja witryna to https://your-site.example.
• Twoja witryna umieszcza element iframe z tej samej domeny (https://your-site.example).
• Twoja witryna umieszcza element iframe z usługi https://trusted-site.example, do którego masz zaufanie.
• W Twojej witrynie są też wyświetlane reklamy wyświetlane przez https://ad.example.
• Chcesz zezwolić na geolokalizację tylko w przypadku swojej witryny i zaufanej witryny, a nie reklamy.

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

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

Ustaw atrybut allow bezpośrednio na tag iframe dla zaufanej witryny:

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

W tym przykładzie lista źródeł nagłówka zezwala tylko Twojej witrynie (self) i trusted-site.example na korzystanie z funkcji geolokalizacji. 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. Element iframe z tej samej domeny (your-site.example) może korzystać z tej funkcji bez atrybutu allow.
3. Element iframe wyświetlany z innej subdomeny (subdomain.your-site-example), który nie został dodany do listy źródeł, a ma w tagu iframe atrybut allow, uniemożliwia korzystanie z tej funkcji. Różne subdomeny są uznawane za tę samą witrynę, ale pochodzące z innej domeny.
4. Z tej funkcji może korzystać element iframe z innego źródła (trusted-site.example), który został dodany do listy źródeł i ma w tagu iframe ustawiony atrybut allow.
5. Międzyźródłowy element iframe (trusted-site.example) dodany do listy źródeł bez atrybutu allow nie może używać tej funkcji.
6. Element iframe z innego źródła (ad.example), który nie został dodany do listy źródeł, uniemożliwia korzystanie z tej funkcji, nawet jeśli w tagu iframe znajduje się atrybut allow.

Nagłówek odpowiedzi HTTP Permissions-Policy

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

Użyj nagłówka Permissions-Policy w odpowiedzi z serwera, aby ustawić dozwolone źródła cechy. Wartość nagłówka może składać się z kombinacji tokenów i ciągów znaków źródłowych. Dostępne tokeny to * dla wszystkich źródeł i self dla tej samej domeny.

Jeśli nagłówek dotyczy wielu cech, rozdziel je przecinkami. Jeśli podajesz kilka punktów początkowych, oddziel je spacją na każdym z nich. W przypadku nagłówków zawierających ź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]=*
  • Zasada zastosowana do wszystkich źródeł
  • Przykład: geolocation=*
• Składnia: [FEATURE]=(self)
  • Zasada zastosowana do tej samej domeny
  • Przykład: geolocation=(self)
• Składnia: [FEATURE]=(self [ORIGIN(s)])
  • Zasada zastosowana do tego samego i określonych źródeł
  • Przykład: geolocation=(self "https://a.example" "https://b.example")
  • self to skrót od https://your-site.example
• Składnia: [FEATURE]=([ORIGIN(s)])
  • Zasada zastosowana do tego samego i określonych źródeł
  • Przykład: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • W przypadku tej składni jednym ze źródeł powinno być źródło elementu osadzającego. Jeśli nie przyznano uprawnień stronie umieszczonej na stronie, umieszczone na niej elementy iframe również zostaną zablokowane, mimo że zostaną dodane do listy źródeł, ponieważ zasady uprawnień przekazują uprawnienia. Możesz też użyć tokena self.
• Składnia: [FEATURE]=()
  • Funkcja zablokowana dla wszystkich źródeł
  • 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 tę samą witrynę, ale pochodzące z innej domeny. Dlatego dodanie subdomeny na liście źródeł nie zezwala na dostęp do innej subdomeny tej samej witryny. Każdą umieszczoną subdomenę, która chce używać tej funkcji, trzeba dodać do listy źródeł oddzielnie. Jeśli na przykład dostęp do tematów przeglądania przeglądanych przez użytkownika jest dozwolony tylko z tej samej domeny za pomocą nagłówka 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ą uznawane za te same i nie muszą być wymienione na liście źródeł.

Atrybut iframe allow

W przypadku korzystania z innych domen element iframe wymaga w tagu atrybutu 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 iframe

Jeśli element iframe przejdzie do innego źródła, zasada nie jest domyślnie stosowana do źródła, do którego przechodzi element iframe. Jeśli podasz w atrybucie allow źródło, do którego przechodzi element iframe, zasada uprawnień zastosowana do pierwotnego elementu iframe zostanie zastosowana 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">

Aby zobaczyć, jak to działa, odwiedź prezentację nawigacji iframe.

Przykładowe konfiguracje zasad uprawnień

Przykłady poniższych konfiguracji znajdziesz w prezentacji.

Funkcja dozwolona we wszystkich źródłach

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ł obecnych na stronie, w tym samego siebie i wszystkich elementów iframe. W tym przykładzie cały kod pochodzący z adresu https://your-site.example oraz kody wyświetlone z elementów iframe https://trusted-site.example i https://ad.example mają dostęp do funkcji geolokalizacji w przeglądarce użytkownika. Pamiętaj, że oprócz dodania źródła do listy źródeł nagłówka musisz też ustawić atrybut allow w samym elemencie iframe.

Tę konfigurację można zobaczyć w wersji demonstracyjnej.

Funkcja dozwolona tylko w tej samej domenie

Permissions-Policy: geolocation=(self)

Token self umożliwia korzystanie z geolokalizacji tylko z tej samej domeny. Użytkownicy z innych domen nie będą mieli dostępu do tej funkcji. W tym przykładzie tylko https://trusted-site.example (self) będzie mieć dostęp do geolokalizacji. Użyj tej składni, jeśli chcesz stosować tę funkcję tylko na swojej stronie, a nie na innych stronach.

Tę konfigurację można zobaczyć w wersji demonstracyjnej.

Funkcja dozwolona w przypadku tej samej domeny i określonych domen z innych domen

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

Ta składnia umożliwia korzystanie z geolokalizacji zarówno do mnie (https://your-site.example), jak i https://trusted-site.example. Pamiętaj, aby wprost dodać atrybut allow do tagu iframe. Jeśli istnieje inny element iframe z atrybutem <iframe src="https://ad.example" allow="geolocation">, element https://ad.example nie będzie miał dostępu do funkcji geolokalizacji. Do funkcji użytkownika będą miały dostęp tylko strona oryginalna i tag https://trusted-site.example na liście źródeł, które mają atrybut allow w tagu iframe.

Tę konfigurację można zobaczyć w wersji demonstracyjnej.

Funkcja zablokowana we wszystkich źródłach

Permissions-Policy: geolocation=()

Jeśli lista źródeł jest pusta, funkcja jest zablokowana we wszystkich źródłach. Tę konfigurację można zobaczyć w wersji demonstracyjnej.

Użycie interfejsu JavaScript API

Istniejący interfejs JavaScript API zasad dotyczących funkcji znajduje się jako obiekt w dokumencie lub elemencie (document.featurePolicy or element.featurePolicy). Zasady dotyczące uprawnień w interfejsie JavaScript API nie zostały jeszcze wdrożone.

Interfejsu Feature Policy API można używać z zasadami ustalanymi w ramach zasad uprawnień, ale z pewnymi ograniczeniami. Pozostają jeszcze pytania dotyczące implementacji interfejsu JavaScript API i przygotowano propozycję przeniesienia logiki do Permissions API. Jeśli masz jakieś uwagi, dołącz do dyskusji.

featurePolicy.allowsFeature(feature)

• Zwraca wartość true, jeśli funkcja jest dozwolona w przypadku domyślnego użycia źródła.
• Działanie jest takie samo zarówno w przypadku zasad określonych przez zasadę dotyczącą uprawnień, jak i poprzednią zasadę funkcji
• Gdy funkcja allowsFeature() jest wywoływana w elemencie iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), zwrócona wartość określa, czy atrybut allow jest ustawiony w elemencie iframe.

featuresPolicy.allowsFeature(funkcja; źródło)

• Zwraca wartość true, jeśli funkcja jest dozwolona dla określonego punktu początkowego.
• Jeśli ta metoda jest wywoływana document, nie wskazuje już, czy funkcja jest dozwolona dla określonego źródła, tak jak zrobiła to zasada dotycząca funkcji. Teraz ta metoda informuje, że możliwe jest, aby funkcja mogła trafiać do tego punktu początkowego. Musisz jeszcze raz sprawdzić, czy element iframe ma ustawiony atrybut allow. Programista musi dodatkowo sprawdzić atrybut allow w elemencie iframe, by określić, czy ta funkcja jest dozwolona w przypadku źródła zewnętrznego.

Sprawdzanie funkcji w elemencie iframe z obiektem element

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

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

featurePolicy.allowedFeatures()

• Zwraca listę funkcji dozwolonych w przypadku użycia źródła domyślnego.
• Działa to tak samo w przypadku zasad określonych przez zasadę dotyczącą uprawnień i zasadę dotyczącą funkcji.
• Jeśli powiązany węzeł jest elementem iframe, brany jest pod uwagę atrybut allow.

featurePolicy.features()

• Zwraca listę funkcji dostępnych w przeglądarce.
• Działa to tak samo w przypadku zasad określonych przez zasadę dotyczącą uprawnień i zasadę dotyczącą funkcji.

Integracja z Narzędziami deweloperskimi w Chrome

Zobacz, jak działa zasada uprawnień w Narzędziach deweloperskich.

1. Otwórz Narzędzia deweloperskie w Chrome.
2. Otwórz panel Aplikacja, aby sprawdzić dozwolone funkcje i niedozwolone funkcje każdej ramki.
3. Na pasku bocznym wybierz ramkę, którą chcesz sprawdzić. Pojawi się lista funkcji, z których może korzystać wybrana ramka, a także lista funkcji zablokowanych w tej ramce.

Migracja z zasady funkcji

Jeśli obecnie używasz nagłówka Feature-Policy, możesz wykonać opisane poniżej czynności, aby przejść na zasady uprawnień.

Zastąp nagłówki zasad dotyczących funkcji nagłówkami zasad uprawnień

Ponieważ nagłówki zasad dotyczących funkcji są obsługiwane tylko w przeglądarkach opartych na Chromium, a nagłówki zasad dotyczących uprawnień są obsługiwane od wersji Chrome 88, można bezpiecznie zaktualizować istniejące nagłówki za pomocą zasad dotyczących uprawnień.

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=()

Zaktualizuj użycie usługi document.allowsFeature(feature, origin)

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

Sprawdzam dostęp do funkcji na koncie document

Aby nadal używać document jako węzła podstawowego, musisz dodatkowo sprawdzić atrybut 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ą metody document, zalecamy wywołanie metody allowsFeature() w obiekcie element, tak jak w poprzednim przykładzie.

Interfejs API do raportowania

Interfejs API do raportowania zapewnia mechanizm raportowania dotyczącego aplikacji internetowych w spójny sposób. Interfejs Reporting API dotyczący naruszeń zasad dotyczących uprawnień jest dostępny jako funkcja eksperymentalna.

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

Poniższy przykład pokazuje, jak można utworzyć 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 dotyczących wszystkich naruszeń zasad w danej ramce – konfigurując punkt końcowy o nazwie „default” (domyślny). jak w przykładzie powyżej. Ramki podrzędne będą wymagać własnej konfiguracji raportowania.

Więcej informacji

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

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