Kontrolowanie funkcji przeglądarki za pomocą zasad uprawnień

Zarządzaj tym, jak Twoja strona i ramki iframe innych firm na niej mają dostęp do funkcji przeglądarki.

Kevin K. Lee
Kevin K. Lee
X GitHub

Zasady dotyczące uprawnień (wcześniej znane jako zasady dotyczące funkcji) umożliwiają deweloperowi kontrolowanie funkcji przeglądarki dostępnych dla strony, jej ramek iframe i podzasobów przez oświadczenie 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ć te same źródła lub domeny z innych domen oraz pozwala deweloperowi kontrolować dostęp własnych i innych firm do funkcji przeglądarki.

Użytkownik ma ostateczne prawo do zezwolenia na dostęp do bardziej zaawansowanych funkcji i musi wyrazić wyraźną zgodę, klikając przycisk.

Zasady dotyczące uprawnień umożliwiają witrynie najwyższego poziomu określenie, z czego ona i jej partnerzy zewnętrzni zamierzają korzystać. Pozwala to użytkownikowi uniknąć konieczności sprawdzania, czy żądanie dostępu do funkcji jest uzasadnione. Na przykład dzięki użyciu zasad dotyczących uprawnień do zablokowania funkcji lokalizowania geograficznego dla wszystkich innych firm deweloper może mieć pewność, że żadna inna firma nie uzyska dostępu do lokalizacji użytkownika.

Zmiany w zasadach dotyczących uprawnień

Zasady dotyczące uprawnień były wcześniej znane jako Zasady dotyczące funkcji. Kluczowe koncepcje pozostają takie same, ale wraz z nazwą wprowadzono kilka ważnych zmian.

Wykorzystanie uporządkowanych pól

Pola uporządkowane zapewniają zestaw typowych struktur danych, które umożliwiają standaryzację analizowania i serializacji wartości pól nagłówka HTTP. Więcej informacji o polach strukturalnych znajdziesz w poście na blogu Fastly pt. Poprawiamy HTTP za pomocą pól nagłówka strukturalnego.

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

Przed zasadami dotyczącymi funkcji

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

Teraz z zasadami dotyczącymi uprawnień.

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

Za pomocą zasad dotyczących funkcji możesz dodać funkcję do ramki między domenami, dodając domenę do listy źródeł nagłówka lub dodając atrybut allow do tagu iframe. Jeśli w ramach zasad dotyczących uprawnień dodasz do listy źródeł ramkę między domenami, tag iframe dla tego źródła musi zawierać atrybut allow. Jeśli odpowiedź nie zawiera nagłówka zasad dotyczących uprawnień, przyjmuje 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 wyraźnie ustawiali nagłówek Permissions Policy w odpowiedzi, tak aby interfejsy iframe w innych domenach, które nie są wymienione na liście źródeł, nie miały dostępu do tej funkcji, nawet jeśli jest obecny nagłówek allow.

