Zarządzaj dostępem strony i elementów iframe innych firm na Twojej stronie do funkcji przeglądarki.
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'
Wcześniej z zasadami dotyczącymi funkcji.
geolocation=(self "https://example.com"), camera=()
Teraz z zasadami uprawnień.
Łą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.
- Twoja witryna
your-site.examplemoże korzystać z funkcji geolokalizacji za zgodą użytkownika. - Element iframe z tej samej domeny (
your-site.example) może korzystać z tej funkcji bez atrybutuallow. - 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. - 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 atrybutallow. - Międzyźródłowy element iframe (
trusted-site.example) dodany do listy źródeł bez atrybutuallownie może używać tej funkcji. - 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ę atrybutallow.
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") selfto skrót odhttps://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 atrybutallow. Programista musi dodatkowo sprawdzić atrybutalloww 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.
- Otwórz Narzędzia deweloperskie w Chrome.
- Otwórz panel Aplikacja, aby sprawdzić dozwolone funkcje i niedozwolone funkcje każdej ramki.
- 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';
Wcześniej z zasadami dotyczącymi funkcji.
Permissions-Policy: autoplay=*, geolocation=(self), camera=(self "https://trusted-site.example"), fullscreen=()
Teraz z zasadami uprawnień.
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: