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

Zarządzaj dostępem strony i zewnętrznych elementów iframe do funkcji przeglądarki.

Kevin K. Lee

Zasada uprawnień, wcześniej znana jako zasada funkcji, umożliwia deweloperowi kontrolowanie funkcji przeglądarki dostępnych dla strony, jej elementów iframe oraz zasobów podrzędnych przez zadeklarowanie zestawu zasad, które przeglądarka będzie egzekwować. Te zasady są stosowane do źródeł podanych na liście źródeł nagłówków odpowiedzi. Lista źródeł może zawierać źródła z tej samej domeny lub z innych domen. Pozwala deweloperowi kontrolować dostęp aplikacji własnych i zewnętrznych do funkcji przeglądarki.

To użytkownik podejmuje ostateczną decyzję o przyznaniu dostępu do bardziej zaawansowanych funkcji i musi udzielić wyraźnego pozwolenia w odpowiedzi na prośbę.

Zasady dotyczące uprawnień pozwalają decydować, z czego chce korzystać witryna najwyższego poziomu, a także z jakich osób trzecich mają korzystać. Dzięki temu użytkownik nie musi już określać, czy prośba o dostęp do funkcji jest uzasadniona. Na przykład blokując funkcję geolokalizacji wszystkim osobom trzecim za pomocą zasad dotyczących uprawnień, deweloper może mieć pewność, że żadna inna firma nie uzyska dostępu do geolokalizacji użytkownika.

Zmiany w zasadach dotyczących uprawnień

Zasada uprawnień była wcześniej znana jako zasada funkcji. Główne pojęcia są takie same, ale oprócz nazwy zaszły istotne zmiany.

Wykorzystanie pól uporządkowanych danych

Pola strukturalne zapewniają zestaw typowych struktur danych do standaryzacji analizowania i serializacji wartości pól nagłówka HTTP. Więcej informacji o polach uporządkowanych danych znajdziesz w poście na blogu Fastly „Ulepszanie protokołu HTTP z użyciem uporządkowanych pól nagłówka”.

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

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

Połącz nagłówki z atrybutem allow elementu iframe

Dzięki zasadzie funkcji możesz dodać funkcję do ramki z innych domen, dodając źródło do listy źródeł nagłówka lub dodając atrybut allow do tagu iframe. Jeśli w ramach zasady uprawnień dodasz do listy źródeł ramkę z innych domen, tag iframe tego źródła musi zawierać atrybut allow. Jeśli odpowiedź nie zawiera nagłówka Zasady uprawnień, 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 deweloperom jawne ustawienie w odpowiedzi nagłówka zasad uprawnień. Dzięki temu elementy iframe z innych domen, których nie ma na liście źródeł, nie będą miały dostępu do tej funkcji, nawet jeśli występuje zasada allow.

Zasad funkcji nadal można używać po Chrome 88, ale jako alias zasad uprawnień. Poza składnią nie ma różnic w logice. Jeśli używasz jednocześnie nagłówków zasad dotyczących uprawnień i zasad funkcji, nagłówek Permissions-Policy będzie miał wyższy priorytet i zastąpi wartość podaną w nagłówku Feature-Policy.

Jak używać zasad dotyczących uprawnień?

Krótkie omówienie

Zanim przejdziemy do szczegółów, przyjrzyjmy się typowi, w którym jesteś właścicielem witryny i chcesz kontrolować sposób, w jaki 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).
• Twoja witryna zawiera zaufany element iframe z https://trusted-site.example.
• Twoja witryna wyświetla także reklamy wyświetlane przez https://ad.example.
• Chcesz zezwolić na geolokalizację tylko swojej witrynie i zaufanej witrynie – nie dla reklamy.

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

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

Ustaw atrybut allow dla tagu iframe zaufanej witryny:

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