Po Chrome 88 nadal można używać zasad dotyczących funkcji, ale działają one jako alias zasad dotyczących uprawnień. Poza składnią nie ma różnic 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, omówimy typowy scenariusz, w którym jesteś właścicielem witryny i chcesz kontrolować, jak Twoja witryna i kod zewnętrzny korzystają z funkcji przeglądarki.

  • Twoja witryna to https://your-site.example.
  • Twoja witryna zawiera element iframe z tego samego źródła (https://your-site.example).
  • Twoja witryna zawiera element iframe z usługi https://trusted-site.example, do którego masz zaufanie.
  • Twoja witryna wyświetla też reklamy obsługiwane przez https://ad.example.
  • Chcesz zezwolić na geolokalizację tylko w swojej witrynie i w zaufanej witrynie, a nie w reklamie.

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">

Szybki przegląd zasad dotyczących uprawnień.

W tym przykładzie lista źródeł nagłówka zezwala na korzystanie z funkcji geolokalizacji tylko Twojej witrynie (self) i trusted-site.example. Aplikacja 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 w ramach tego samego źródła (your-site.example) może korzystać z funkcji bez użycia 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 z różnych źródeł.
  4. Tag iframe (trusted-site.example) w wielu domenach, który został dodany do listy domen i ma ustawiony atrybut allow w tagu iframe, może korzystać z tej funkcji.
  5. Element iframe (trusted-site.example) z wielu źródeł dodany do listy źródeł bez atrybutu allow nie może korzystać z tej funkcji.
  6. Tag iframe (ad.example) z wielu źródeł, który nie został dodany do listy źródeł, nie może korzystać z tej funkcji, nawet jeśli zawiera atrybut allow.

Nagłówek odpowiedzi HTTP Permissions-Policy

Użytkownik wysyła żądanie, serwer odpowiada nagłówkiem polityki uprawnień, a przeglądarka przyznaje dostęp na podstawie tego nagłówka.

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

Użyj nagłówka Permissions-Policy w odpowiedzi z serwera, aby ustawić dozwolone pochodzenie dla funkcji. Wartość nagłówka może zawierać kombinację tokenów i ciągów tekstowych z różnych źródeł. Dostępne tokeny to * dla wszystkich źródeł i self dla źródeł tego samego pochodzenia.

Jeśli nagłówek dotyczy wielu funkcji, rozdziel je przecinkami. Jeśli podajesz kilka punktów początkowych, oddziel je spacją na każdym z nich. W przypadku nagłówków podających źródło będące żądaniem z innej domeny tag iframe musi zawierać atrybut allow.

Oto przykładowe pary klucz-wartość:

  • Składnia: [FEATURE]=*
    • Zasady zastosowane do wszystkich elementów origin
    • Przykład: geolocation=*
  • Składnia: [FEATURE]=(self)
    • Zasada zastosowana w przypadku domen o tej samej domenie
    • Przykład: geolocation=(self)
  • Składnia: [FEATURE]=(self [ORIGIN(s)])
    • Zasady zastosowane do tego samego źródła i wybranych ź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)])
    • Zasady zastosowane do tego samego źródła i wybranych źródeł
    • Przykład: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
    • W tym przypadku jedno z źródeł powinno być źródłem kodu embedowania. Jeśli stronie, na której znajduje się kod, nie zostaną przyznane uprawnienia, iframe wbudowane na tej stronie również zostaną zablokowane, mimo że zostały dodane do listy źródeł, ponieważ zasady dotyczące uprawnień delegują uprawnienia. Możesz też użyć tokena self.
  • Składnia: [FEATURE]=()
    • Funkcja jest 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 w tej samej witrynie, ale w różnych domenach. Dlatego dodanie subdomeny do listy źródeł nie umożliwia uzyskania dostępu do innej subdomeny tej samej witryny. Każda wbudowana subdomena, która ma korzystać z tej funkcji, musi być dodana osobno do listy źródeł. Jeśli na przykład dostęp do tematów przeglądania użytkownika jest dozwolony tylko dla witryn z tym samym pochodzeniem, które mają nagłówek 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 tych tematów.

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

Atrybut iframe allow

Konfiguracja elementu iframe

Aby można było korzystać z ramki iframe w różnych domenach, musi ona zawierać atrybut allow, który umożliwia 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

Konfigurowanie nawigacji w elementach iframe

Domyślnie, jeśli element iframe przekierowuje do innego pochodzenia, zasada nie jest stosowana do tego pochodzenia. Jeśli w atrybucie allow podasz źródło, do którego przekierowuje iframe, zasada dotycząca uprawnień zastosowana do pierwotnego elementu iframe zostanie zastosowana do źródła, do którego przekierowuje iframe.

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

Aby zobaczyć, jak to działa, otwórz prezentację nawigacji w elementach iframe.

Przykładowe konfiguracje zasad dotyczących uprawnień

Przykłady tych konfiguracji znajdziesz w prezentacji demonstracyjnej.

Funkcja dozwolona we wszystkich elementach origin

Architektura wszystkich elementów origin, które mają dostęp do funkcji

Permissions-Policy: geolocation=*

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

Gdy lista źródeł jest skonfigurowana na token *, funkcja jest dozwolona dla wszystkich źródeł obecnych na stronie, w tym dla niej samej i wszystkich ramek iframe. W tym przykładzie cały kod przesyłany z poziomu https://your-site.example oraz kody przesyłane z iframe https://trusted-site.example i https://ad.example mają dostęp do funkcji geolokalizacji w przeglądarce użytkownika. Pamiętaj, że atrybut allow musi być ustawiony również w samym iframe, a źródło musi zostać dodane do listy źródeł nagłówka.

Takie ustawienie możesz zobaczyć w demo.

Funkcja dozwolona tylko w ramach tego samego źródła

Architektura tylko z tym samym źródłem mających dostęp do funkcji

Permissions-Policy: geolocation=(self)

Korzystanie z tokena self pozwala na korzystanie z geolokalizacji tylko w ramach tego samego źródła. 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, aby funkcja była dostępna tylko na Twojej stronie.

Takie ustawienie możesz zobaczyć w demo.

Funkcja dozwolona w tym samym źródle i w określonych domenach zewnętrznych

Architektura określonych źródeł mających dostęp do funkcji

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

