עדכונים של FedCM: גרסאות מקור לניסיון של חבילת Continuation API והענקה אוטומטית של Storage Access API

Eiji Kitamura

החל מגרסה 126 של Chrome, מפתחים יכולים להתחיל להריץ גרסת מקור לניסיון של חבילה של תכונות של Desktop Federated Credential Management API (FedCM) שמאפשרות הפעלה של חלק תרחישים לדוגמה של הרשאות. החבילה כוללת את ממשק ה-API להמשיך Parameters API, שמאפשרים חוויה דמוית תהליך הרשאה ב-OAuth תיבת דו-שיח עם הרשאה שמספקת ספק זהויות (IdP). החבילה גם הדוח כולל שינויים נוספים, כגון Fields API, מספר configURLs ו-Custom תוויות חשבון. החל מגרסה 126 של Chrome, אנחנו משיקים גם גרסת מקור לניסיון עבור Storage Access API (SAA) שנותן בקשות SAA באופן אוטומטי אם המשתמש התחברת בהצלחה באמצעות FedCM בעבר.

גרסת מקור לניסיון: חבילת FedCM Continuation API

חבילת FedCM Continuation API מורכבת מכמה תוספי FedCM:

• Continuation API
• Parameters API
• Fields API
• כתובות URL עם כמה הגדרות אישיות
• תוויות חשבון בהתאמה אישית

ממשק API של המשך

משתמש נכנס לגורם מוגבל (RP) ואז מאשר אותו במצב הלחצן.

אפשר לעיין בהדגמה של ה-API ב-Glitch.

Continuation API מאפשר טענת נכוֹנוּת (assertion) של המזהה (IdP) ב-IdP" נקודת קצה (endpoint) אופציונלי: החזרת כתובת URL ש-FedCM יציג כדי לאפשר למשתמש להמשיך תהליך כניסה עם מספר שלבים. כך ה-IdP יכול לבקש מהמשתמש להעניק את הרשאות צד נסמך (RP) מעבר למה שאפשר להשתמש בממשק המשתמש הקיים של FedCM, כמו גישה למשאבים של המשתמש בצד השרת.

בדרך כלל, נקודת הקצה של טענת הנכוֹנוּת (assertion) של המזהה מחזירה אסימון שנדרש אימות.

{
  "token": "***********"
}

עם זאת, באמצעות ממשק ה-API של ההמשך, טענת הנכונות (assertion) של המזהה נקודת קצה (endpoint) יכולה מחזירה נכס continue_on שכולל נתיב מוחלט או יחס נתיב לנקודת הקצה של טענת הנכוֹנוּת (assertion) של המזהה.