W tym przykładzie lista źródeł nagłówka pozwala na korzystanie z funkcji geolokalizacji tylko Twojej witrynie (self) i witrynie trusted-site.example. Witryna 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 tego samego źródła (your-site.example) może używać 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ł i ma w tagu iframe ustawiony atrybut allow, jest zablokowany i nie może korzystać z tej funkcji. Różne subdomeny są uznawane za tę samą witrynę, ale z innych domen.
4. Z tej funkcji może korzystać element iframe z innych domen (trusted-site.example), który został dodany do listy źródeł i ma ustawiony atrybut allow w tagu iframe.
5. Z tej funkcji nie można korzystać w elemencie iframe z innych domen (trusted-site.example) dodanym do listy źródeł bez atrybutu allow.
6. Element iframe z innych domen (ad.example), który nie został dodany do listy źródeł, jest zablokowany, nawet jeśli atrybut allow jest zawarty w tagu iframe.

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 przyjmować kombinację tokenów i ciągów znaków źródła. Dostępne tokeny mają wartość * dla wszystkich źródeł i self dla tego samego pochodzenia.

Jeśli nagłówek dotyczy wielu obiektów, rozdziel je przecinkami. Jeśli podasz wiele źródeł, oddziel je spacją. W przypadku nagłówków, których źródło jest żądaniem z innych domen, tag iframe musi zawierać atrybut allow.

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

• Składnia: [FEATURE]=*
  • Zasada została 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 źródła i określonych źródeł
  • Przykład: geolocation=(self "https://a.example" "https://b.example")
  • self to skrót dla wyrażenia https://your-site.example
• Składnia: [FEATURE]=([ORIGIN(s)])
  • Zasada zastosowana do tego samego źródła i określonych źródeł
  • Przykład: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Jeśli używasz tej składni, jednym ze źródeł powinno być źródło elementu do umieszczania. Jeśli strona umieszczonego na stronie nie otrzyma tych uprawnień, umieszczone na niej elementy iframe również będą zablokowane, mimo że zostaną dodane do listy źródeł, ponieważ zasada uprawnień przekazuje uprawnienia. Możesz też użyć tokena self.
• Składnia: [FEATURE]=()
  • Funkcja zablokowana we wszystkich źródłach
  • Przykład: geolocation=()

Różne subdomeny i ścieżki

Różne subdomeny, takie jak https://your-site.example i https://subdomain.your-site.example, są uznawane za tę samą witrynę, ale z innej domeny. Dlatego dodanie subdomeny na liście źródeł nie pozwala na dostęp do innej subdomeny w tej samej witrynie. Każda umieszczona subdomena, która chce korzystać z tej funkcji, musi zostać dodana do listy źródeł oddzielnie. Jeśli na przykład użytkownik przegląda tematy przeglądane przez użytkownika ma dostęp do tej samej domeny tylko 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ą uznawane za tę samą pochodzenie i nie muszą znajdować się na liście źródeł.

Atrybut elementu iframe allow

W przypadku użycia z innych domen element iframe wymaga atrybutu allow w tagu, aby mieć 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 źródła, zasada nie jest stosowana do źródła, do którego przechodzi element iframe. Jeśli w atrybucie allow podasz źródło, do którego przechodzi element iframe, zasada uprawnień, która została 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">

Możesz zobaczyć, jak to działa, w prezentacji nawigacji iframe.

Przykładowe konfiguracje zasad uprawnień

Przykłady tych konfiguracji można znaleźć 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">

Jeśli lista źródeł jest ustawiona na token *, funkcja jest dozwolona w przypadku wszystkich źródeł występujących na stronie, w tym siebie samego i wszystkich elementów iframe. W tym przykładzie cały kod z https://your-site.example oraz kody 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 atrybut allow należy ustawić również w elemencie iframe wraz z dodaniem źródła do listy źródeł nagłówka.

Tę konfigurację można zobaczyć w prezentacji.

Funkcja dozwolona tylko w tej samej domenie

Permissions-Policy: geolocation=(self)

Token self umożliwia geolokalizację tylko w przypadku tego samego źródła. Źródła z innych domen nie będą miały dostępu do tej funkcji. W tym przykładzie tylko użytkownik https://trusted-site.example (self) będzie miał dostęp do geolokalizacji. Zastosuj tę składnię, jeśli chcesz, aby ta funkcja była dostępna tylko na Twojej stronie.