Ta składnia umożliwia korzystanie z geolokalizacji zarówno w przypadku self (https://your-site.example), jak i https://trusted-site.example. Pamiętaj, aby wyraźnie dodać atrybut allow do tagu iframe. Jeśli jest 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. Dostęp do funkcji użytkownika będzie mieć tylko oryginalna strona i https://trusted-site.example, która znajduje się na liście źródeł i ma atrybut allow w tagu iframe.

Takie ustawienie możesz zobaczyć w demo.

Funkcja jest zablokowana we wszystkich elementach origin

Architektura wszystkich źródeł, które mają zablokowany dostęp do funkcji

Permissions-Policy: geolocation=()

Jeśli lista źródeł jest pusta, funkcja jest blokowana dla wszystkich źródeł. Takie ustawienie możesz zobaczyć w demo.

Korzystanie z interfejsu JavaScript API

Dotychczasowy interfejs JavaScript API zasad dotyczących funkcji jest obiektem w dokumencie lub elemencie (document.featurePolicy or element.featurePolicy). Interfejs JavaScript API zasad dotyczących uprawnień nie został jeszcze zaimplementowany.

Interfejs API zasad funkcji może być używany do zasad ustawianych przez zasady dotyczące uprawnień, ale z pewnymi ograniczeniami. Wciąż pojawiają się pytania dotyczące implementacji interfejsu JavaScript API. W związku z tym zaproponowano 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 dla domyślnego pochodzenia.
  • Zasady określone przez zasady dotyczące uprawnień i poprzednie zasady dotyczące funkcji działają tak samo.
  • Gdy funkcja allowsFeature() jest wywoływana w elemencie iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), zwrócona wartość informuje, czy w elemencie iframe jest ustawiony atrybut allow.

featurePolicy.allowsFeature(feature, origin)

  • 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 dodatkowo sprawdzić, czy iframe ma ustawiony atrybut allow. Aby określić, czy funkcja jest dozwolona dla źródła zewnętrznego, deweloper musi przeprowadzić dodatkową weryfikację atrybutu allow w elemencie iframe.

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 tego nie robi.

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

featurePolicy.allowedFeatures()

  • Zwraca listę funkcji dozwolonych do użycia w przypadku domyślnego pochodzenia.
  • Działa to tak samo w przypadku zasad określonych przez zasadę dotyczącą uprawnień i zasadę dotyczącą funkcji.
  • Gdy powiązany węzeł jest iframe, uwzględniany jest atrybut allow.

featurePolicy.features()

  • Zwraca listę funkcji dostępnych w przeglądarce.
  • Zasady ustawione przez zasady dotyczące uprawnień i zasady dotyczące funkcji działają w taki sam sposób.

Integracja z Narzędziami deweloperskimi w Chrome

Integracja narzędzi deweloperskich w Chrome z zasadami dotyczącymi uprawnień

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

  1. Otwórz Narzędzia deweloperskie w Chrome.
  2. Otwórz panel Aplikacja, aby sprawdzić dozwolone i niedozwolone funkcje poszczególnych ramek.
  3. Na pasku bocznym wybierz kadr, który chcesz sprawdzić. Zobaczysz listę funkcji, których może używać wybrany ramka, oraz listę funkcji, które są w niej zablokowane.

Migracja z zasady funkcji

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

Zastępowanie nagłówków zasad dotyczących funkcji nagłówkami zasad dotyczących uprawnień

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 Chrome 88, dlatego można bezpiecznie zaktualizować istniejące nagłówki, używając nagłówków zasad dotyczących uprawnień.

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

Przed zasadami dotyczącymi funkcji

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

Teraz z zasadami dotyczącymi uprawnień.

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

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

Sprawdzanie dostępu do funkcji w usłudze document

Aby nadal używać elementu document jako węzła podstawowego, musisz przeprowadzić dodatkową kontrolę 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ą funkcji document, zalecamy wywołanie funkcji allowsFeature() na obiekcie element, 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ć funkcję eksperymentalną, postępuj zgodnie z przewodnikiem i włącz flagę w sekcji chrome://flags/#enable-experimental-web-platform-features. Po włączeniu flagi możesz sprawdzać naruszenia zasad dotyczących uprawnień w DevTools na karcie Aplikacja:

Przykładowy 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 ramach obecnej implementacji możesz otrzymywać raporty o naruszeniu zasad dotyczące wszystkich naruszeń występujących w danym okresie, konfigurując punkt końcowy o nazwie „default” (domyślny) tak jak w poprzednim przykładzie. Ramki podrzędne będą wymagać własnej konfiguracji raportowania.

Więcej informacji

Aby lepiej zrozumieć zasady dotyczące uprawnień, zapoznaj się z tymi materiałami: