שליטה בתכונות הדפדפן באמצעות מדיניות ההרשאות

ניהול האופן שבו לדף ול-iframe של צד שלישי בדף תהיה גישה לתכונות הדפדפן.

Kevin K. Lee

המדיניות בנושא הרשאות, שנקראה בעבר 'מדיניות תכונות', מאפשרת למפתח לשלוט בתכונות הדפדפן שזמינות לדף, ב-iframes ובמשאבי המשנה שלו, על ידי הצהרה על קבוצת כללי מדיניות שהדפדפן צריך לאכוף. כללי המדיניות האלה חלים על מקורות שצוינו ברשימת המקורות של כותרת התגובה. רשימת המקור יכולה לכלול מקורות זהים ו/או מקורות שונים, והיא מאפשרת למפתח לשלוט בגישה של צד ראשון וצד שלישי לתכונות הדפדפן.

המשתמש הוא ההחלטה הסופית אם לאפשר גישה לתכונות חזקות יותר, והוא צריך להעניק הרשאה מפורשת באמצעות הצעה לפעולה.

המדיניות בנושא הרשאות מאפשרת לאתר ברמה העליונה להגדיר במה הוא והצדדים השלישיים שלו מתכוונים להשתמש, ולבטל את הנטל ממשתמשים כדי לקבוע אם בקשת הגישה לתכונה היא לגיטימית או לא. לדוגמה, על ידי חסימת תכונת המיקום הגיאוגרפי לכל הצדדים השלישיים דרך מדיניות ההרשאות, המפתח יכול להיות בטוח שאף צד שלישי לא יקבל גישה למיקום הגיאוגרפי של המשתמש.

שינויים במדיניות ההרשאות

מדיניות ההרשאות נקראה בעבר 'מדיניות תכונות'. מושגי המפתח לא השתנו, אך השם כולל כמה שינויים חשובים.

שימוש בשדות מובנים

שדות מובנים מספקים קבוצה של מבני נתונים נפוצים כדי לקבוע תקן לניתוח ולסריאליזציה של ערכי שדות בכותרת HTTP. קבל מידע נוסף על שדות מובנים בפוסט בבלוג של Fastly, "שיפור HTTP באמצעות שדות כותרת מובנים".

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

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

שילוב הכותרות עם המאפיין allow של iframe

באמצעות מדיניות התכונות, אפשר להוסיף את התכונה למסגרת ממקורות שונים על ידי הוספת המקור לרשימת המקורות של הכותרת או על ידי הוספת המאפיין allow לתג ה-iframe. באמצעות מדיניות ההרשאות, אם מוסיפים מסגרת ממקורות שונים לרשימת המקור, תג ה-iframe של המקור חייב לכלול את המאפיין allow. אם התשובה לא מכילה כותרת של מדיניות הרשאות, רשימת המקור נחשבת עם ערך ברירת המחדל *. הוספת המאפיין allow ל-iframe מאפשרת גישה לתכונה.

לכן אנחנו ממליצים למפתחים להגדיר במפורש את הכותרת של 'מדיניות ההרשאות' בתגובה, כך שלמסגרות iframe ממקורות שונים שלא מופיעים ברשימת המקור לא תהיה גישה לתכונה הזו, גם אם allow קיים.

עדיין אפשר להשתמש במדיניות התכונות אחרי Chrome 88, אבל היא משמשת ככינוי למדיניות ההרשאות. מלבד התחביר, אין הבדל בלוגיקה. אם משתמשים גם בכותרת של מדיניות ההרשאות וגם בכותרות של מדיניות התכונות, לכותרת 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

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, נחשבים לאותו מקור, ולא חייבים לציין נתיבים שונים ברשימת המקור.

מאפיין iframe allow

לשימוש ממקורות שונים, ל-iframe נדרש המאפיין allow בתג כדי לקבל גישה לתכונה.

תחביר: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

למשל:

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

טיפול בניווט 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 יש גישה לתכונת המיקום הגיאוגרפי בדפדפן של המשתמש. חשוב לזכור שצריך להגדיר את מאפיין ההרשאה גם ב-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

ה-API הקיים של JavaScript למדיניות התכונות נמצא כאובייקט במסמך או באלמנט (document.featurePolicy or element.featurePolicy). מדיניות ה-API של JavaScript להרשאות עוד לא הוטמעה.

אפשר להשתמש ב-Feature Policy API לכללי מדיניות שהוגדרו במדיניות ההרשאות, עם מגבלות מסוימות. יש שאלות נוספות לגבי הטמעת JavaScript API, ונרשמה הצעה להעביר את הלוגיקה ל-Permissions API. אם יש לך שאלות, אפשר להצטרף לדיון.

featurePolicy.allowsFeature(feature)

• הפונקציה מחזירה את הערך true אם התכונה מותרת עבור שימוש במקור המוגדר כברירת מחדל.
• ההתנהגות זהה בשני כללי המדיניות שהוגדרו על ידי מדיניות ההרשאות וגם המדיניות הקודמת בנושא תכונות
• כאשר allowsFeature() מופעל על רכיב iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), הערך המוחזר משקף אם מאפיין ההרשאה מוגדר ב-iframe

featurePolicy.allowsFeature(feature, origin)

• הפונקציה מחזירה את הערך true אם התכונה מותרת עבור המקור שצוין.
• אם השיטה מופעלת ב-document, השיטה הזו כבר לא מציינת אם התכונה מותרת עבור המקור שצוין, כמו 'מדיניות התכונות'. עכשיו, השיטה הזו מציינת שיכול להיות שהתכונה תאושר למקור הזה. צריך לבדוק שוב אם המאפיין allow מוגדר ב-iframe או לא. המפתח צריך לבצע בדיקה נוספת של המאפיין 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, מאפיין ההרשאה נלקח בחשבון.

featurePolicy.features()

• מחזירה רשימה של תכונות הזמינות בדפדפן.
• ההתנהגות זהה בשני כללי המדיניות שהוגדרו במדיניות ההרשאות ובמדיניות התכונות

שילוב של כלי הפיתוח ל-Chrome

אפשר לבדוק איך פועלת מדיניות ההרשאות בכלי הפיתוח.

1. פותחים את כלי הפיתוח ל-Chrome.
2. פותחים את החלונית Application (אפליקציה) כדי לבדוק אילו תכונות מותרות ואילו תכונות אסורות לשימוש בכל פריים.
3. בסרגל הצד, בוחרים את המסגרת שרוצים לבדוק. תוצג לכם רשימה של תכונות שמותר למסגרת שבחרתם להשתמש בהן ורשימה של התכונות החסומות במסגרת הזו.

העברה ממדיניות התכונות

אם אתם משתמשים כרגע בכותרת Feature-Policy, אתם יכולים ליישם את השלבים הבאים כדי לעבור למדיניות ההרשאות.

החלפת הכותרות של מדיניות התכונות בכותרות של מדיניות ההרשאות

הכותרות של מדיניות התכונות נתמכות רק בדפדפנים המבוססים על Chromium, והכותרות של מדיניות ההרשאות נתמכות החל מ-Chrome 88. לכן מומלץ לעדכן את הכותרות הקיימות באמצעות מדיניות ההרשאות.

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) מביאה בחשבון את מאפיין ההרשאה, ואילו השיטה 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 Permissions policy הפרות זמין כתכונה ניסיונית.

אם אתם רוצים לבדוק את התכונה הניסיונית, יש לפעול לפי ההדרכה המפורטת ולהפעיל את הדגל ב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;

בהטמעה הנוכחית, כדי לקבל דוחות על הפרות מדיניות לגבי כל הפרה שמתרחשת במסגרת הזו, צריך להגדיר נקודת קצה (endpoint) בשם 'ברירת מחדל' כמו בדוגמה שלמעלה. למסגרות משנה יהיה צורך לקבוע הגדרות דיווח משלהן.

למידע נוסף

להבנה עמוקה יותר של מדיניות ההרשאות, כדאי לעיין במקורות המידע הבאים:

• מפרטים של מדיניות ההרשאות
• הסבר על המדיניות בנושא הרשאות
• רשימה של תכונות שנשלטות על ידי מדיניות.