Tę konfigurację można zobaczyć w prezentacji.

Funkcja dozwolona w tej samej domenie i w konkretnych domenach z innych domen

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

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

Tę konfigurację można zobaczyć w prezentacji.

Funkcja zablokowana we wszystkich źródłach

Permissions-Policy: geolocation=()

W przypadku pustej listy źródeł funkcja jest blokowana we wszystkich źródłach. Tę konfigurację można zobaczyć w prezentacji.

Użyj interfejsu JavaScript API

Istniejący interfejs JavaScript API zasad dotyczących funkcji znajduje się jako obiekt w dokumencie lub w elemencie (document.featurePolicy or element.featurePolicy). Zasada JavaScript API for Permissions nie została jeszcze zaimplementowana.

Za pomocą interfejsu Feature Policy API można używać zasad określonych przez zasadę uprawnień (z pewnymi ograniczeniami). Pozostały pytania dotyczące implementacji interfejsu JavaScript API oraz opracowano propozycję przeniesienia tej logiki do interfejsu Permissions API. Jeśli masz jakieś pomysły, dołącz do dyskusji.

featurePolicy.allowsFeature(feature)

• Zwraca wartość true, jeśli funkcja jest dozwolona w przypadku użycia domyślnego źródła.
• Działanie jest takie samo w przypadku obu zasad ustawionych przez zasadę uprawnień i poprzedniej zasady funkcji
• Po wywołaniu metody allowsFeature() w elemencie iframe (iframeEl.featurePolicy.allowsFeature('geolocation')) zwracana wartość pokazuje, czy w elemencie iframe ustawiono atrybut allow.

featurePolicy.allowsFeature(feature, origin)

• Zwraca wartość true, jeśli funkcja jest dozwolona w przypadku określonego źródła.
• Jeśli metoda zostanie wywołana document, nie będzie już informować, czy funkcja jest dozwolona w przypadku określonego źródła, w przeciwieństwie do zasady Feature Policy. Teraz ta metoda informuje, że możliwe jest udostępnienie danej cechy w przypadku tego źródła. Musisz przeprowadzić dodatkowe sprawdzenie, czy element iframe ma ustawiony atrybut allow. Deweloper musi przeprowadzić dodatkowe sprawdzenie atrybutu allow w elemencie iframe, by określić, czy ta funkcja jest dozwolona w źródle zewnętrznym.

Sprawdź funkcje w elemencie iframe za pomocą obiektu element

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

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

featurePolicy.allowedFeatures()

• Zwraca listę funkcji dozwolonych w przypadku użycia domyślnego źródła.
• Działanie jest takie samo w przypadku obu zasad ustawionych przez zasady uprawnień i zasady dotyczące funkcji.
• Gdy powiązany węzeł jest elementem iframe, uwzględniany jest atrybut allow.

featurePolicy.features()

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

Integracja z Narzędziami deweloperskimi w Chrome

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

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

Migracja z zasady funkcji

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

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

Nagłówki zasad funkcji są obsługiwane tylko w przeglądarkach opartych na Chromium, a nagłówki zasad uprawnień są obsługiwane od Chrome 88, więc można bezpiecznie zaktualizować istniejące nagłówki, używając 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 informacje o korzystaniu z aplikacji 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 zawierającego document. Metoda element.allowsFeature(feature) uwzględnia atrybut allow, a document.allowsFeature(feature, origin) – nie.

Sprawdzam dostęp do funkcji w aplikacji document

Aby 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łanie allowsFeature() w obiekcie element, jak w poprzednim przykładzie.

Reporting API

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

Jeśli chcesz przetestować tę funkcję, wykonaj instrukcje i włącz flagę w narzędziu chrome://flags/#enable-experimental-web-platform-features. Po włączeniu flagi możesz obserwować przypadki naruszenia zasad dotyczących uprawnień w Narzędziach deweloperskich na karcie Aplikacja:

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 tej ramce, konfigurując punkt końcowy o nazwie „default” (jak w przykładzie powyżej). Ramki podrzędne będą wymagać własnej konfiguracji raportowania.

Więcej informacji

Dokładniejsze informacje 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.