מדריך למפתחים בנושא Private State Tokens

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

ה-API של Private State Tokens מאפשר לשתף מידע באינטרנט, אבל תוך שמירה על הפרטיות באמצעות אמצעים לבקרה על כמות הנתונים שאפשר לשתף בפועל.

אסימוני מצב פרטי (לשעבר אסימוני מהימנות) מאפשרים להעביר את המהימנות של אותנטיות המשתמש מהקשר אחד להקשר אחר, ועוזרים לאתרים להילחם בהונאות ולהבחין בין בוטים לבין בני אדם אמיתיים – ללא מעקב פסיבי.

במסמך הזה מפורטים הפרטים הטכניים להטמעה של Private State Tokens (PST). בסקירה הכללית על PST מופיע תיאור כללי יותר.

איך פועלים טוקנים של מצב פרטי?

הקשר המרכזי שחשוב להבין ב-PST הוא בין המנפיקים לבין מי שמממשים את האסימונים. המנפיקים והמממשים יכולים להיות באותה חברה.

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

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

האם טוקנים של מצב פרטי מתאימים לי?

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

הנפקת טוקנים ומימושם

ההטמעה של PST מתבצעת בשלושה שלבים:

1. הנפקת טוקנים
2. מימוש טוקנים
3. העברת רשומות פדיון

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

הגדרת אסטרטגיית הטוקנים

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

מה הקשר בין טוקנים לבין רשומות מימוש?

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

כשמממשים אסימון, רשומת המימוש (RR) מאוחסנת במכשיר. האחסון הזה משמש כמטמון למימוש עתידי. יש הגבלה של מימוש שני אסימונים כל 48 שעות לכל מכשיר, דף ומונפק. קריאות חדשות למימוש ישתמשו ב-RR שנשמרו במטמון במידת האפשר, במקום לגרום לבקשה למוציא.

1. מונפקים טוקנים חדשים (עד 500 לכל מנפיק, אתר ומכשיר).
2. כל הטוקנים מאוחסנים במאגר הטוקנים במכשיר (בדומה למאגר קובצי Cookie).
3. אם לא נמצא RR פעיל, אפשר ליצור RR חדשים אחרי ההנפקה (עד 2 כל 48 שעות).
4. רשומות RR נחשבות פעילות עד שהן פגות, והן ישמשו כמטמון מקומי.
5. קריאות חדשות למימוש שוברים יגיעו למטמון המקומי (לא ייווצרו בקשות חדשות למימוש שוברים).

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

לפני שמגדירים את האסטרטגיה, חשוב להבין את ההתנהגויות והמשתנים הקריטיים הבאים:

תרחישים לדוגמה

תרחיש מספר 1: משך החיים של ה-RR הוא פחות מ-24 שעות (t=t) והמימוש מתבצע מספר פעמים במהלך חלון 48 השעות.

תרחיש מספר 2: משך החיים של קוד ה-RR הוא 24 שעות והמימוש מתבצע מספר פעמים במהלך חלון הזמן של 48 שעות.

תרחיש מספר 3: משך החיים של קוד ה-RR הוא 48 שעות והמימוש מתבצע מספר פעמים במהלך חלון הזמן של 48 השעות.

הפעלת ההדגמה

לפני שמתחילים להשתמש ב-PST, מומלץ להגדיר את הדמו.

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

שיקולים טכניים

כדי שההדגמה תפעל בצורה הטובה ביותר, צריך לבצע את השלבים הבאים:

• חשוב לוודא שכל המופעים של Chrome הופסקו לפני שמריצים את Chrome עם תכונות ניסיוניות.
• אם אתם משתמשים במחשב Windows, כדאי לעיין במדריך הזה כדי ללמוד איך להעביר פרמטרים לקובץ ההרצה הבינארי של Chrome.
• פותחים את כלי הפיתוח ל-Chrome בקטע Applications > Storage > Private State Tokens בזמן השימוש באפליקציית ההדגמה כדי לראות את האסימונים שהונפקו או שמומשו על ידי מנפיק ההדגמה.

הגדרת תהליך האימוץ

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

איך הופכים למנפיקים

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

כדי להגיש בקשה להפוך למונפק, המפעיל של אתר המנפיק צריך לפתוח בעיה חדשה במאגר GitHub באמצעות התבנית New PST Issuer (מנפיק חדש של PST). פועלים לפי ההנחיות במאגר כדי למלא את הבעיה. אחרי שנקודת קצה מאומתת, היא תמוזג במאגר הזה והתשתית בצד השרת של Chrome תתחיל לאחזר את המפתחות האלה.

שרתי הנפקה

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

פריסת הסביבה: שרתי מנפיקים

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

רכיב המנפיק מורכב משני מודולים עיקריים: (1) שרת המנפיק ו-(2) מנפיק האסימונים.

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

1. שרת המנפיק: בהטמעה לדוגמה שלנו, שרת ההנפקה הוא שרת Node.js שמשתמש ב-Express framework כדי לארח את נקודות הקצה של HTTP של המנפיק. אפשר לעיין בקוד לדוגמה ב-GitHub.

2. הנפקת טוקנים: רכיב ההצפנה של הנפקת הטוקנים לא דורש שפה ספציפית, אבל בגלל דרישות הביצועים של הרכיב הזה, אנחנו מספקים הטמעה ב-C כדוגמה, שמשתמשת בספריית BoringSSL לניהול טוקנים. דוגמה לקוד של מנפיק ומידע נוסף על ההתקנה זמינים ב-GitHub

3. מפתחות: רכיב הנפקת הטוקנים משתמש במפתחות EC מותאמים אישית כדי להצפין טוקנים. המפתחות האלה צריכים להיות מוגנים ומאוחסנים באחסון מאובטח.

דרישות טכניות לשרתי המנפיק

בהתאם לפרוטוקול, תצטרכו להטמיע לפחות שתי נקודות קצה (endpoint) של HTTP בשרת המנפיק:

• התחייבות למפתח (לדוגמה, /.well-known/private-state-token/key-commitment): בנקודת הקצה הזו, פרטי המפתח הציבורי של ההצפנה יהיו זמינים לדפדפנים כדי לאשר שהשרת שלכם לגיטימי.
  • דוגמת קוד ב-GitHub
  • לצפייה בהדגמה
• הנפקת טוקן (לדוגמה, /.well-known/private-state-token/issuance): נקודת הקצה להנפקת טוקן שבה יטופלו כל בקשות הטוקן. נקודת הקצה הזו תהיה נקודת השילוב של רכיב הנפקת האסימונים.
  • דוגמת קוד ב-GitHub
  • לצפייה בהדגמה

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

שליחת שיחה לשרת המוסד המנפיק

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

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

דוגמה לקוד

שרתי מימוש

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

אפשר להפעיל את הגורם המנפיק ואת הגורם המממש באותו שרת (או באותה קבוצת שרתים).

דרישות טכניות לשרתים של מימוש שוברים

בהתאם לפרוטוקול, תצטרכו להטמיע לפחות שתי נקודות קצה (endpoint) של HTTP בשרת המימוש:

• ‫/.well-known/private-state-token/redemption: נקודת הקצה שבה יטופל כל מימוש האסימונים. נקודת הקצה הזו היא המקום שבו ישולב רכיב מימוש האסימון
  • קוד לדוגמה ב-GitHub
  • הדגמה

שליחת שיחה לשרת המימוש

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

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

דוגמת קוד

אחרי מימוש של טוקן, אפשר לשלוח את רשומת המימוש (RR) על ידי ביצוע עוד קריאת אחזור:

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

דוגמת קוד

פריסת ההטמעה

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

פריסה בעולם האמיתי

מומלץ לבחור אתרי טירגוט שרלוונטיים לתרחיש השימוש הספציפי שלכם:

• מספר קטן של ביקורים חודשיים (עד מיליון ביקורים בחודש): מומלץ להתחיל בפריסת ה-API לקהל קטן
• הבעלות והשליטה בידיכם: אם צריך, אפשר להשבית במהירות את ההטמעה בלי אישורים מורכבים
• לא יותר מגורם מנפיק אחד: כדי להגביל את מספר הטוקנים וכך לפשט את הבדיקה.
• לא יותר משני מממשים: כדי לפשט את פתרון הבעיות במקרה של בעיות.

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

כדי ש-PST API יפעל בצורה תקינה, הוא צריך להיות זמין לדף ברמה העליונה ולכל משאבי המשנה שמשתמשים ב-API.

הפעולה של בקשת הטוקן נשלטת על ידי ההנחיה private-state-token-issuance. הפעולות token-redemption ו-send-redemption-record נשלטות על ידי ההנחיה private-state-token-redemption. ב-Chrome 132 ובגרסאות מתקדמות יותר, רשימת ההיתרים של ההנחיות האלה מוגדרת כ-* (כל המקורות) כברירת מחדל. המשמעות היא שהתכונה זמינה לדף ברמה העליונה, לרכיבי iframe מאותו מקור ולרכיבי iframe ממקורות שונים ללא העברה מפורשת של הרשאות.

כדי להפסיק להנפיק או לממש אסימוני PST בדפים ספציפיים באתר, צריך לכלול את private-state-token-issuance=() ואת private-state-token-redemption=() בכותרת Permissions-Policy של כל דף.

אפשר גם להשתמש בכותרת Permissions-Policy כדי לשלוט בגישה של צדדים שלישיים ל-PST. כפרמטרים לרשימת המקורות של הכותרת, משתמשים ב-self ובכל המקורות שרוצים לאפשר להם גישה ל-API. לדוגמה, כדי להשבית לחלוטין את השימוש ב-PST בכל הקשרי הגלישה, למעט המקור שלכם ו-https://example.com, מגדירים את כותרות התגובה הבאות של HTTP:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

כדי להפעיל את ה-API לכל המשאבים ממקורות שונים, מגדירים את רשימת המקורות ל-*.

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

פתרון בעיות

אפשר לבדוק את ה-PST בכרטיסיות 'רשת' ו'אפליקציה' בכלי הפיתוח ל-Chrome.

בכרטיסייה 'רשת':

בכרטיסייה 'בקשה':

מידע נוסף על השילוב הזה של כלי הפיתוח

שיטות מומלצות ללקוחות

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

מספר המנפיקים לכל רמה עליונה מוגבל לשניים, וסקריפטים של צד שלישי עשויים גם לנסות לקרוא ל-hasPrivateToken(issuer) כדי לתת עדיפות למנפיקים המועדפים שלהם. לכן, חשוב לאבטח מראש את המנפיקים החיוניים כדי לוודא שהאתר פועל כמצופה.

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

שיטות מומלצות לשימוש בשרת ופתרון בעיות

כדי שהשרת של מנפיק ה-PST והשרת של מי שמשתמש ב-PST יפעלו בצורה יעילה, מומלץ ליישם את השיטות המומלצות הבאות כדי למנוע בעיות בגישה, באבטחה, ברישום ביומן או בתנועה של PST.

• נקודות הקצה צריכות להשתמש בהצפנה חזקה באמצעות TLS 1.3 או 1.2.
• התשתית שלכם צריכה להיות מוכנה לטפל בנפחי תנועה משתנים (כולל עליות חדות).
• חשוב לוודא שהמפתחות מוגנים ומאובטחים, בהתאם למדיניות בקרת הגישה, לאסטרטגיית ניהול המפתחות ולתוכניות לשימור ההמשכיות העסקית.
• כדאי להוסיף מדדי יכולת צפייה לסט הטכנולוגיות כדי לוודא שתהיה לכם אפשרות להבין את השימוש, צווארי הבקבוק ובעיות הביצועים אחרי המעבר לסביבת הייצור.

מידע נוסף

1. עיון במסמכי התיעוד למפתחים:
   1. כדאי להתחיל בקריאת סקירה כללית כדי להבין מה זה PST ומה היכולות שלו.
   2. מומלץ לצפות בסרטון ההקדמה בנושא PST.
   3. אפשר לנסות את ההדגמה של PST.
   4. כדאי גם לקרוא את ההסבר על ה-API כדי לקבל פרטים נוספים.
   5. מידע נוסף על המפרט הנוכחי של ה-API
2. אתם יכולים להשתתף בדיון באמצעות בעיות ב-GitHub או שיחות ב-W3C.
3. כדי להבין טוב יותר את המונחים, מומלץ לעיין במילון המונחים של ארגז החול לפרטיות.
4. כדי לקבל מידע נוסף על מושגים ב-Chrome, כמו 'גרסת מקור לניסיון' או 'דגלים של Chrome', אפשר לעיין בסרטונים ובמאמרים הקצרים שזמינים בכתובת goo.gle/cc.