التحكّم في ميزات المتصفّح باستخدام "سياسة الأذونات"

يمكنك إدارة كيفية وصول صفحتك وإطارات iframe التابعة لجهات خارجية على صفحتك إلى ميزات المتصفّح.

Kevin K. Lee
Kevin K. Lee
X GitHub

تسمح "سياسة الأذونات"، التي كانت تُعرف سابقًا باسم "سياسة الميزات"، للمطوّر بالتحكم في ميزات المتصفّح المتاحة للصفحة وإطارات iframe ومواد العرض الفرعية، وذلك من خلال الإفصاح عن مجموعة من السياسات لينفّذها المتصفّح. يتم تطبيق هذه السياسات على المصادر المقدَّمة في قائمة مصادر عناوين الاستجابة. يمكن أن تحتوي قائمة المصادر على مصادر من المصدر نفسه و/أو مصادر مختلفة، وتسمح للمطوّر بالتحكم في إمكانية وصول الطرف الأول والطرف الثالث إلى ميزات المتصفّح.

يملك المستخدم القرار النهائي بالسماح بالوصول إلى ميزات أكثر فعالية، ويجب أن يقدّم إذنًا صريحًا من خلال قبول طلب.

تسمح "سياسة الأذونات" للموقع الإلكتروني من المستوى الأعلى بتحديد ما يريده هو والأطراف الثالثة استخدامه، وتزيل من المستخدم عبء تحديد ما إذا كان طلب الوصول إلى الميزة مشروعًا أم لا. على سبيل المثال، باستخدام سياسة الأذونات لحظر ميزة الموقع الجغرافي لجميع الجهات الخارجية، يمكن للمطوّر التأكّد من أنّه لن يتمكّن أي جهة خارجية من الوصول إلى الموقع الجغرافي للمستخدم.

التغييرات على سياسة الأذونات

كانت سياسة الأذونات تُعرف سابقًا باسم "سياسة الميزات". تظل المفاهيم الرئيسية كما هي، لكن هناك بعض التغييرات المهمة إلى جانب الاسم.

استخدام الحقول المنظَّمة

توفّر الحقول المنظَّمة مجموعة من بُنى البيانات الشائعة لتوحيد تحليل وتسلسل قيم حقول عنوان HTTP. يمكنك الاطّلاع على مزيد من المعلومات عن الحقول المنظَّمة من خلال مشاركة مدونة Fastly بعنوان تحسين HTTP باستخدام حقول الرأس المنظَّمة.

الإصدار القديم
  geolocation 'self' https://example.com; camera 'none'

قبل سياسة الميزات.

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

الآن مع سياسة الأذونات.

دمج العناوين مع سمة iframe allow

باستخدام سياسة الميزات، يمكنك إضافة الميزة إلى إطار من مصادر متعددة إما عن طريق إضافة المصدر إلى قائمة مصادر العنوان أو إضافة سمة allow إلى علامة iframe. في سياسة الأذونات، إذا أضفت إطارًا من مصدر مختلف إلى قائمة المصادر، يجب أن تتضمّن علامة iframe لهذا المصدر السمة allow. إذا لم يتضمّن الردّ عنوان سياسة الأذونات، يُعتبَر أنّ قائمة المصادر لها القيمة التلقائية *. تسمح إضافة السمة allow إلى إطار iframe بالوصول إلى الميزة.

لذلك، ننصح المطوّرين بضبط عنوان سياسة الأذونات صراحةً في الاستجابة، حتى يتم حظر إطارات iframe من مصادر مختلفة غير مُدرَجة في قائمة المصادر من الوصول إلى هذه الميزة، حتى إذا كان allow متوفّرًا.

سيظل بإمكانك استخدام "سياسة الميزات" بعد الإصدار 88 من Chrome، ولكنّها تعمل كعنوان بديل لـ "سياسة الأذونات". لا فرق في المنطق سوى في البنية. في حال استخدام كل من عنوانَي "سياسة الأذونات" و"سياسة الميزات" معًا، سيكون لعنوان Permissions-Policy أولوية أعلى، وسيتم استبدال القيمة المقدّمة في العنوان Feature-Policy.

كيف يمكنني استخدام "سياسة الأذونات"؟

نظرة عامة سريعة

قبل الخوض في التفاصيل، لنلقِ نظرة سريعة على سيناريو شائع تكون فيه مالك موقع إلكتروني وتريد التحكّم في كيفية استخدام موقعك الإلكتروني والرمز البرمجي التابع لجهة خارجية لميزات المتصفّح.

  • موقعك الإلكتروني هو https://your-site.example.
  • يضمّن موقعك الإلكتروني إطار iframe من المصدر نفسه (https://your-site.example).
  • يضمِّن موقعك الإلكتروني إطار iframe من https://trusted-site.example تثق به.
  • يعرض موقعك الإلكتروني أيضًا إعلانات تعرِضها https://ad.example.
  • تريد السماح برصد الموقع الجغرافي لموقعك الإلكتروني والموقع الإلكتروني الموثوق به فقط، وليس للإعلان.

وفي هذه الحالة، استخدِم رأس الصفحة التالي:

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

واضبط السمة allow على علامة iframe للموقع الإلكتروني الموثوق به:

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

نظرة عامة سريعة على استخدام سياسة الأذونات

في هذا المثال، لا تسمح قائمة مصادر الرؤوس إلا لموقعك الإلكتروني (self) وtrusted-site.example باستخدام ميزة الموقع الجغرافي. لا يُسمح لتطبيق ad.example باستخدام ميزة رصد الموقع الجغرافي.

  1. يُسمح لموقعك الإلكتروني your-site.example باستخدام ميزة الموقع الجغرافي بعد الحصول على موافقة المستخدم.
  2. يُسمَح لإطار iframe نفسه المصدر (your-site.example) باستخدام الميزة بدون استخدام السمة allow.
  3. يتم حظر استخدام الميزة من خلال عنصر iframe يتم عرضه من نطاق فرعي مختلف (subdomain.your-site-example) لم تتم إضافته إلى قائمة المصادر، وتم ضبط سمة allow على علامة iframe. وتُعتبر النطاقات الفرعية المختلفة موقعًا إلكترونيًا واحدًا ولكن من مصدر آخر.
  4. إنّ إطار iframe من مصادر متعددة (trusted-site.example) تمت إضافته إلى قائمة المصادر وتم ضبطه على السمة allow على علامة iframe ويُسمح باستخدام هذه الميزة.
  5. يتم حظر استخدام الميزة إذا تمّت إضافة إطار iframe (trusted-site.example) من مصدر مختلف إلى قائمة المصادر بدون سمة allow.
  6. يتم حظر استخدام الميزة من خلال إطار iframe (ad.example) من مصدر مختلف لم تتم إضافته إلى قائمة المصادر، حتى إذا كانت سمة allow مضمّنة في علامة iframe.

عنوان استجابة HTTP‏ Permissions-Policy

يقدّم المستخدم طلبًا، ويستجيب الخادم بعرض العنوان &quot;سياسة الأذونات&quot;، ثم يمنح المتصفّح إمكانية الوصول استنادًا إلى ذلك العنوان.

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

يمكنك استخدام عنوان Permissions-Policy في الاستجابة من الخادم لضبط المصادر المسموح بها لإحدى الميزات. يمكن أن تأخذ قيمة العنوان مجموعة من الرموز المميّزة وسلاسل المصادر. الرموز المميّزة المتوفّرة هي * لكل المصادر وself للمصدر نفسه.

إذا كان العنوان خاصًا بعناصر متعددة، افصل بين العناصر بفاصلة. إذا أدرجت مصادر متعددة، افصل بين كل مصدر في قائمة المصادر باستخدام مسافة. بالنسبة إلى الرؤوس التي تسرد مصدرًا لطلب من مصادر متعددة، يجب أن تتضمّن علامة iframe السمة allow.

في ما يلي بعض الأمثلة على أزواج المفتاح/القيمة:

  • البنية: [FEATURE]=*
    • السياسة المطبّقة على جميع المصادر
    • مثلاً: geolocation=*
  • البنية: [FEATURE]=(self)
    • السياسة المطبّقة على المصدر نفسه
    • مثلاً: geolocation=(self)
  • البنية: [FEATURE]=(self [ORIGIN(s)])
    • السياسة المطبّقة على المصادر نفسها والمصادر المحدّدة
    • مثلاً: geolocation=(self "https://a.example" "https://b.example")
    • self هو اختصار لـ https://your-site.example
  • البنية: [FEATURE]=([ORIGIN(s)])
    • تطبيق السياسة على المصدر نفسه والمصادر المحدّدة
    • مثلاً: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
    • عند استخدام هذه البنية، يجب أن يكون أحد المصادر هو مصدر مُضمِّن المحتوى. إذا لم يتم منح صفحة المُضمِّن نفسها الأذونات، سيتم أيضًا حظر إطارات iframe المضمّنة في تلك الصفحة على الرغم من إضافتها إلى قائمة المصادر لأنّ سياسة الأذونات تفوض الأذونات. يمكنك أيضًا استخدام الرمز المميّز self.
  • البنية: [FEATURE]=()
    • الميزة محظورة لجميع المصادر
    • مثلاً: geolocation=()

مسارات ونطاقات فرعية مختلفة

تُعدّ النطاقات الفرعية المختلفة، مثل https://your-site.example وhttps://subdomain.your-site.example، من الموقع الإلكتروني نفسه ولكن من مصادر مختلفة. وبالتالي، لا تسمح إضافة نطاق فرعي في قائمة المصادر بالوصول إلى نطاق فرعي آخر للموقع الإلكتروني نفسه. يجب إضافة كل نطاق فرعي مضمّن يريد استخدام الميزة بشكل منفصل إلى قائمة المصادر. على سبيل المثال، إذا كان يُسمح بالوصول إلى مواضيع التصفّح الخاصة بالمستخدم من المصدر نفسه فقط باستخدام العنوان Permissions-Policy: browsing-topics=(self)، لن يتمكّن إطار iframe من نطاق فرعي مختلف للموقع الإلكتروني نفسه، https://subdomain.your-site.example، من الوصول إلى المواضيع.

تُعتبر المسارات المختلفة، مثل https://your-site.example وhttps://your-site.example/embed، مصدرًا واحدًا، ولا يجب إدراج المسارات المختلفة في قائمة المصادر.

سمة allow في إطار iframe

إعداد إطار iframe

لاستخدام إطار iframe من مصدر مختلف، يجب أن تتضمّن العلامة سمة allow للوصول إلى الميزة.

البنية: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

على سبيل المثال:

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

التعامل مع التنقل في إطار iframe

إعداد التنقل في إطار iframe

بشكلٍ تلقائي، إذا كان إطار iframe ينتقل إلى مصدر آخر، لا يتم تطبيق السياسة على المصدر الذي ينتقل إليه إطار iframe. من خلال إدراج المصدر الذي ينتقل إليه إطار iframe في السمة allow، سيتم تطبيق سياسة الأذونات التي تم تطبيقها على إطار iframe الأصلي على المصدر الذي ينتقل إليه إطار iframe.

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

يمكنك الاطّلاع عليها أثناء التنفيذ من خلال الانتقال إلى العرض التوضيحي للتنقّل في iframe.

أمثلة على إعدادات سياسة الأذونات

يمكن العثور على أمثلة على عمليات الإعداد التالية في الإصدار التجريبي.

هذه الميزة مسموح بها في جميع المصادر.

بنية جميع المصادر المسموح لها بالوصول إلى الميزة

Permissions-Policy: geolocation=*

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

عند ضبط قائمة المصادر على الرمز المميّز *، يتم السماح بالميزة لجميع المصادر المتوفّرة على الصفحة، بما في ذلك الصفحة نفسها وجميع إطارات iframe. في هذا المثال، يمكن لكل الرموز التي يتم عرضها من خلال https://your-site.example والرموز التي يتم عرضها من خلال https://trusted-site.example iframe وhttps://ad.example الوصول إلى ميزة رصد الموقع الجغرافي في متصفّح المستخدم. تذكَّر أنّه يجب أيضًا ضبط سمة allow على عنصر iframe نفسه مع إضافة المصدر إلى قائمة مصادر الرؤوس.

يمكن الاطّلاع على هذا الإعداد في العرض التجريبي.

الميزة مسموح بها من المصدر نفسه فقط

بنية المصدر نفسه فقط مسموح بها للوصول إلى الميزة

Permissions-Policy: geolocation=(self)

ويؤدي استخدام الرمز المميز self إلى السماح باستخدام رصد الموقع الجغرافي للمصدر نفسه فقط. ولن تتمكن المواقع الإلكترونية من مصادر مختلفة من الوصول إلى الميزة. في هذا المثال، لن يتمكّن سوى https://trusted-site.example (self) من الوصول إلى الموقع الجغرافي. استخدِم هذه البنية إذا كنت تريد تفعيل الميزة لصفحتك فقط وليس لأي مستخدم آخر.

يمكن الاطّلاع على هذا الإعداد في العرض التجريبي.

الميزة مسموح بها من المصدر نفسه ومن مصادر محدّدة أخرى

بنية مصادر محدّدة مسموح لها بالوصول إلى الميزة

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

يسمح بناء الجملة هذا باستخدام الموقع الجغرافي لكلّ من "المستخدم نفسه" (https://your-site.example) وhttps://trusted-site.example. تذكَّر إضافة سمة allow إلى علامة iframe بشكل صريح. إذا كان هناك إطار iframe آخر يتضمّن <iframe src="https://ad.example" allow="geolocation">، لن يتمكّن https://ad.example من الوصول إلى ميزة الموقع الجغرافي. لن تتمكن سوى الصفحة الأصلية وhttps://trusted-site.example المدرَجة في قائمة المصادر، بالإضافة إلى سمة allow في علامة iframe، من الوصول إلى ميزة المستخدم.

يمكنك الاطّلاع على هذا الإعداد في العرض التوضيحي.

الميزة محظورة على جميع المصادر

بنية جميع مصادر البيانات المحظورة من الوصول إلى الميزة

Permissions-Policy: geolocation=()

في حال كانت قائمة المصادر فارغة، يتم حظر الميزة لجميع المصادر. يمكن الاطّلاع على هذا الإعداد في العرض التجريبي.

استخدام JavaScript API

يمكن العثور على واجهة برمجة تطبيقات JavaScript الحالية لسياسة الميزات ككائن في المستند أو العنصر (document.featurePolicy or element.featurePolicy). لم يتم تنفيذ واجهة برمجة تطبيقات JavaScript لسياسة الأذونات حتى الآن.

يمكن استخدام واجهة برمجة التطبيقات Feature Policy API مع السياسات التي تحدّدها سياسة الأذونات، مع بعض القيود. هناك أسئلة متبقّية بشأن تنفيذ واجهة برمجة تطبيقات JavaScript، وقد تم تقديم اقتراح لنقل المنطق إلى Permissions API. يمكنك الانضمام إلى المناقشة إذا كانت لديك أي ملاحظات.

featurePolicy.allowsFeature(feature)

  • تعرِض القيمة true إذا كانت الميزة مسموحًا بها لاستخدام المصدر التلقائي.
  • يكون السلوك متطابقًا لكلتا السياستَين اللتين تم ضبطهما من خلال "سياسة الأذونات" و"سياسة الميزات" السابقة.
  • عند استدعاء allowsFeature() على عنصر iframe (iframeEl.featurePolicy.allowsFeature('geolocation'))، تعكس القيمة المعروضة ما إذا تم ضبط سمة allow على iframe.

featurePolicy.allowsFeature(feature, source)

  • تعرض true إذا كانت الميزة مسموحًا بها للمصدر المحدّد.
  • في حال تمّ استدعاء الطريقة على document، لن تخبرك هذه الطريقة بعد الآن ما إذا كانت الميزة مسموحًا بها للمصدر المحدّد كما كانت تفعل "سياسة الميزات". تشير هذه الطريقة الآن إلى أنّه من الممكن السماح بالميزة لهذا المصدر. يجب إجراء عملية تحقّق إضافية لمعرفة ما إذا كان عنصر iframe قد تم ضبط سمة allow فيه أم لا. على المطوّر إجراء عملية تحقّق إضافية للسمة allow في عنصر iframe لتحديد ما إذا كانت الميزة مسموحًا بها لمصدر الجهة الخارجية.

التحقّق من الميزات في إطار iframe باستخدام الكائن element

يمكنك استخدام element.allowsFeature(feature) الذي يأخذ سمة allow في الاعتبار على عكس document.allowsFeature(feature, origin) الذي لا يأخذها في الاعتبار.

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

featurePolicy.allowedFeatures()

  • عرض قائمة بالميزات المسموح بها لاستخدام المصدر التلقائي
  • يكون السلوك متطابقًا لكلتا السياستَين اللتين تم ضبطهما من خلال "سياسة الأذونات" و"سياسة الميزات".
  • عندما تكون العقدة المرتبطة هي إطار iframe، يتم أخذ سمة allow في الاعتبار.

featurePolicy.features()

  • تعرِض هذه الدالة قائمة بالميزات المتاحة في المتصفّح.
  • ينطبق السلوك نفسه على السياستَين اللتَين تم ضبطهما من خلال سياسة الأذونات وسياسة الميزات.

دمج "أدوات مطوّري البرامج في Chrome"

دمج &quot;أدوات مطوري البرامج في Chrome&quot; مع سياسة الأذونات

يمكنك الاطّلاع على طريقة عمل "سياسة الأذونات" في "أدوات مطوّري البرامج".

  1. افتح "أدوات مطوّري البرامج في Chrome".
  2. افتح لوحة التطبيق للتحقّق من الميزات المسموح بها والميزات غير المسموح بها في كل إطار.
  3. في الشريط الجانبي، اختَر الإطار الذي تريد فحصه. ستظهر لك قائمة بالميزات المسموح للإطار المحدّد باستخدامها وقائمة بالميزات المحظورة في هذا الإطار.

نقل البيانات من سياسة الميزات

إذا كنت تستخدِم العنوان Feature-Policy، يمكنك تنفيذ الخطوات التالية لنقل البيانات إلى سياسة الأذونات.

استبدال عناوين سياسة الميزات بعناوين سياسة الأذونات

بما أنّ عناوين "سياسة الميزات" لا تتوفّر إلا في المتصفِّحات المستنِدة إلى Chromium، وعناوين "سياسة الأذونات" متاحة منذ الإصدار 88 من Chrome، من الآمن تعديل العناوين الحالية باستخدام "سياسة الأذونات".

الإصدار القديم
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)

إذا كنت تستخدِم طريقة document.allowsFeature(feature, origin) للتحقّق من الميزات المسموح بها لإطارات iframe، استخدِم طريقة allowsFeature(feature) المرتبطة بعنصر iframe، وليس document الذي يحتوي عليه. تراعي الطريقة element.allowsFeature(feature) سمة allow، في حين لا تراعيها الطريقة document.allowsFeature(feature, origin).

التحقّق من إمكانية الوصول إلى الميزات باستخدام document

لمواصلة استخدام document كسمة العقدة الأساسية، عليك إجراء عملية تحقّق إضافية لسمة allow في علامة 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

بدلاً من تعديل الرمز الحالي باستخدام document، ننصحك باستدعاء allowsFeature() على عنصر element مثل المثال السابق.

Reporting API

توفّر Reporting API آلية للإبلاغ عن تطبيقات الويب بطريقة متّسقة، وتتوفّر Reporting API لانتهاكات سياسة الأذونات كميزة تجريبية.

إذا أردت اختبار الميزة التجريبية، اتّبِع الجولة الإرشادية وفعِّل العلامة في chrome://flags/#enable-experimental-web-platform-features. من خلال تفعيل العلامة، يمكنك ملاحظة انتهاكات "سياسة الأذونات" في "أدوات مطوري البرامج" ضمن علامة التبويب "التطبيق":

يوضّح المثال التالي كيفية إنشاء رأس 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;

في التنفيذ الحالي، يمكنك تلقّي تقارير عن انتهاكات السياسة من أي انتهاكات تحدث خلال هذا الإطار الزمني من خلال ضبط نقطة نهاية باسم "default" مثل المثال السابق. ستتطلب الإطارات الفرعية إعدادات إعداد التقارير الخاصة بها.

التعرف على المزيد

لفهم سياسة الأذونات بشكلٍ أعمق، يُرجى الرجوع إلى المراجع التالية: