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

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

Kevin K. Lee
Kevin K. Lee
X GitHub

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

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

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

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

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

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

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

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

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

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

تتوفّر الآن سياسة الأذونات.

دمج العناوين مع السمة allow في إطار iframe

باستخدام سياسة الميزة، يمكنك إضافة الميزة إلى إطار من مصادر متعددة عن طريق إضافة المصدر إلى قائمة أصل العنوان أو إضافة سمة 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) لم تتم إضافته إلى قائمة المصادر، ويحتوي على سمة "السماح" على علامة 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: &lt;feature&gt;=(&lt;token&gt;|&lt;origin(s)&gt;)

يمكنك استخدام عنوان 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، من المصدر نفسه، ويجب عدم إدراج المسارات المختلفة في قائمة المصادر.

سمة Iframe allow

إعداد إطارات 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 والرموز التي يتم عرضها من خلال إطار iframe وhttps://ad.example الخاص بـ https://trusted-site.example يمكنها الوصول إلى ميزة الموقع الجغرافي في متصفّح المستخدم. لا تنسَ أنّه يجب أيضًا ضبط سمة "السماح" على إطار 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 الواردان في قائمة المصادر فقط مع تضمين السمة "السماح" في علامة 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, origin)

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

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

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

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

featurePolicy.allowedFeatures()

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

featurePolicy.features()

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

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

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

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

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

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

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

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

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

الإصدار القديم
Feature-Policy:
  autoplay *;
  geolocation 'self';
  camera 'self' 'https://trusted-site.example';
  fullscreen 'none';

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

New
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 for الأذونات كميزة تجريبية.

إذا كنت تريد اختبار الميزة التجريبية، اتّبِع الجولة التفصيلية وفعِّل العلامة في 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;

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

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

لمزيد من المعلومات عن "سياسة الأذونات"، يمكنك الاطّلاع على المراجع التالية: