עדכונים של FedCM: API לסטטוס התחברות, Error API וממשק API לסימון שנבחר באופן אוטומטי

מערכת Chrome 120 שולחת את ה-Login Status API עבור FedCM. ה-API של סטטוס ההתחברות (שנקרא בעבר IdP Signin Status API) מאפשר לאתרים, במיוחד לספקי זהויות, לאותת לדפדפן כשהמשתמשים מתחברים ויוצאים. FedCM משתמש באות הזה כדי לטפל בבעיה של התקפת תזמון שקטה, וכך הוא מאפשר ל-FedCM לפעול ללא קובצי cookie של צד שלישי. העדכון הזה מטפל בשינויים האחרונים שעדיין לא תואמים לאחור, שזיהינו בעבר בכוונת הרכישה המקורית של FedCM, כחלק מהיקף העבודה שלנו.

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

כמו כן, תקבלו ב-Chrome שתי תכונות חדשות של ניהול פרטי כניסה מאוחד (FedCM):

  • Error API: יש להודיע למשתמשים אם ניסיון הכניסה שלהם נכשל בממשק משתמש מקורי, על סמך תגובת השרת מנקודת הקצה של טענת הנכוֹנוּת (assertion) של המזהה, אם יש כזו.
  • Auto-Selected flags API: מודיע לספק הזהויות (IdP) ולצד המסתמך (RP) אם פרטי הכניסה נבחרו באופן אוטומטי בתהליך.

ממשק API לסטטוס התחברות

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

שליחת הודעה לדפדפן לגבי סטטוס ההתחברות של המשתמש

מזהי ה-IdP יכולים לאותת את סטטוס ההתחברות של המשתמשים לדפדפן על ידי שליחת כותרת HTTP או באמצעות קריאה ל-JavaScript API כשהמשתמש מחובר ל-IdP או כשמשתמש מנותק מכל חשבונות ה-IdP שלו. לכל IdP (שמזוהה לפי כתובת ה-URL להגדרה שלו), הדפדפן שומר משתנה תלת-מצבי שמייצג את מצב ההתחברות עם הערכים האפשריים logged-in, logged-out ו-unknown. מצב ברירת המחדל הוא unknown.

כדי לסמן שהמשתמש מחובר, צריך לשלוח כותרת HTTP מסוג Set-Login: logged-in בניווט ברמה העליונה או בבקשה למשאב משנה מאותו מקור:

Set-Login: logged-in

לחלופין, אפשר לקרוא ל-JavaScript API navigator.login.setStatus('logged-in') ממקור ה-IdP:

navigator.login.setStatus('logged-in');

השיחות האלה מתעדות את סטטוס ההתחברות של המשתמש בתור logged-in. כשסטטוס ההתחברות של המשתמש מוגדר כ-logged-in, הגורם המוגבל שקורא ל-FedCM לשלוח בקשות לנקודת הקצה של רשימת החשבונות של ה-IdP, ומציג למשתמש חשבונות זמינים בתיבת הדו-שיח של FedCM.

כדי לסמן שהמשתמש לא מחובר לכל החשבונות שלו, צריך לשלוח את כותרת ה-HTTP Set-Login: logged-out בניווט ברמה העליונה או בבקשת משאב משנה של אותו מקור:

Set-Login: logged-out

לחלופין, אפשר לקרוא ל-JavaScript API navigator.login.setStatus('logged-out') מהמקור של ה-IdP:

navigator.login.setStatus('logged-out');

השיחות האלה מתעדות את סטטוס ההתחברות של המשתמש בתור logged-out. כשסטטוס ההתחברות של המשתמש הוא logged-out, ההפעלה של FedCM נכשלת בלי לשלוח בקשה לנקודת הקצה (endpoint) של רשימת החשבונות של ה-IdP.

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

  • אם נקודת הקצה מחזירה רשימה של חשבונות פעילים, מעדכנים את הסטטוס ל-logged-in ופותחים את תיבת הדו-שיח של FedCM כדי להציג את החשבונות האלה.
  • אם נקודת הקצה לא מחזירה חשבונות, מעדכנים את הסטטוס ל-logged-out ונכשלים בקריאה של FedCM.

מה אם תוקף הסשן של המשתמש פג? צריך לאפשר למשתמש להיכנס בתהליך התחברות דינמי!

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

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

תיבת דו-שיח של FedCM עם הצעה להיכנס ל-IdP.
תיבת דו-שיח של FedCM עם הצעה להיכנס ל-IdP.

כשהמשתמש לוחץ על הלחצן Continue (המשך) בדפדפן, נפתחת תיבת דו-שיח לדף ההתחברות של ה-IdP.

תיבת דו-שיח לדוגמה.
תיבת דו-שיח לדוגמה שמוצגת אחרי לחיצה על לחצן הכניסה ללחצן ה-IdP.

כתובת ה-URL של דף ההתחברות מצוינת ב-login_url כחלק מקובץ התצורה של IdP.

{
  "accounts_endpoint": "/auth/accounts",
  "client_metadata_endpoint": "/auth/metadata",
  "id_assertion_endpoint": "/auth/idtokens",
  "login_url": "/login"
  }
}

תיבת הדו-שיח היא חלון דפדפן רגיל עם קובצי cookie מהדומיין הנוכחי. כל מה שקרה בתיבת הדו-שיח תלוי ב-IdP, ואין נקודות אחיזה שזמינות לחלון לשליחת בקשת תקשורת ממקורות שונים לדף ה-RP. אחרי שהמשתמשים מחוברים, ה-IdP צריך:

  • צריך לשלוח את הכותרת Set-Login: logged-in או לבצע קריאה ל-navigator.login.setStatus("logged-in") API כדי להודיע לדפדפן שהמשתמש נכנס לחשבון.
  • צריך לקרוא ל-IdentityProvider.close() כדי לסגור את תיבת הדו-שיח.
משתמש נכנס ל-RP אחרי שהוא נכנס ל-IdP באמצעות FedCM.
משתמש נכנס ל-RP אחרי שהוא נכנס ל-IdP באמצעות FedCM.

תוכלו לנסות את ההתנהגות של Login Status API בהדגמה.

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

צריכה להיות לכם אפשרות לראות את ההתחברות ל-IdP דרך ההתנהגות של המודול.

ממשק API לשגיאה

כש-Chrome שולח בקשה לנקודת הקצה של טענת הנכוֹנוּת (assertion) של המזהה (לדוגמה, כשמשתמש לוחצים על הלחצן Continue as בממשק המשתמש של FedCM או שמופעל אימות אוטומטי), יכול להיות שה-IdP לא יוכל להנפיק אסימון מסיבות לגיטימיות. לדוגמה, אם הלקוח לא מורשה, השרת לא זמין באופן זמני וכו'. נכון לעכשיו, Chrome לא מאשר את הבקשה בשקט במקרה של שגיאות כאלה, ומודיע ל-RP רק בדחיית ההבטחה.

כשמשתמשים ב-Error API, המערכת של Chrome שולחת התראות למשתמש על ידי הצגת ממשק משתמש מקורי עם פרטי השגיאה שה-IdP סיפק.

תיבת דו-שיח של FedCM שבה מוצגת הודעת השגיאה אחרי שניסיון הכניסה של המשתמש נכשל. המחרוזת משויכת לסוג השגיאה.
תיבת דו-שיח של FedCM שמוצגת בה הודעת השגיאה אחרי שניסיון הכניסה של המשתמש נכשל. המחרוזת משויכת לסוג השגיאה.

ממשק API של HTTP ל-IdP

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

  1. code
  2. url
// id_assertion_endpoint response
{
  "error": {
     "code": "access_denied",
     "url": "https://idp.example/error?type=access_denied"
  }
}

ה-IdP יכול לבחור באחת מהשגיאות הידועות מרשימת השגיאות שצוינו ב-OAuth 2.0 [invalid_request, unauthorized_client, access_denied, server_error ו-temporarily_unavailable] או להשתמש במחרוזת שרירותית כלשהי. אם האפשרות השנייה היא ש-Chrome מעבד את ממשק המשתמש של השגיאות עם הודעת השגיאה הגנרית ומעביר את הקוד ל-RP.

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

try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: 'https://idp.example/manifest.json',
          clientId: '1234',
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

ממשק API לסימון שנבחר באופן אוטומטי

mediation: optional הוא התנהגות ברירת המחדל של תהליך בחירת הרשת (Mediation) של משתמשים ב-Credential Management API, והוא מפעיל אימות אוטומטי מחדש כשאפשר. עם זאת, האימות האוטומטי מחדש לא זמין יכול להיות בגלל סיבות שרק לדפדפן יודע. במקרים שבהם האפשרות הזו לא זמינה, יכול להיות שהמשתמשים יתבקשו להיכנס לחשבון באמצעות תהליך בחירת הרשת (Mediation) מפורש – כלומר, תהליך עם נכסים שונים.

  • מבחינת הקורא ל-API, כשהם מקבלים אסימון מזהה, אין להם אפשרות לדעת אם המקור היה בתהליך אימות אוטומטי. לכן קשה להם להעריך את ביצועי ה-API ולשפר את חוויית המשתמש בהתאם.
  • מנקודת המבט של ה-IdP, באותה מידה הם לא יכולים לדעת אם בוצע או לא אימות אוטומטי לצורך הערכת הביצועים. בנוסף, אם היה מעורב תהליך מפורש של בחירת רשת מצד המשתמש, יכול להיות שהוא תומך בתכונות נוספות שקשורות לאבטחה. לדוגמה, משתמשים מסוימים עשויים להעדיף רמת אבטחה גבוהה יותר, שמחייבת גישור מפורש של המשתמשים לאימות. אם ה-IdP מקבל בקשה לאסימון ללא תהליך בחירת הרשת (Mediation) כזה, יכול להיות שהוא יטפל בבקשה באופן שונה. לדוגמה, החזרת קוד שגיאה כך שה-RP יוכל להפעיל שוב את ה-API של FedCM באמצעות mediation: required.

לכן, היכולת לראות את תהליך האימות האוטומטי יכולה להועיל למפתחים.

באמצעות Auto-selected API, Chrome משתף אם הושגה הרשאה מפורשת למשתמש באמצעות הקשה על הלחצן Continue as (המשך בתור) עם ה-IdP וגם עם ה-RP, בכל פעם שהתרחש אימות מחדש אוטומטי או תהליך בחירת רשת מפורש. השיתוף מתבצע רק אחרי שמעניקים הרשאת משתמש לתקשורת IdP/RP.

שיתוף IdP

כדי לשתף את המידע עם הרשאת משתמש לפוסט של ה-IdP, Chrome כולל is_auto_selected=true בבקשת POST שנשלחה ל-id_assertion_endpoint:

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=Ct0D&disclosure_text_shown=true&is_auto_selected=true

שיתוף גורם מוגבל

הדפדפן יכול לשתף את המידע עם ה-RP ב-isAutoSelected דרך IdentityCredential:

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/manifest.json',
      clientId: '1234'
    }]
  }
});

if (cred.isAutoSelected !== undefined) {
  const isAutoSelected = cred.isAutoSelected;
}

עניין ושיתוף משוב

אם יש לכם משוב או בעיות במהלך הבדיקה, תוכלו לשתף אותן בכתובת crbug.com.

תמונה מאת Girl עם כובע אדום ב-Unense