{
  // In the id_assertion_endpoint, instead of returning a typical
  // "token" response, the IdP decides that it needs the user to
  // continue on a pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

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

אחרי האינטראקציה של המשתמש עם הדף, למשל מתן הרשאה נוספת כדי לשתף מידע נוסף עם ה-RP, דף ה-IdP יכול להפעיל IdentityProvider.resolve() כדי לתקן את הבעיה המקורית הקריאה navigator.credentials.get() ומחזירה אסימון כארגומנט.

document.getElementById('allow_btn').addEventListener('click', async () => {
  let accessToken = await fetch('/generate_access_token.cgi');
  // Closes the window and resolves the promise (that is still hanging
  // in the relying party's renderer) with the value that is passed.
  IdentityProvider.resolve(accessToken);
});

הדפדפן יסגור את החלון הקופץ בעצמו ויחזיר את האסימון ל-API של הקריאה החוזרת.

אם המשתמש ידחה את הבקשה, אפשר לסגור את החלון באמצעות קריאה IdentityProvider.close()

IdentityProvider.close();

הערה: החלון הקופץ מתנהג כאילו noopener, noreferrer שצוין (כך, window.opener הוא null) ואין דרך כלשהי עבור חלון ההורה (RP) והחלון הקופץ (IdP) לאינטראקציה זה עם זה. הדרך היחידה לתקשר צריכה להיות IdentityProvider.resolve() חד פעמית קריאה נוספת, שסוגרת גם את החלון הקופץ.

הערה: אפשר להשתמש ב-Continuation API רק כשיש אינטראקציה של המשתמש (קליקים מפורשים). לכן, המשתמש נדרש לבחור חשבון מצב ווידג'ט (עם mediation: 'required'), או בלחצן מצב (שתמיד דורשת הפעלה של המשתמש). אבל החלון הקופץ הזה לא מורשה mediation: silent למצב ווידג'ט של mediation: optional שה-API מחפש הפעלה זמנית של המשתמש אם מופעל אימות אוטומטי מחדש. אחרת, לא נפתח חלון קופץ, וההבטחה נדחית.

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

IdentityProvider.resolve(token, {accountId: '1234');

ממשק API של פרמטרים

Parameters API מאפשר לגורם המוגבל כדי לספק פרמטרים נוספים לטענת הנכונות (assertion) של המזהה נקודת קצה (endpoint). באמצעות Parameters API, גורמים מוגבלים יכולים להעביר פרמטרים נוספים ל-IdP כדי לבקש הרשאות למשאבים שמעבר לכניסה הבסיסית. המשתמש יאשר את ההרשאות האלה באמצעות תהליך חוויית משתמש בשליטת ה-IdP שמופעל דרך ממשק API של המשך.

כדי להשתמש ב-API, צריך להוסיף פרמטרים למאפיין params כאובייקט ב- שיחת navigator.credentials.get().

let {token} = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      // Key/value pairs that need to be passed from the
      // RP to the IdP but that don't really play any role with
      // the browser.
      params: {
        IDP_SPECIFIC_PARAM: '1',
        foo: 'BAR',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

לפני שמות המאפיינים באובייקט params מצורפים param_. ב שלמעלה לדוגמה, מאפיין הפרמטרים מכיל IDP_SPECIFIC_PARAM בתור '1', foo בתור 'BAR', ETC בתור 'MOAR' ו-scope בתור 'calendar.readonly photos.write'. הטקסט הזה יתורגם ל- param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write בגוף ה-HTTP של הבקשה:

POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

קבלת הרשאות באופן דינמי

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

כדי לבקש הרשאה באופן דינמי באמצעות FedCM, ה-IdP יכול:

1. קוראים לפונקציה navigator.credentials.get() עם הפרמטרים הנדרשים שה-IdP יכול כמו scope.
2. טענת נכוֹנוּת (assertion) של המזהה נקודת קצה (endpoint) מאשרת שהמשתמש כבר מחובר ומגיב עם כתובת URL מסוג continue_on.
3. הדפדפן פותח חלון קופץ עם דף ההרשאות של ה-IdP שבו מופיעה בקשה הרשאה נוספת שתואמת להיקפים המבוקשים.
4. אחרי קבלת ההרשאה מה-IdP של IdentityProvider.resolve(), החלון נסגרה והשיחה המקורית navigator.credentials.get() של הגורם המוגבל (RP) מקבלת באסימון רלוונטי או בקוד הרשאה, כדי שהגורם המוגבל (RP) יוכל להחליף אותם אסימון גישה מתאים.

ממשק API של Fields

Fields API מאפשר ל-RP: להצהיר על מאפייני חשבון לבקש מה-IdP כדי שהדפדפן יוכל לרנדר ממשק משתמש מתאים לגילוי נאות בתיבת הדו-שיח של FedCM. באחריות ה-IdP כדי לכלול את השדות המבוקשים באסימון המוחזר. כדאי לשקול את הבקשה 'פרופיל בסיסי' ב-OpenID Connect לעומת 'היקפים' ב-OAuth.

הודעת גילוי נאות במצב ווידג'ט.

הודעת גילוי נאות במצב לחצן.

כדי להשתמש ב-Fields API, צריך להוסיף פרמטרים לנכס fields כמערך שיחת navigator.credentials.get(). השדות יכולים להכיל את השדות 'name', 'email' ו-'picture' כרגע, אבל ניתן להרחיב כדי לכלול ערכים נוספים העתידי.

בקשה עם fields תיראה כך:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

בקשת ה-HTTP לטענת הנכונות (assertion) של המזהה נקודת קצה (endpoint) כולל את הפרמטר fields שצוין על ידי RP, עם disclosure_text_shown מוגדר כ-true אם זה לא משתמש חוזר, והשדות דפדפן שנמסר למשתמש בפרמטר disclosure_shown_for:

POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

הערה: בשלב הזה, Chrome מחזיר הודעת חריג, אלא אם הגורם המוגבל (RP) מבקש fields: ['name', 'email', 'picture'], או שום דבר לגבי fields: []. בעתיד, דפדפן Chrome ישפר את היכולות של ממשק המשתמש לבקש ויתחיל לקבל קבוצות משנה של הערכים האלה.

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

אם fields הוא מערך ריק, הבקשה תיראה כך:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

אם fields הוא מערך ריק, סוכן המשתמש ידלג על ממשק המשתמש של הגילוי הנאות.

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

גם אם תתקבל ממך תגובה בחשבונות נקודת קצה (endpoint) לא מכיל מזהה לקוח שתואם ל-RP ב-approved_clients.

במקרה הזה, השדה disclosure_text_shown נשלח אל טענת הנכוֹנוּת (assertion) של המזהה נקודת הקצה היא FALSE בגוף HTTP:

POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false

מספר configURLs

כמה הגדרות אישיות מאפשרות לספקי IdP כדי לכלול קובצי תצורה מרובים ל-IdP, על ידי ציון accounts_endpoint ו-login_url בשפה זהים בקובץ בתור קובצי התצורה.

אם מוסיפים את accounts_endpoint ואת login_url לקובץ הידוע, המערכת מתעלמת מ-provider_urls כדי שה-IdP יוכל לתמוך בכמה קובצי תצורה. אם לא, provider_urls ימשיך לפעול כך שהוא לאחור תואמת.

הקובץ הידוע שתומך בכמה כתובות URL של config יכול להיראות כך:

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

הפעולה הזאת מאפשרת לנו:

1. לשמור על תאימות אחורה וקדימה עם קבצים ידועים קיימים. ובגרסה הקודמת של דפדפנים שכבר פרוסים ברחבי העולם.
2. לכלול מספר שרירותי של קובצי תצורה - כל עוד כולם מצביעים על אותם accounts_endpoint ו-login_url.
3. לא קיימת הזדמנות להוסיף את האנטרופיה לבקשת האחזור עם פרטי הכניסה בוצע לaccounts_endpoint, מכיוון שצריך לציין אותו ב " .well-known" ברמה.

התמיכה במספר כתובות URL של config היא אופציונלית וה-FedCM הקיים הוא אופציונלי יכולים להישאר ללא שינוי.

תוויות חשבון מותאמות אישית

תוויות חשבון מותאמות אישית מאפשרות FedCM ספקי IdP כדי להוסיף הערות לחשבונות, כדי שהגורמים המוגבלים (RP) יוכלו לסנן אותם על ידי ציון התווית קובץ תצורה. ניתן לבצע סינון דומה באמצעות Domain Hint API והתחברות Hint API באמצעות ציון אלא בשיחה navigator.credentials.get(), אבל בתוויות של חשבון בהתאמה אישית יכול לסנן משתמשים על ידי ציון קובץ התצורה. קובץ התצורה הזה שימושי במיוחד כאשר נעשה שימוש במספר כתובות URL של config. תוויות חשבון מותאמות אישית הן גם שונה בכך שהם מסופקים משרת ה-IdP, לעומת הגורם המוגבל, כמו רמזים להתחברות או לדומיין.

דוגמה

IdP שתומך בשתי כתובות URL config לצרכנים ולארגון, בהתאמה. קובץ התצורה של הצרכן כולל את התווית 'consumer', וקובץ התצורה של הארגון מכיל את התווית 'enterprise'.

עם הגדרה כזו, הקובץ המוכר כולל את accounts_endpoint ואת login_url כדי לאפשר מספר כתובות URL של config.

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

כשמזינים את ה-accounts_endpoint בקובץ הידוע, המערכת מתעלמת מ-provider_urls. הגורם המוגבל (RP) יכול להפנות ישירות להגדרה המתאימה קבצים בשיחה navigator.credentials.get().

קובץ התצורה של הצרכן נמצא ב-https://idp.example/fedcm.json, וכולל מאפיין accounts שמציין את 'consumer' באמצעות include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

קובץ התצורה של הארגון נמצא ב-https://idp.example/enterprise/fedcm.json, שכולל את המאפיין accounts שמציין את 'enterprise' באמצעות include

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

חשבונות IdP נפוצים נקודת קצה (endpoint) (בדוגמה הזו, https://idp.example/accounts) מחזירה רשימה של חשבונות כולל מאפיין תוויות עם labels שהוקצה במערך לכל חשבון. הדוגמה הבאה היא תשובה למשתמש שיש לו שני חשבונות. האחד הוא עבור לצרכן, והשני הוא לארגון:

{
 "accounts": [{
   "id": "123",
   "given_name": "John",
   "name": "John Doe",
   "email": "[e-mail]",
   "picture": "https://idp.example/profile/123",
   "labels": ["consumer"]
  }], [{
   "id": "4567",
   "given_name": "Jane",
   "name": "Jane Doe",
   "email": "[e-mail]",
   "picture": "https://idp.example/profile/4567",
   "labels": ["enterprise"]
  }]
}

כשגורם מוגבל (RP) רוצה לאפשר למשתמשי 'enterprise' להיכנס לחשבון, הוא יכול לציין 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' ב שיחת navigator.credentials.get():

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      nonce: '234234',
      configURL: 'https://idp.example/enterprise/fedcm.json',
    },
  }
});

כתוצאה מכך, רק מספר החשבון של '4567' זמין לחתימה אינץ' מספר החשבון של '123' מוסתר על ידי הדפדפן בצורה שקטה, כדי שהמשתמש לא יסופק עם חשבון שאינו נתמך על ידי ה-IdP באתר הזה.

הערה:

• תוויות הן מחרוזות. אם המערך labels או השדה include מכיל משהו שאינו מחרוזת, הוא המערכת מתעלמת ממנו.
• אם לא יצוינו תוויות ב-configURL, כל החשבונות שמוצגות בבורר החשבונות של FedCM.
• אם לא יצוינו תוויות לחשבון, הן יוצגו רק Account Chooser אם ה-configURL גם לא מציין תווית.
• אם אין חשבון שתואם לתווית המבוקשת בתהליך הווידג'ט (בדומה ל- Domain Hint API) בתיבת הדו-שיח של FedCM מוצגת בקשת התחברות שמאפשרת למשתמש כדי להתחבר לחשבון IdP. לצורך זרימת הלחצנים, החלון הקופץ להתחברות פתיחה ישירה.

גרסת מקור לניסיון: FedCM כאות אמון ל-Storage Access API

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

האפשרות הזו שימושית כש-iframe מוטמע רוצה לגשת למשאבים מותאמים אישית: לדוגמה, אם הפרמטר idp.example מוטמע ב-rp.example וצריך להציג בו מקור מידע בהתאמה אישית. אם הדפדפן מגביל את הגישה לקובצי Cookie של צד שלישי, גם אם המשתמש מחובר ל-rp.example באמצעות idp.example עם FedCM, ל-iframe של idp.example המוטמע לא תהיה אפשרות לבקש משאבים מותאמים אישית כי הבקשות לא יכללו קובצי Cookie של צד שלישי.

כדי לעשות זאת, idp.example צריכה לקבל הרשאת גישה לאחסון דרך את iframe מוטמע באתר, וניתן לקבל אותו רק באמצעות של בקשת ההרשאה.

עם FedCM כאות אמון בגישה לאחסון API, בדיקות ההרשאה Storage Access API לא רק מקבלות את הענקת ההרשאה ניתנת על ידי בקשה לגישה לאחסון, אבל גם על ידי מתן ההרשאה הודעת FedCM.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

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

הערה: כדי לאפשר ל-iframe מוטמע של IdP לקבל גישה לאחסון באופן אוטומטי למרות FedCM עצמו לא מופעל בתוך ה-iframe, ה-RP צריך להוסיף באופן מפורש הרשאות FedCM identity-credentials-get .

השתתפות בגרסת המקור לניסיון

אפשר לנסות את חבילת FedCM Continuation API באופן מקומי על ידי הפעלת Chrome דגל chrome://flags#fedcm-authz ב-Chrome מגרסה 126 ואילך. אפשר גם לנסות את FedCM בתור אות אמון ל-Storage Access API באופן מקומי, על ידי הפעלת #fedcm-with-storage-access-api ב-Chrome מגרסה 126 ואילך.

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

כדי לנסות את מקור החבילה של FedCM Continuation API תקופת ניסיון, ליצור שני אסימוני מקור לניסיון:

• נרשמים לתקופת הניסיון. הטמעת האסימון ב-IdP origin.
• נרשמים לתקופת הניסיון של המקור כשתיבת הסימון של התאמה של צד שלישי מסומנת. פועלים לפי ההוראות במאמר רישום מקור לניסיון של צד שלישי עבור RP כדי להטמיע את האסימון של הגורם המוגבל.

אם אתם רוצים להפעיל את Continuation API יחד עם הלחצן זרימה, הפעלת מצב הלחצן מקור ה-API תקופת ניסיון וגם:

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

כדי לנסות את FedCM בתור אות אמון במקור של Storage Access API תקופת ניסיון:

• נרשמים לגרסת המקור לניסיון. הטמעת האסימון ב-IdP origin.

גרסת המקור לניסיון של חבילת ה-Continue API וה-FedCM כאות אמון עבור גרסת המקור לניסיון של Storage Access API זמינה החל מ-Chrome 126.

רישום גרסת מקור לניסיון של צד שלישי ל-RP

1. עוברים לדף הרישום לגרסת המקור לניסיון.
2. לוחצים על הלחצן Register וממלאים את הטופס כדי לבקש אסימון.
3. מזינים את מקור ה-IdP בתור מקור אינטרנט.
4. בדיקת התאמות של צד שלישי כדי להחדיר את האסימון עם JavaScript במקורות אחרים.
5. לוחצים על שליחה.
6. מטמיעים את האסימון שהונפק באתר של צד שלישי.

כדי להטמיע את האסימון באתר של צד שלישי, צריך להוסיף את הקוד הבא ספריית JavaScript או SDK שמוצגים מהמקור של ה-IdP.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

מחליפים את TOKEN_GOES_HERE באסימון שלכם.

הערה: אם ה-RP מופעל על ידי FedCM API, ולא דרך סקריפט שנטען מה-IdP, ה-RP חייבים לרשום את המקור בעצמם ולהפעיל גרסת מקור לניסיון של צד ראשון.