İzin Politikası ile tarayıcı özelliklerini kontrol etme

Sayfanızın ve sayfanızdaki üçüncü taraf iframe'lerin tarayıcı özelliklerine nasıl erişebileceğini yönetin.

Kevin K. Lee

İzin Politikası (eski adıyla Özellik Politikası), tarayıcının zorunlu kılması için bir dizi politika tanımlayarak geliştiricinin, sayfada, iframe'lerinde ve alt kaynaklarında kullanılabilen tarayıcı özelliklerini kontrol etmesine olanak tanır. Bu politikalar, yanıt başlığı kaynak listesinde sağlanan kaynaklara uygulanır. Kaynak listesi aynı kaynakları ve/veya çapraz kaynaklar içerebilir ve geliştiricinin, tarayıcı özelliklerine birinci taraf ve üçüncü taraf erişimini kontrol etmesine olanak tanır.

Daha güçlü özelliklere erişim izni verme konusunda nihai karar kullanıcıya aittir ve kullanıcının bir istemle açık bir şekilde izin vermesi gerekir.

İzin Politikası, üst düzey sitenin, sitenin ve üçüncü tarafların neyi kullanmayı amaçladığını tanımlamasına olanak tanır ve kullanıcının, özelliğe erişim isteğinin meşru olup olmadığını belirleme yükünü ortadan kaldırır. Örneğin, geliştirici İzin Politikası aracılığıyla tüm üçüncü taraflar için coğrafi konum özelliğini engelleyerek, hiçbir üçüncü tarafın kullanıcının coğrafi konumuna erişim elde etmeyeceğinden emin olabilir.

İzin Politikası'nda Yapılan Değişiklikler

İzin Politikası, daha önce Özellik Politikası olarak biliniyordu. Temel kavramlar değişmedi, ancak adla birlikte bazı önemli değişiklikler yapıldı.

Yapılandırılmış alanların kullanımı

Yapılandırılmış Alanlar, HTTP üst bilgisi alanı değerlerinin ayrıştırılması ve serileştirilmesi için standart hale getirilmesi amacıyla bir dizi yaygın veri yapısı sağlar. Fastly'nin "Yapılandırılmış başlık alanları ile HTTP'yi iyileştirme" başlıklı blog yayınından Yapılandırılmış Alanlar hakkında daha fazla bilgi edinin.

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

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

Üstbilgileri iframe allow özelliğiyle birleştirme

Özellik Politikası ile kaynağı başlık kaynak listesine ekleyerek veya iframe etiketine bir allow özelliği ekleyerek özelliği bir çapraz kaynak çerçevesine ekleyebilirsiniz. İzin Politikası ile kaynak listesine bir çapraz kaynak çerçevesi eklerseniz söz konusu kaynağın iframe etiketi allow özelliğini içermelidir. Yanıt bir İzin Politikası başlığı içermiyorsa kaynak listesinin varsayılan değeri * olarak kabul edilir. allow özelliğinin iframe'e eklenmesi, bu özelliğe erişim sağlar.

Bu nedenle, allow mevcut olsa bile kaynak listesinde yer almayan çapraz kaynak iframe'lerin bu özelliğe erişmesini engellemek için geliştiricilerin yanıtta İzin Politikası başlığını açıkça ayarlamasını öneririz.

Özellik Politikası, Chrome 88'den sonra da kullanılabilir ancak İzin Politikası için takma ad işlevi görür. Söz dizimi dışında, mantık açısından herhangi bir fark bulunmuyor. Hem İzin Politikası hem de Özellik Politikası başlıkları birlikte kullanılırsa Permissions-Policy başlığının önceliği daha yüksek olur ve Feature-Policy başlığı tarafından sağlanan değerin üzerine yazılır.

İzin Politikası'nı nasıl kullanabilirim?

Hızlı genel bakış

Konunun ayrıntılarına dalmadan önce, bir web sitesinin sahibi olduğunuzu ve sitenizin ve üçüncü taraf kodunuzun tarayıcı özelliklerini nasıl kullandığını kontrol etmek istediğiniz yaygın bir senaryoya hızlıca göz atalım.

• Siteniz: https://your-site.example.
• Siteniz aynı kaynaktan bir iframe yerleştiriyor (https://your-site.example).
• Siteniz, https://trusted-site.example kaynağından güvendiğiniz bir iframe yerleştiriyor.
• Sitenizde https://ad.example tarafından yayınlanan reklamlar da gösteriliyor.
• Reklam için değil, yalnızca siteniz ve güvenilir site için coğrafi konuma izin vermek istiyorsanız.

Bu durumda, aşağıdaki başlığı kullanın:

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

Ve güvenilir sitenin iframe etiketinde allow özelliğini açık bir şekilde ayarlayın:

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

Bu örnekte, başlık kaynak listesi yalnızca sitenizin (self) ve trusted-site.example sitesinin coğrafi konum özelliğini kullanmasına izin verir. ad.example uygulamasının coğrafi konumu kullanmasına izin verilmiyor.

1. Kullanıcının izniyle, sitenizin (your-site.example) coğrafi konum özelliğini kullanmasına izin veriliyor.
2. Aynı kaynaklı iframe'in (your-site.example), allow özelliği kullanılmadan bu özelliği kullanmasına izin verilir.
3. Kaynak listesine eklenmemiş farklı bir alt alan adından (subdomain.your-site-example) sunulan ve iframe etiketinde "Allow" özelliği ayarlanmış olan bir iframe'in bu özelliği kullanması engellenir. Farklı alt alan adları aynı site ancak çapraz kaynak olarak kabul edilir.
4. Kaynak listesine eklenmiş ve iframe etiketinde allow özelliği ayarlanmış bir çapraz kaynak iframe'in (trusted-site.example) bu özelliği kullanmasına izin veriliyor.
5. Kaynak listesine allow özelliği olmadan eklenen çapraz kaynak iframe'in (trusted-site.example) bu özelliği kullanması engellenir.
6. Kaynak listesine eklenmemiş bir çapraz kaynak iframe'in (ad.example), allow özelliği iFrame etiketine dahil olsa bile bu özelliği kullanması engellenir.

Permissions-Policy HTTP yanıt başlığı

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

Bir özellik için izin verilen kaynakları ayarlamak üzere sunucudan gelen yanıtta bir Permissions-Policy üst bilgisi kullanın. Başlık değeri, belirteçlerin ve kaynak dizelerinin bir kombinasyonunu alabilir. Kullanılabilir jetonlar, tüm kaynaklar için * ve aynı kaynak için self şeklindedir.

Başlığınız birden çok özelliğe yönelikse özellikleri virgülle ayırın. Birden fazla kaynak listelerseniz kaynak listesindeki her kaynağı boşlukla ayırın. Çapraz kaynak isteği olan bir kaynağı listeleyen başlıklar için iframe etiketi, allow özelliğini içermelidir.

Aşağıda bazı örnek anahtar/değer çiftleri verilmiştir:

• Sözdizimi: [FEATURE]=*
  • Politika tüm kaynaklara uygulandı
  • Örnek: geolocation=*
• Sözdizimi: [FEATURE]=(self)
  • Aynı kaynağa uygulanan politika
  • Örnek: geolocation=(self)
• Sözdizimi: [FEATURE]=(self [ORIGIN(s)])
  • Politika aynı kaynağa ve belirtilen kaynaklara uygulandı
  • Örnek: geolocation=(self "https://a.example" "https://b.example")
  • self, https://your-site.example kelimesinin kısaltmasıdır
• Sözdizimi: [FEATURE]=([ORIGIN(s)])
  • Politika aynı kaynağa ve belirtilen kaynaklara uygulandı
  • Örnek: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Bu söz dizimi kullanılırken kaynaklardan biri, yerleştirenin kaynağı olmalıdır. Yerleştiren sayfaya izinler verilmezse bu sayfaya yerleştirilmiş iframe'ler, izin politikası izinleri yetkilendirdiği için kaynak listesine eklenmiş olsalar da engellenir. self jetonunu da kullanabilirsiniz.
• Sözdizimi: [FEATURE]=()
  • Özellik tüm kaynaklar için engellendi
  • Örnek: geolocation=()

Farklı alt alan adları ve yollar

https://your-site.example ve https://subdomain.your-site.example gibi farklı alt alan adları aynı site ancak çapraz kaynak olarak kabul edilir. Bu nedenle, kaynak listesine alt alan adı eklemek aynı sitenin başka bir alt alan adına erişilmesine izin vermez. Özelliği kullanmak isteyen her yerleştirilmiş alt alan adı, kaynak listesine ayrı olarak eklenmelidir. Örneğin, kullanıcının göz atma konularına yalnızca Permissions-Policy: browsing-topics=(self) başlığı ile aynı kaynağa erişim izni veriliyorsa aynı sitenin farklı bir alt alan adından (https://subdomain.your-site.example) gelen bir iframe'in konulara erişimi olmaz.

https://your-site.example ve https://your-site.example/embed gibi farklı yollar aynı kaynak olarak kabul edilir ve farklı yolların kaynak listesinde listelenmesine gerek yoktur.

iFrame allow özelliği

Kaynaklar arası kullanım söz konusu olduğunda, iframe'in özelliğe erişmek için etikette allow özelliğine ihtiyacı vardır.

Sözdizimi: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

Örneğin:

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

iframe'de gezinmeyi yönetme

Varsayılan olarak bir iframe başka bir kaynağa giderse politika, iframe'in gittiği kaynağa uygulanmaz. iframe'in gittiği kaynak allow özelliğinde listelendiğinde, orijinal iframe'e uygulanan İzin Politikası iframe'in gittiği kaynağa uygulanır.

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

iframe gezinme demosunu ziyaret ederek bunu çalışırken görebilirsiniz.

Örnek İzin Politikası kurulumları

Aşağıdaki kurulum örneklerini demo bölümünde bulabilirsiniz.

Özelliğe tüm kaynaklarda izin veriliyor

Permissions-Policy: geolocation=*

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

Kaynak listesi * jetonuna ayarlandığında bu özelliğe, kendisi ve tüm iframe'ler dahil olmak üzere sayfada bulunan tüm kaynaklar için izin verilir. Bu örnekte, https://your-site.example ürününden sunulan tüm kodlar ve https://trusted-site.example iframe ile https://ad.example'den sunulan kodlar kullanıcının tarayıcısındaki coğrafi konum özelliğine erişim sahibidir. allow özelliğinin, kaynak başlık kaynak listesine eklenmesiyle birlikte iframe üzerinde de ayarlanması gerektiğini unutmayın.

Bu kurulumu demoda görebilirsiniz.

Özelliğe yalnızca aynı kaynakta izin veriliyor

Permissions-Policy: geolocation=(self)

self jetonunun kullanılması, yalnızca aynı kaynaktan coğrafi konum kullanımına olanak tanır. Çapraz kaynaklar bu özelliğe erişemez. Bu örnekte, yalnızca https://trusted-site.example (self) coğrafi konuma erişebilecek. Özelliğin yalnızca sizin sayfanız için olmasını ve başka hiç kimse için istemiyorsanız bu söz dizimini kullanın.

Bu kurulumu demoda görebilirsiniz.

Aynı kaynakta ve belirli çapraz kaynaklarda izin verilen özellik

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

Bu söz dizimi, coğrafi konumun hem kendisi (https://your-site.example) hem de https://trusted-site.example için kullanılmasına olanak tanır. allow özelliğini açık bir şekilde iframe etiketine eklemeyi unutmayın. <iframe src="https://ad.example" allow="geolocation"> içeren başka bir iframe varsa https://ad.example, coğrafi konum özelliğine erişemez. Kullanıcının özelliğine yalnızca, kaynak listesinde belirtilen https://trusted-site.example ve iframe etiketinde allow özelliğine sahip olan sayfa erişebilir.

Bu kurulumu demoda görebilirsiniz.

Özellik tüm kaynaklarda engellendi

Permissions-Policy: geolocation=()

Boş bir kaynak listesi varsa özellik tüm kaynaklar için engellenir. Bu kurulumu demoda görebilirsiniz.

JavaScript API'sini kullanma

Özellik Politikası'nın mevcut JavaScript API'si belgede veya öğede (document.featurePolicy or element.featurePolicy) nesne olarak bulundu. İzin Politikası için JavaScript API henüz uygulanmadı.

Feature Policy API, bazı kısıtlamalarla birlikte İzin Politikası tarafından belirlenen politikalar için kullanılabilir. Bir JavaScript API uygulamasıyla ilgili kalan sorular bulunmaktadır ve mantığın Permissions API'ye taşınması için bir teklif sunulmuştur. Düşünceleriniz varsa tartışmaya katılın.

featurePolicy.allowsFeature(feature)

• Bu özelliğe varsayılan kaynak kullanımı için izin veriliyorsa true değerini döndürür.
• Bu davranış, İzin Politikası tarafından ayarlanan her iki politikada ve önceki Özellik Politikası'nda aynıdır.
• Bir iframe öğesinde (iframeEl.featurePolicy.allowsFeature('geolocation')) allowsFeature() çağrıldığında döndürülen değer, allow özelliğinin iframe'de ayarlanmış olup olmadığını yansıtır

özellik politikası.allowsFeature(özellik; kaynak)

• Belirtilen kaynak için özelliğe izin veriliyorsa true değerini döndürür.
• Yöntem document üzerinde çağrılırsa bu yöntem, Özellik Politikası'nda olduğu gibi özelliğe belirtilen kaynak için izin verilip verilmediğini artık size bildirmez. Bu yöntem, ilgili özelliğin ilgili kaynağa erişmesine izin verilebileceğini belirtir. iframe'de allow özelliğinin ayarlanıp ayarlanmadığına dair ek bir kontrol yapmanız gerekir. Geliştirici, üçüncü taraf kaynak için bu özelliğe izin verilip verilmediğini belirlemek üzere iframe öğesinde allow özelliğini ek bir kontrol etmelidir.

element nesnesine sahip bir iframe'de özellikleri kontrol edin

İzin ver özelliğini hesaba katan element.allowsFeature(feature) kullanabilirsiniz (document.allowsFeature(feature, origin) özelliğinin aksine).

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

featurePolicy.allowedFeatures()

• Varsayılan kaynak kullanımı için izin verilen özelliklerin listesini döndürür.
• Bu davranış, İzin Politikası ve Özellik Politikası tarafından belirlenen her iki politika için de aynıdır.
• İlişkili düğüm bir iframe olduğunda, allow özelliği dikkate alınır.

featurePolicy.features()

• Tarayıcıda kullanılabilen özelliklerin bir listesini döndürür.
• Bu davranış, İzin Politikası ve Özellik Politikası tarafından belirlenen her iki politika için de aynıdır.

Chrome Geliştirici Araçları entegrasyonu

Geliştirici Araçları'nda izin politikasının işleyiş şekline göz atın.

1. Chrome Geliştirici Araçları'nı açın.
2. Her bir çerçevede izin verilen ve izin verilmeyen özellikleri kontrol etmek için Uygulama panelini açın.
3. Kenar çubuğunda incelemek istediğiniz kareyi seçin. Seçilen çerçevenin kullanmasına izin verilen özelliklerin ve o çerçevede engellenen özelliklerin bir listesi sunulur.

Özellik-Politikasından Taşıma

Şu anda Feature-Policy üstbilgisini kullanıyorsanız İzin Politikası'na geçiş için aşağıdaki adımları uygulayabilirsiniz.

Özellik Politikası başlıklarını, İzin Politikası başlıklarıyla değiştir

Özellik Politikası başlıkları yalnızca Chromium tabanlı tarayıcılarda ve İzin Politikası başlıkları Chrome 88'den itibaren desteklendiğinden, mevcut başlıkları İzin Politikası ile güncellemek güvenlidir.

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

document.allowsFeature(feature, origin) kullanımını güncelle

iframe'ler için izin verilen özellikleri kontrol etmek üzere document.allowsFeature(feature, origin) yöntemini kullanıyorsanız iframe öğesine ekli olan document yöntemini değil, iframe öğesine eklenen allowsFeature(feature) yöntemini kullanın. element.allowsFeature(feature) yöntemi allow özelliğini dikkate alırken document.allowsFeature(feature, origin) bunu yapmaz.

document ile özellik erişimi kontrol ediliyor

Temel düğüm olarak document kullanmaya devam etmek için iframe etiketinde allow özelliğine yönelik ek bir kontrol gerçekleştirmeniz gerekir.

<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

Mevcut kodu document kullanarak güncellemek yerine, önceki örnekte olduğu gibi element nesnesinde allowsFeature() çağrısının yapılması önerilir.

Reporting API

Reporting API, web uygulamaları için tutarlı bir şekilde bir raporlama mekanizması sağlar. İzin Politikası ihlalleri için Reporting API deneysel bir özellik olarak kullanılabilir.

Deneysel özelliği test etmek istiyorsanız adım adım açıklamalı kılavuzu izleyin ve chrome://flags/#enable-experimental-web-platform-features öğesinde işareti etkinleştirin. İşaret etkinleştirildiğinde, Uygulama sekmesi altındaki Geliştirici Araçları'nda İzin Politikası ihlallerini gözlemleyebilirsiniz:

Aşağıdaki örnekte, Reporting API başlığının nasıl oluşturulabileceği gösterilmektedir:

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;

Mevcut uygulamada, yukarıdaki örnekte gösterildiği gibi "varsayılan" adlı bir uç nokta yapılandırarak, söz konusu çerçeve içinde gerçekleşen ihlallerden politika ihlali raporları alabilirsiniz. Alt çerçevelerin kendi raporlama yapılandırmaları gerekir.

Daha fazla bilgi

İzin Politikası hakkında daha ayrıntılı bilgi için aşağıdaki kaynaklara bakın:

• İzin Politikası spesifikasyonları
• İzin Politikası açıklayıcı
• Politikayla kontrol edilen özelliklerin listesi.