Kelola cara halaman dan iframe pihak ketiga di halaman Anda memiliki akses ke fitur browser.
Kebijakan Izin, sebelumnya dikenal sebagai Kebijakan Fitur, memungkinkan developer untuk mengontrol fitur browser yang tersedia untuk halaman, iframe-nya, dan subresource, dengan mendeklarasikan serangkaian kebijakan untuk diterapkan browser. Ini kebijakan diterapkan ke origin yang disediakan dalam daftar asal header respons. Daftar origin dapat berisi origin yang sama dan/atau lintas origin, serta memungkinkan developer untuk mengontrol akses pihak pertama dan pihak ketiga ke fitur browser.
Pengguna memiliki keputusan akhir untuk mengizinkan akses ke fitur yang lebih canggih, dan harus memberikan izin eksplisit melalui prompt.
Kebijakan Izin memungkinkan situs tingkat atas menentukan apa yang ingin dan digunakan oleh pihak ketiga, dan menghilangkan beban dari pengguna dalam menentukan apakah permintaan akses fitur itu sah atau tidak. Misalnya, dengan memblokir fitur geolokasi untuk semua pihak ketiga melalui Kebijakan Izin, pengembang dapat memastikan bahwa tidak ada pihak ketiga yang akan memperoleh akses ke geolokasi.
Perubahan pada Kebijakan Izin
Kebijakan Izin sebelumnya dikenal sebagai Kebijakan Fitur. Konsep utamanya tetap sama, tetapi ada beberapa perubahan penting seiring dengan namanya.
Penggunaan Kolom Terstruktur
Kolom Terstruktur menyediakan kumpulan struktur data umum untuk menstandarkan penguraian dan serialisasi nilai kolom header HTTP. Pelajari lebih lanjut Kolom Terstruktur dari postingan blog Fastly, "Meningkatkan HTTP dengan kolom header terstruktur".
geolocation 'self' https://example.com; camera 'none'
Sebelumnya dengan Kebijakan Fitur.
geolocation=(self "https://example.com"), camera=()
Kini dengan Kebijakan Izin.
Gabungkan header dengan atribut allow
iframe
Dengan Kebijakan Fitur, Anda dapat menambahkan fitur ke frame lintas origin dengan menambahkan origin ke daftar asal header atau menambahkan atribut allow
ke tag iframe. Dengan Kebijakan Izin, jika Anda menambahkan frame lintas origin ke daftar origin, tag iframe untuk origin tersebut harus menyertakan atribut allow
.
Jika respons tidak berisi header Kebijakan Izin, daftar origin akan dianggap memiliki nilai default *
. Menambahkan atribut allow
ke iframe akan memungkinkan akses ke fitur tersebut.
Oleh karena itu, sebaiknya developer menetapkan header Kebijakan Izin secara eksplisit dalam respons, sehingga iframe lintas origin yang tidak tercantum dalam daftar origin diblokir agar tidak dapat mengakses fitur ini, meskipun allow
ada.
Kebijakan Fitur masih dapat digunakan setelah Chrome 88, tetapi berfungsi sebagai alias untuk Kebijakan Izin. Selain sintaksis, tidak ada perbedaan logika. Jika header Kebijakan Izin dan Kebijakan Fitur digunakan bersama, header Permissions-Policy
akan memiliki prioritas yang lebih tinggi, dan akan menimpa nilai yang diberikan oleh header Feature-Policy
.
Bagaimana cara menggunakan Kebijakan Izin?
Ringkasan singkat
Sebelum membahas lebih dalam, mari kita lihat sekilas skenario umum saat Anda adalah pemilik situs dan ingin mengontrol cara situs dan kode pihak ketiga Anda menggunakan fitur browser.
- Situs Anda adalah
https://your-site.example
. - Situs Anda menyematkan iframe dari origin yang sama (
https://your-site.example
). - Situs Anda menyematkan iframe dari
https://trusted-site.example
yang Anda percayai. - Situs Anda juga menampilkan iklan yang ditayangkan oleh
https://ad.example
. - Anda ingin mengizinkan geolokasi hanya untuk situs Anda dan situs tepercaya, bukan untuk iklan.
Dalam hal ini, gunakan header berikut:
Permissions-Policy: geolocation=(self "https://trusted-site.example")
Selain itu, setel atribut allow
secara eksplisit ke tag iframe untuk situs tepercaya:
<iframe src="https://trusted-site.example" allow="geolocation">
Dalam contoh ini, daftar asal header hanya memungkinkan situs Anda (self
) dan trusted-site.example
untuk menggunakan fitur geolokasi. ad.example
tidak diizinkan untuk menggunakan geolokasi.
- Situs Anda
your-site.example
diizinkan untuk menggunakan fitur geolokasi dengan persetujuan pengguna. - iframe origin yang sama (
your-site.example
) diizinkan untuk menggunakan fitur tanpa menggunakan atributallow
. - iframe yang ditayangkan dari subdomain berbeda (
subdomain.your-site-example
) yang tidak ditambahkan ke daftar asal, dan memiliki atribut izinkan yang ditetapkan di tag iframe, diblokir agar tidak dapat menggunakan fitur tersebut. Subdomain yang berbeda dianggap sebagai situs yang sama, tetapi lintas origin. - iframe lintas origin (
trusted-site.example
) yang ditambahkan ke daftar asal dan memiliki atributallow
yang ditetapkan pada tag iframe diizinkan untuk menggunakan fitur ini. - iframe lintas origin (
trusted-site.example
) yang ditambahkan ke daftar asal, tanpa atributallow
, diblokir agar tidak menggunakan fitur ini. - iframe lintas origin (
ad.example
) yang tidak ditambahkan ke daftar asal diblokir agar tidak menggunakan fitur tersebut, meskipun atributallow
disertakan dalam tag iframe.
Header respons HTTP Permissions-Policy
Permissions-Policy: <feature>=(<token>|<origin(s)>)
Gunakan header Permissions-Policy
dalam respons dari server untuk menetapkan origin yang diizinkan untuk suatu fitur. Nilai header dapat mengambil kombinasi token dan string origin. Token yang tersedia adalah *
untuk semua origin dan self
untuk origin yang sama.
Jika header Anda ditujukan untuk beberapa fitur, pisahkan fitur tersebut dengan koma. Jika Anda mencantumkan beberapa origin, pisahkan setiap origin dalam daftar origin dengan spasi. Untuk header yang mencantumkan origin yang merupakan permintaan lintas origin, tag iframe harus menyertakan atribut allow
.
Berikut adalah beberapa contoh pasangan nilai kunci:
- Sintaksis:
[FEATURE]=*
- Kebijakan diterapkan ke semua origin
- Contoh:
geolocation=*
- Sintaksis:
[FEATURE]=(self)
- Kebijakan diterapkan ke origin yang sama
- Contoh:
geolocation=(self)
- Sintaksis:
[FEATURE]=(self [ORIGIN(s)])
- Kebijakan diterapkan ke origin yang sama dan origin yang ditentukan
- Contoh:
geolocation=(self "https://a.example" "https://b.example")
self
adalah singkatan untukhttps://your-site.example
- Sintaksis:
[FEATURE]=([ORIGIN(s)])
- Kebijakan diterapkan ke origin yang sama dan origin yang ditentukan
- Contoh:
geolocation=("https://your-site.example" "https://a.example" "https://b.example")
- Saat menggunakan sintaksis ini, salah satu origin harus merupakan origin dari embeddingder. Jika halaman sematan tidak diberi izin, iframe yang disematkan di halaman tersebut juga akan diblokir meskipun ditambahkan ke daftar origin karena Kebijakan Izin mendelegasikan izin. Anda juga dapat menggunakan token
self
.
- Sintaksis:
[FEATURE]=()
- Fitur diblokir untuk semua origin
- Contoh:
geolocation=()
Subdomain dan jalur yang berbeda
Subdomain yang berbeda, seperti https://your-site.example
dan https://subdomain.your-site.example
, dianggap situs yang sama, tetapi lintas origin. Oleh karena itu, menambahkan subdomain dalam daftar origin tidak mengizinkan akses ke subdomain lain dari situs yang sama. Setiap subdomain tersemat yang ingin menggunakan fitur tersebut harus ditambahkan secara terpisah ke daftar origin. Misalnya, jika akses ke topik penjelajahan pengguna diizinkan ke origin yang sama hanya dengan header Permissions-Policy: browsing-topics=(self)
, iframe dari subdomain lain dari situs yang sama, https://subdomain.your-site.example
, tidak akan memiliki akses ke topik tersebut.
Jalur yang berbeda, seperti https://your-site.example
dan https://your-site.example/embed
, dianggap sebagai origin yang sama, dan jalur yang berbeda tidak harus dicantumkan dalam daftar origin.
Atribut Iframe allow
Untuk penggunaan lintas origin, iframe memerlukan atribut allow
dalam tag untuk mendapatkan akses ke fitur.
Sintaksis: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>
Contoh:
<iframe src="https://trusted-site.example" allow="geolocation">
Menangani navigasi iframe
Secara default, jika iframe mengarah ke origin lain, kebijakan tidak akan diterapkan ke origin yang dituju iframe. Dengan mencantumkan origin yang dituju iframe di atribut allow
, Kebijakan Izin yang diterapkan ke iframe asli akan diterapkan ke origin yang dituju iframe.
<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">
Anda dapat melihatnya dengan membuka demo navigasi iframe.
Contoh penyiapan Kebijakan Izin
Contoh penyiapan berikut dapat ditemukan di demo.
Fitur diizinkan di semua origin
Permissions-Policy: geolocation=*
<iframe src="https://trusted-site.example" allow="geolocation">
<iframe src="https://ad.example" allow="geolocation">
Jika daftar origin ditetapkan ke token *
, fitur tersebut akan diizinkan untuk semua origin yang ada di halaman, termasuk halaman itu sendiri dan semua iframe. Dalam contoh ini, semua kode yang disajikan dari https://your-site.example
dan kode yang ditampilkan dari iframe https://trusted-site.example
dan https://ad.example
memiliki akses ke fitur geolokasi di browser pengguna. Ingat bahwa atribut allow juga harus disetel pada iframe bersama dengan menambahkan origin ke daftar asal header.
Penyiapan ini dapat dilihat di demo.
Fitur diizinkan hanya di origin yang sama
Permissions-Policy: geolocation=(self)
Penggunaan token self
memungkinkan penggunaan geolokasi ke asal yang sama saja. Cross-origin tidak akan memiliki akses ke fitur ini. Dalam contoh ini, hanya https://trusted-site.example
(self
) yang akan memiliki akses ke geolokasi. Gunakan sintaksis ini jika Anda ingin fitur tersebut hanya untuk halaman Anda dan bukan untuk orang lain.
Penyiapan ini dapat dilihat di demo.
Fitur diizinkan di origin yang sama dan lintas origin spesifik
Permissions-Policy: geolocation=(self "https://trusted-site.example")
Sintaksis ini memungkinkan penggunaan geolokasi ke diri (https://your-site.example
) dan https://trusted-site.example
. Jangan lupa untuk menambahkan atribut allow secara eksplisit ke tag iframe. Jika ada iframe lain dengan <iframe src="https://ad.example" allow="geolocation">
, https://ad.example
tidak akan memiliki akses ke fitur geolokasi. Hanya halaman asli dan https://trusted-site.example
yang tercantum dalam daftar asal bersama dengan atribut izinkan di tag iframe yang akan memiliki akses ke fitur pengguna.
Penyiapan ini dapat dilihat di demo.
Fitur diblokir di semua origin
Permissions-Policy: geolocation=()
Dengan daftar origin yang kosong, fitur ini akan diblokir untuk semua origin. Penyiapan ini dapat dilihat di demo.
Menggunakan JavaScript API
JavaScript API dari Kebijakan Fitur yang ada ditemukan sebagai objek pada dokumen atau elemen (document.featurePolicy or element.featurePolicy
). JavaScript API untuk Kebijakan Izin belum diterapkan.
Feature Policy API dapat digunakan untuk kebijakan yang ditetapkan oleh Kebijakan Izin, dengan beberapa batasan. Ada sisa pertanyaan terkait penerapan JavaScript API, dan proposal telah dibuat untuk memindahkan logika ke Permissions API. Bergabunglah dalam diskusi jika Anda memiliki pendapat.
featurePolicy.allowsFeature(feature)
- Menampilkan
true
jika fitur diizinkan untuk penggunaan origin default. - Perilaku untuk kebijakan yang ditetapkan oleh Kebijakan Izin dan Kebijakan Fitur sebelumnya sama
- Saat
allowsFeature()
dipanggil di elemen iframe (iframeEl.featurePolicy.allowsFeature('geolocation')
), nilai yang ditampilkan akan mencerminkan apakah atribut izinkan ditetapkan di iframe
featurePolicy.allowsFeature(feature, origin)
- Menampilkan
true
jika fitur diizinkan untuk origin yang ditentukan. - Jika metode ini dipanggil di
document
, metode ini tidak lagi memberi tahu Anda apakah fitur tersebut diizinkan untuk origin yang ditentukan seperti Feature Policy. Sekarang, metode ini memberi tahu Anda bahwa fitur bisa saja diizinkan untuk asal tersebut. Anda harus melakukan pemeriksaan tambahan apakah iframe memiliki atributallow
yang disetel atau belum. Developer harus melakukan pemeriksaan tambahan terhadap atributallow
di elemen iframe guna menentukan apakah fitur tersebut diizinkan untuk asal pihak ketiga atau tidak.
Memeriksa fitur di iframe dengan objek element
Anda dapat menggunakan element.allowsFeature(feature)
yang mempertimbangkan atribut izinkan, tidak seperti document.allowsFeature(feature, origin)
yang tidak.
const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')
featurePolicy.allowedFeatures()
- Menampilkan daftar fitur yang diizinkan untuk penggunaan origin default.
- Perilaku untuk kebijakan yang ditetapkan oleh Kebijakan Izin dan Kebijakan Fitur sama
- Jika node yang terkait adalah iframe, atribut izinkan akan dipertimbangkan.
featurePolicy.features()
- Menampilkan daftar fitur yang tersedia di browser.
- Perilaku untuk kebijakan yang ditetapkan oleh Kebijakan Izin dan Kebijakan Fitur sama
Integrasi Chrome DevTools
Lihat cara kerja Kebijakan Izin di DevTools.
- Buka Chrome DevTools.
- Buka panel Aplikasi untuk memeriksa fitur yang diizinkan dan fitur yang tidak diizinkan dari setiap frame.
- Di {i>sidebar<i}, pilih bingkai yang ingin Anda periksa. Anda akan melihat daftar fitur yang diizinkan untuk digunakan oleh frame yang dipilih dan daftar fitur yang diblokir di frame tersebut.
Migrasi dari Kebijakan Fitur
Jika saat ini Anda menggunakan header Feature-Policy
, Anda dapat menerapkan langkah-langkah berikut untuk bermigrasi ke Kebijakan Izin.
Ganti header Kebijakan Fitur dengan header Kebijakan Izin
Karena header Kebijakan Fitur hanya didukung di browser berbasis Chromium, dan header Kebijakan Izin didukung mulai versi Chrome 88, Anda dapat memperbarui header yang ada dengan Kebijakan Izin.
Feature-Policy: autoplay *; geolocation 'self'; camera 'self' 'https://trusted-site.example'; fullscreen 'none';
Sebelumnya dengan Kebijakan Fitur.
Permissions-Policy: autoplay=*, geolocation=(self), camera=(self "https://trusted-site.example"), fullscreen=()
Kini dengan Kebijakan Izin.
Perbarui penggunaan document.allowsFeature(feature, origin)
Jika Anda menggunakan metode document.allowsFeature(feature, origin)
untuk memeriksa fitur yang diizinkan untuk iframe, gunakan metode allowsFeature(feature)
yang dilampirkan di elemen iframe, bukan document
yang memuatnya. Metode element.allowsFeature(feature)
memperhitungkan atribut izinkan sedangkan document.allowsFeature(feature, origin)
tidak.
Memeriksa akses fitur dengan document
Untuk terus menggunakan document
sebagai node dasar, Anda harus melakukan pemeriksaan tambahan untuk atribut allow
di tag 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
Daripada mengupdate kode yang ada menggunakan document
, sebaiknya panggil allowsFeature()
pada objek element
seperti contoh sebelumnya.
Reporting API
Reporting API menyediakan mekanisme pelaporan untuk aplikasi web secara konsisten, dan Reporting API untuk pelanggaran Kebijakan Izin tersedia sebagai fitur eksperimental.
Jika Anda ingin menguji fitur eksperimental, ikuti panduan dan aktifkan tanda di chrome://flags/#enable-experimental-web-platform-features
. Dengan mengaktifkan flag, Anda bisa mengamati pelanggaran Kebijakan Izin di DevTools pada tab Application:
Contoh berikut menunjukkan cara pembuatan header 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;
Dalam implementasi saat ini, Anda dapat menerima laporan pelanggaran kebijakan dari pelanggaran apa pun yang terjadi dalam frame tersebut dengan mengonfigurasi endpoint bernama 'default' seperti contoh di atas. Subframe akan memerlukan konfigurasi pelaporannya sendiri.
Cari tahu selengkapnya
Untuk pemahaman yang lebih mendalam tentang Kebijakan Izin, lihat referensi berikut: