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

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

Kevin K. Lee

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

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

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

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

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

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

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

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

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

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

באמצעות מדיניות התכונות, תוכלו להוסיף את התכונה למסגרת ממקורות שונים על ידי הוספת המקור לרשימת מקורות הכותרת או הוספת מאפיין allow לתג iframe. במדיניות הרשאות, אם מוסיפים מסגרת ממקורות שונים לרשימת המקורות, תג ה-iframe של המקור הזה חייב לכלול את המאפיין allow. אם התשובה לא תכיל כותרת Permissions Policy, רשימת המקור נחשבת כערך ברירת המחדל של *. הוספת המאפיין 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")
  • כשמשתמשים בתחביר הזה, אחד מהמקורות צריך להיות המקור של כלי ההטמעה. אם לדף כלי ההטמעה עצמו לא ניתנו ההרשאות, גם ה-iframes שמוטמעים בדף הזה ייחסמו אף הם, למרות שהם נוספו לרשימת המקורות מפני שמדיניות ההרשאות מעניקה הרשאות. אפשר גם להשתמש באסימון 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 עובר. במאפיין allow מציינים את המקור שאליו עובר ב-iframe, מדיניות ההרשאות שהוחלה על ה-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://trusted-site.example ומ-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. חשוב לזכור להוסיף את מאפיין ההרשאה באופן מפורש לתג iframe. אם יש iframe נוסף עם <iframe src="https://ad.example" allow="geolocation">, ל-https://ad.example לא תהיה גישה לתכונת המיקום הגיאוגרפי. רק לדף המקורי ול-https://trusted-site.example שמופיעים ברשימת המקורות, יחד עם מאפיין ההרשאה שבתג ה-iframe, תהיה גישה לתכונה של המשתמש.

אפשר לראות את ההגדרות האלה בהדגמה.

התכונה חסומה בכל המקורות

Permissions-Policy: geolocation=()

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

שימוש ב-JavaScript API

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

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

featurePolicy.allowsFeature(feature)

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

featurePolicy.allowsFeature(feature, מקור)

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

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

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)

אם משתמשים ב-method document.allowsFeature(feature, origin) כדי לבדוק תכונות מורשות ל-iframes, צריך להשתמש בשיטה 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 להפרות מדיניות הרשאות זמין כתכונה ניסיונית.

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

למידע נוסף

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

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