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

ניהול הגישה של הדף ושל תגי 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. אם התשובה לא תכיל כותרת Permissions Policy, רשימת המקור נחשבת כערך ברירת המחדל של *. הוספת המאפיין allow ל-iframe מאפשרת גישה לתכונה.

לכן, אנחנו ממליצים למפתחים להגדיר במפורש את הכותרת Permissions Policy בתגובה, כדי ש-iframes ממקורות שונים שלא מופיעים ברשימת המקור ייחסמו לגישה לתכונה הזו, גם אם 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) שלא נוסף לרשימת המקור, ושהמאפיין allow מוגדר בתג 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 (מדיניות ההרשאות), ואז הדפדפן מעניק גישה על סמך הכותרת הזו.

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 מנווט. במאפיין 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 למדיניות שהוגדרה על ידי מדיניות ההרשאות, עם מגבלות מסוימות. יש שאלות נוספות לגבי הטמעת JavaScript API, והצעה להעביר את הלוגיקה ל-Permissions API. אם יש לכם משהו להוסיף, אתם מוזמנים להצטרף לדיון.

featurePolicy.allowsFeature(feature)

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

featurePolicy.allowsFeature(feature, origin)

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

featurePolicy.features()

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

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

שילוב של כלי הפיתוח ל-Chrome עם מדיניות ההרשאות

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

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

העברה מ-Feature-Policy

אם משתמשים בכותרת 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 להפרות מדיניות הרשאות זמין כתכונה ניסיונית.

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

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

למידע נוסף

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