דף זה תורגם על ידי Cloud Translation API.

מדריך למפתחים בנושא Federated Credential Management API

כאן מוסבר איך משתמשים ב-FedCM לאיחוד שירותי אימות הזהות תוך שמירה על הפרטיות.

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

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

סביבת הפיתוח של FedCM

צריך הקשר מאובטח (HTTPS או Localhost) גם ב-IdP וגם ב-RP ב-Chrome להשתמש ב-FedCM.

קוד לניפוי באגים ב-Chrome ב-Android

צריך להגדיר ולהפעיל שרת באופן מקומי כדי לנפות באגים בקוד ה-FedCM. אפשר גישה לשרת הזה בדפדפן Chrome במכשיר Android שמחובר באמצעות כבל USB עם יציאה מתבצעת העברה.

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

חסימת קובצי cookie של צד שלישי ב-Chrome

ביצוע הדמיה של הפסקה הדרגתית של שימוש בקובצי Cookie של צד שלישי על ידי הגדרת Chrome לחסימה שלהם — סימולציה של הוצאה הדרגתית של קובצי Cookie של צד שלישי על ידי הגדרת Chrome לחסום אותם

אתם יכולים לבדוק איך FedCM פועל ללא קובצי Cookie של צד שלישי ב-Chrome לפני לאכיפה בפועל.

כדי לחסום קובצי Cookie של צד שלישי, צריך להשתמש במצב פרטי מצב, או בוחרים באפשרות 'חסימה' קובצי cookie של צד שלישי" בהגדרות של המחשב בכתובת chrome://settings/cookies או במכשיר נייד על ידי מעבר אל הגדרות > הגדרות לאתרים > קובצי cookie.

שימוש ב-FedCM API

כדי לשלב את FedCM צריך ליצור קובץ ידוע, קובץ תצורה ונקודות קצה (endpoints) לחשבונות list, הנפקה של טענות נכונות (assertions) וגם אופציונלי: מטא-נתונים של לקוח.

כאן, FedCM חושף ממשקי API של JavaScript שמשמשים את הגורמים המוגבלים (RP) כדי לחתום in עם ה-IdP.

יצירת קובץ ידוע

כדי למנוע מכלי מעקב לנצל לרעה את ל-API, קובץ ידוע צריך להיות הצגת מודעות מתוך /.well-known/web-identity מתוך eTLD+1 של IdP.

לדוגמה, אם נקודות הקצה של IdP מוצגות https://accounts.idp.example/, הם צריכים להגיש קובץ ידוע בכתובת https://idp.example/.well-known/web-identity וגם הגדרה של IdP . הנה דוגמה לתוכן ידוע של קובץ:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

קובץ ה-JSON חייב להכיל את המאפיין provider_urls עם מערך של IdP כתובות URL של קובץ התצורה שניתן לציין אותן כחלק מנתיב configURL ב-navigator.credentials.get על ידי גורמים מוגבלים. מספר מחרוזות ה-URL במערך מוגבלות למחרוזת אחת, אבל הדבר עשוי להשתנות משוב בעתיד.

טיפ: במהלך הפיתוח של FedCM, בדיקה או Staging של דומיינים של שרת RP עשויים להיות של שרת ה-IdP בסביבת הייצור. לדוגמה, שרת ה-IdP לסביבת הייצור נמצא ב-idp.example וגם את שרת ה-Staging RP וגם את ה-Staging שרת ה-IdP נמצאים ב-staging.idp.example. אבל, מאחר שהמודל יש למקם קובץ ידוע ברמה הבסיסית (root) של ה-eTLD+1 של שרת ה-IdP, יש לו להיות ב-idp.example/.well-known/web-identity, בסביבת הייצור. מאחר שלא בטוח שהמפתחים יכולים בסביבת הייצור בזמן הפיתוח, דבר שמונע מהם מבדיקת FedCM. אם דומיין ה-RP ודומיין ה-IdP זהים, Chrome יכול לדלג על הבדיקה של ידוע החל מ-Chrome 122. אפשר גם לעקוף את הבדיקה של configURL על ידי הפעלה של ההגדרה דגל chrome://flags#fedcm-without-well-known-enforcement. הדבר שימושי כשסביבת הפיתוח משתמשת ב-DNS שאינו ציבורי נגיש.

יצירת קובץ תצורה ונקודות קצה של IdP

קובץ התצורה של ה-IdP כולל רשימה של נקודות הקצה (endpoints) הנחוצות לדפדפן. IdPs יארח את קובץ התצורה הזה ואת כתובות ה-URL ונקודות הקצה הנדרשות. כל קובצי ה-JSON חובה להגיש תשובות עם סוג תוכן application/json.

כתובת ה-URL של קובץ התצורה נקבעת לפי הערכים שצוינו הקריאה ל-navigator.credentials.get בוצעה על ידי גורם מוגבל.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

צריך לציין כתובת URL מלאה של המיקום של קובץ התצורה של ה-IdP בתור configURL. מתי navigator.credentials.get() נקראת ב-RP, הדפדפן מאחזר את קובץ התצורה באמצעות בקשת GET ללא הכותרת Origin או הכותרת Referer. הבקשה לא כוללת קובצי cookie ולא עוקבת אחר הפניות אוטומטיות. כך ה-IdP לא יוכל ללמוד מי שלח את הבקשה, הגורם המוגבל מנסה להתחבר. לדוגמה:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

זהירות: כל הבקשות שנשלחות מהדפדפן באמצעות FedCM כוללים את הכותרת Sec-Fetch-Dest: webidentity כדי למנוע מתקפות CSRF. נקודות הקצה הבאות של IdP חייבות לאשר שהכותרת הזו כלולה:

נקודת קצה של חשבונות
נקודת קצה של טענת נכוֹנוּת (assertion) של המזהה
ניתוק נקודת קצה

הדפדפן מצפה לתגובת JSON מה-IdP שכוללת את הפרטים הבאים: נכסים:

נכס	תיאור
`accounts_endpoint` (חובה)	כתובת ה-URL של נקודת הקצה של החשבונות.
ֶ`client_metadata_endpoint` (אופציונלי)	כתובת ה-URL של נקודת הקצה של המטא-נתונים של הלקוח.
`id_assertion_endpoint` (חובה)	כתובת ה-URL של נקודת הקצה של טענת הנכוֹנוּת (assertion) של המזהה.
ֶ`disconnect` (אופציונלי)	כתובת ה-URL של נקודת הקצה (endpoint).
`login_url` (חובה)	כתובת ה-URL של דף ההתחברות של המשתמש כדי להיכנס ל-IdP.
ֶ`branding` (אופציונלי)	אובייקט שמכיל אפשרויות מיתוג שונות.
ֶ`branding.background_color` (אופציונלי)	אפשרות מיתוג שמגדירה את צבע הרקע של האפשרות 'המשך בתור...' לחצן. צריך להשתמש בתחביר CSS הרלוונטי, כלומר `hex-color` `hsl()`, `rgb()`, או `named-color`.
ֶ`branding.color` (אופציונלי)	אפשרות מיתוג שמגדירה את צבע הטקסט של האפשרות 'המשך בתור...'. לחצן. צריך להשתמש בתחביר CSS הרלוונטי, כלומר `hex-color` `hsl()`, `rgb()`, או `named-color`.
ֶ`branding.icons` (אופציונלי)	אפשרות מיתוג שמגדירה את אובייקט הסמל שמוצג בתיבת הדו-שיח לכניסה. אובייקט הסמל הוא מערך עם שני פרמטרים: `url` (חובה): כתובת URL של תמונת הסמל. האפשרות הזו לא תומכת בתמונות SVG. `size` (אופציונלי): מידות הסמל, שבהן האפליקציה מניחה שהם ברזולוציה של ריבוע. המספר הזה חייב להיות גדול מ-25 או שווה לו.

הגורם המוגבל (RP) יכול לשנות את המחרוזת בממשק המשתמש של תיבת הדו-שיח של FedCM באמצעות ערך של identity.context בשביל navigator.credentials.get() כדי לאפשר אימות מוגדר מראש הקשרים שונים. המאפיין האופציונלי יכול להיות אחד מהערכים האלה: "signin" (ברירת מחדל), "signup", "use" או "continue".

לפניכם דוגמה לגוף התשובה מה-IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

אחרי שהדפדפן מאחזר את קובץ התצורה, הוא שולח בקשות נוספות אל נקודות קצה ב-IdP:

נקודת הקצה של חשבונות

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

הדפדפן שולח בקשת GET עם קובצי cookie עם SameSite=None, אבל בלי פרמטר client_id, הכותרת Origin או הכותרת Referer. הזה זה מונע מה-IdP ללמוד על הגורם המוגבל (RP) שהמשתמש מנסה לחתום ב-. לדוגמה:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

עם קבלת הבקשה, השרת צריך:

צריך לוודא שהבקשה מכילה כותרת HTTP Sec-Fetch-Dest: webidentity.
מתאימים את קובצי ה-cookie של הסשן למזהים של החשבונות שכבר מחוברים.
מחזירים תשובה ומצרפים את רשימת החשבונות.

הדפדפן מצפה לתגובת JSON שכוללת נכס accounts עם מערך של פרטי חשבון עם המאפיינים הבאים:

נכס	תיאור
`id` (חובה)	המזהה הייחודי של המשתמש.
`name` (חובה)	השם הפרטי ושם המשפחה של המשתמש.
`email` (חובה)	כתובת האימייל של המשתמש.
ֶ`given_name` (אופציונלי)	השם הפרטי של המשתמש.
ֶ`picture` (אופציונלי)	כתובת ה-URL של תמונת דמות המשתמש.
ֶ`approved_clients` (אופציונלי)	מערך של מזהי לקוח של גורם מוגבל (RP) שהמשתמש נרשם איתם.
ֶ`login_hints` (אופציונלי)	מערך של כל סוגי המסננים האפשריים ש-IdP תומך בהם כדי לציין חשבון. הגורם המוגבל (RP) יכול להפעיל את `navigator.credentials.get()` עם הנכס `loginHint` כדי להציג באופן סלקטיבי את החשבון שצוין.
ֶ`domain_hints` (אופציונלי)	מערך של כל הדומיינים שאליהם החשבון משויך. הגורם המוגבל התקשרות אל `navigator.credentials.get()` באמצעות `domainHint` כדי לסנן את חשבונות.

דוגמה לגוף התשובה:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

אם המשתמש לא מחובר לחשבון, יש להשיב באמצעות HTTP 401 (לא מורשה).

הדפדפן משתמש ברשימת החשבונות שהוחזרו ולא תהיה זמינה ל: הגורם המוגבל.

נקודת קצה למטא-נתונים של לקוח

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

הדפדפן שולח בקשת GET באמצעות client_id navigator.credentials.get ללא קובצי Cookie. לדוגמה:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

עם קבלת הבקשה, השרת צריך:

קובעים את הגורם המוגבל (RP) של client_id.
להשיב עם המטא-נתונים של הלקוח.

המאפיינים של נקודת הקצה במטא-נתונים של הלקוח כוללים:

נכס	תיאור
ֶ`privacy_policy_url` (אופציונלי)	כתובת ה-URL של מדיניות הפרטיות של הגורם המוגבל.
ֶ`terms_of_service_url` (אופציונלי)	כתובת ה-URL של התנאים וההגבלות של הגורם המוגבל.

הדפדפן מצפה לתגובת JSON מנקודת הקצה:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

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

נקודת קצה של טענת נכוֹנוּת (assertion) של המזהה

נקודת הקצה לטענת הנכוֹנוּת (assertion) של המזהה ב-IdP מחזירה טענת נכוֹנוּת (assertion) של המשתמש המחובר. כשהמשתמש נכנס לאתר של גורם מוגבל באמצעות navigator.credentials.get() , הדפדפן שולח בקשת POST עם קובצי cookie עם SameSite=None וסוג התוכן של application/x-www-form-urlencoded כדי את נקודת הקצה עם הפרטים הבאים:

נכס	תיאור
`client_id` (חובה)	מזהה הלקוח של הגורם המוגבל.
`account_id` (חובה)	המזהה הייחודי של המשתמש שנכנס לחשבון.
ֶ`nonce` (אופציונלי)	הצופן החד-פעמי (nonce) של הבקשה, שסופק על ידי הגורם המוגבל.
`disclosure_text_shown`	התוצאות מוצגות במחרוזת `"true"` או `"false"` (במקום ערך בוליאני). אם טקסט הגילוי הנאות לא הוצג, התוצאה תהיה `"false"`. מצב זה מתרחש כשמזהה הלקוח של הגורם המוגבל (RP) נכלל ברשימת הנכסים של `approved_clients` של התגובה מנקודת הקצה של החשבונות, או אם הדפדפן זיהה רגע הרשמה בעבר כאשר לא צוין `approved_clients`.
`is_auto_selected`	אם בגורם המוגבל (RP) מבוצע אימות מחדש אוטומטי, `is_auto_selected` מציין `"true"`. אחרת, `"false"`. הפעולה הזו שימושית לצורך תמיכה בתכונות נוספות שקשורות לאבטחה. לדוגמה, משתמשים מסוימים עשויים להעדיף רמת אבטחה גבוהה יותר שדורשת תהליך אימות מפורש של המשתמש בתהליך האימות. אם IdP מקבל בקשה לאסימון ללא תיווך כזה, הוא עשוי לטפל בבקשה בצורה שונה. לדוגמה, החזרת קוד שגיאה כך שה-RP יוכל לקרוא שוב ל-FedCM API עם `mediation: required`.

כותרת HTTP לדוגמה:

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

עם קבלת הבקשה, השרת צריך:

להגיב לבקשה באמצעות CORS (משאב ממקורות שונים שיתוף).
צריך לוודא שהבקשה מכילה כותרת HTTP Sec-Fetch-Dest: webidentity.
מתאימים את הכותרת Origin למקור של הגורם המוגבל (RP) שנקבע לפי client_id. אפשר לדחות אותם אם הם לא תואמים.
מתאימים את account_id למזהה של החשבון שמחובר כבר. דחייה אם הם לא תואמים.
להשיב באמצעות אסימון. אם הבקשה תידחה, יש להשיב עם שגיאה תשובה.

אזהרה: הבקשה של CORS צריכה להיות עם פרטי כניסה, כלומר, כותרת התגובה Access-Control-Allow-Origin חייבת לציין מקור מפורש ולא תו כללי לחיפוש באמצעות "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true

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

הדפדפן מצפה לתגובת JSON שכוללת את המאפיין הבא:

נכס	תיאור
`token` (חובה)	אסימון הוא מחרוזת שמכילה הצהרות על האימות.

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

האסימון המוחזר מועבר ל-RP על ידי הדפדפן, כדי שה-RP יוכל לאמת את האימות.

החזרת תגובת שגיאה

id_assertion_endpoint גם יכול להחזיר 'שגיאה' שכוללת שני שדות אופציונליים:

code: ה-IdP יכול לבחור אחת מהשגיאות הידועות בדוח OAuth 2.0 השגיאה שצוינה list (invalid_request, unauthorized_client, access_denied, server_error וגם temporarily_unavailable) או להשתמש בכל מחרוזת שרירותית. אם ההגדרה היא אחרת, Chrome מעבד את ממשק השגיאות של השגיאה ומציג הודעת שגיאה גנרית ומעביר את הקוד לגורם המוגבל (RP).
url: הוא מזהה דף אינטרנט קריא לאנשים עם מידע על כדי לספק למשתמשים מידע נוסף על השגיאה. השדה הזה שימושי למשתמשים מכיוון שדפדפנים לא יכולים לספק הודעות שגיאה עשירות ממשק משתמש מקורי. לדוגמה, קישורים לשלבים הבאים, פרטים ליצירת קשר עם שירות הלקוחות מידע וכן הלאה. אם המשתמש רוצה לקבל מידע נוסף על פרטי השגיאה ואיך לתקן את זה, הם יכולים להיכנס לדף שסופק מממשק המשתמש של הדפדפן פרטים נוספים. כתובת ה-URL חייבת להיות מאותו אתר כמו ה-IdP (מזהה configURL).

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

ניתוק נקודת הקצה

על ידי הפעלת IdentityCredential.disconnect(), הדפדפן שולח קוד חוצה-מקורות בקשת POST עם קובצי cookie עם SameSite=None וסוג תוכן של application/x-www-form-urlencoded לנקודת הקצה הזו של הניתוק באמצעות הבאים:

נכס	תיאור
`account_hint`	רמז לחשבון IdP.
`client_id`	מזהה הלקוח של הגורם המוגבל.

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

account_hint=account456&client_id=rp123

עם קבלת הבקשה, השרת צריך:

להגיב לבקשה באמצעות CORS (משאב ממקורות שונים שיתוף).
צריך לוודא שהבקשה מכילה כותרת HTTP Sec-Fetch-Dest: webidentity.
מתאימים את הכותרת Origin למקור של הגורם המוגבל (RP) שנקבע לפי client_id. אפשר לדחות אותם אם הם לא תואמים.
התאמת account_hint למזהים של החשבונות שכבר מחוברים.
מנתקים את חשבון המשתמש מה-RP.
להשיב לדפדפן עם פרטי חשבון המשתמש שזוהו ב-JSON הפורמט.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true

דוגמה למטען ייעודי (payload) של JSON עם תגובה:

{
  "account_id": "account456"
}

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

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

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

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

כשהמשתמש לוחץ על הלחצן המשך, הדפדפן פותח חלון קופץ. לדף ההתחברות של ה-IdP.

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

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

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

משתמש נכנס ל-RP אחרי כניסה ל-IdP באמצעות FedCM.

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

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

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

Set-Login: logged-in

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

navigator.login.setStatus("logged-in")

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

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

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 שולח אות באמצעות סטטוס ההתחברות API. הגרסה Unknown נוצרה לצורך מעבר טוב יותר, כי ייתכן שמשתמש כבר נכנסו ל-IdP כשה-API הזה נשלח. יכול להיות שה-IdP לא כולל הזדמנות לסמן זאת לדפדפן לפני ההפעלה הראשונה של FedCM. כאן דפדפן Chrome ישלח בקשה לנקודת הקצה (endpoint) של החשבונות של ה-IdP ויעדכן את המבוסס על התגובה מנקודת הקצה של החשבונות:

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

הערה: ניתן לשלוח את כותרת סטטוס ההתחברות מאותו אתר גם במשאבי משנה, החל מ-Chrome 122. האפשרות הזו שימושית, לדוגמה, אם אתר שמאפשר למשתמשים להזין את שם המשתמש שלהם והסיסמה ב-idp.example, אבל פרטי הכניסה פורסמו ב- login.idp.example עם fetch(). תגובת האחזור מ-login.idp.example עדיין יכול להגדיר את סטטוס ההתחברות עבור idp.example על ידי שליחת HTTP Set-Login: logged-in הכותרת.

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

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

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

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

ה-Login Status API לא מאפשר ל-RP להציג "כניסה ל-IdP" למשתמשים שלא מחוברים ל-IdP. זהו תכונה נפרדת שתתווסף בעתיד.

כניסה לצד הנסמך באמצעות ספק הזהויות

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

לפני הקריאה ל-API, צריך לוודא ש-[FedCM זמין הדפדפן של המשתמש]. כדי לבדוק אם FedCM זמין, אפשר לעטוף את הקוד הזה סביב הטמעת FedCM:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

כדי לבקש למשתמשים להיכנס ל-IdP מה-RP: לדוגמה:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

המאפיין providers מקבל מערך של IdentityProvider אובייקטים שיש להם המאפיינים הבאים:

נכס	תיאור
`configURL` (חובה)	נתיב מלא של קובץ התצורה של ה-IdP.
`clientId` (חובה)	מזהה הלקוח של הגורם המוגבל (RP), שהונפק על ידי ה-IdP.
ֶ`nonce` (אופציונלי)	מחרוזת אקראית שנועדה להבטיח שהתגובה תונפק לבקשה הספציפית הזו. מניעת התקפות שליחה מחדש
ֶ`loginHint` (אופציונלי)	אפשר לציין אחד מהערכים של `login_hints` שסופקו על ידי נקודות הקצה של החשבונות, ה-FedCM מציגה באופן סלקטיבי את החשבון שצוין.
ֶ`domainHint` (אופציונלי)	אפשר לציין אחד מהערכים של `domain_hints` שסופקו על ידי נקודות הקצה של החשבונות, ה-FedCM להציג באופן סלקטיבי את החשבון שצוין.

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

מצב ההרשמה נקבע על סמך התנאי הבא: סופקו או לא:

אם approved_clients כולל את clientId של הגורם המוגבל.
אם הדפדפן זוכר שהמשתמש כבר נרשם ל-RP.

משתמש נכנס ל-RP באמצעות FedCM

כשהגורם המוגבל (RP) שולח קריאה אל navigator.credentials.get(), הפעילויות הבאות מתבצעות מקום:

הדפדפן שולח בקשות ומאחזר מספר מסמכים:
1. הקובץ הידוע והגדרת IdP שמצהיר על נקודות הקצה.
2. רשימת חשבונות.
3. אופציונלי: כתובות URL למדיניות הפרטיות ולתנאים ולהגבלות של הגורם המוגבל מאוחזר מנקודת הקצה של המטא-נתונים של הלקוח.
הדפדפן מציג את רשימת החשבונות שהמשתמש יכול להשתמש בהם כדי להיכנס, וגם את התנאים וההגבלות ומדיניות הפרטיות, אם יש כאלה.
אחרי שהמשתמש יבחר חשבון להיכנס באמצעותו, תישלח בקשה למזהה נקודת קצה של טענת נכוֹנוּת (assertion) נשלחת ל-IdP כדי לאחזר ב-Assistant.
הגורם המוגבל (RP) יכול לאמת את האסימון כדי לאמת את המשתמש.

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

לאחר שהאסימון מאומת על ידי שרת ה-RP, ה-RP עשוי לרשום את המשתמש או לאפשר להם להיכנס ולהתחיל סשן חדש.

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

גורמים מוגבלים יכולים להציג חשבון ספציפי באופן סלקטיבי על ידי הפעלה navigator.credentials.get() עם המאפיין loginHint עם אחד מ- login_hints ערכים אוחזרו מרשימת החשבונות נקודת קצה (endpoint), כפי שמוצג בדוגמת הקוד הבאה:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

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

ממשק API של Domain Hint

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

גורמים מוגבלים יכולים להציג באופן סלקטיבי רק חשבונות תואמים על ידי הפעלה navigator.credentials.get() עם המאפיין domainHint עם אחד מ- domain_hints ערכים אוחזרו מרשימת החשבונות נקודת קצה (endpoint), כפי שמוצג בדוגמת הקוד הבאה:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

הערה: כאשר נעשה שימוש ב-domainHint: "any", Chrome מסנן חשבונות ללא דומיינים (כלומר, domain_hints לא הועבר או ריק). לדוגמה, כך ניתן לאפשר תרחישים לדוגמה שבהם הגורם המוגבל מאפשר לנהל רק חשבונות בתהליך ההרשמה שלו.

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

דוגמה לבקשת התחברות כשאין חשבונות שתואמים ל-domainHint. — דוגמה לבקשת התחברות כשאין חשבונות שתואמים ל-`domainHint`.

להציג הודעת שגיאה

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

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

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;
}

אימות מחדש אוטומטי של משתמשים אחרי האימות הראשוני

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

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

לאחר אימות אוטומטי, הדפדפן משנה את אופן הפעולה שלו בהתאם לאפשרות לציין עבור mediation כשקוראים לפונקציה navigator.credentials.get().

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

ה-mediation הוא נכס בניהול פרטי הכניסה API, הוא מתנהג באותו דרך כפי שנעשה עבור PasswordCredential וגם FederatedCredential והיא נתמכת באופן חלקי PublicKeyCredential וגם. המאפיין מקבל את ארבעת הערכים הבאים:

'optional'(ברירת מחדל): אימות אוטומטי אם אפשר, מחייב גישור. רביעי מומלץ לבחור באפשרות הזו בדף הכניסה.
'required': תמיד צריך להגדיר גישור כדי להמשיך. לדוגמה, לחיצה על "Continue" בממשק המשתמש. יש לבחור באפשרות הזו אם המשתמשים צפויים מעניקות הרשאה מפורשת בכל פעם שצריך לאמת אותן.
'silent': אימות מחדש אוטומטי אם אפשר, נכשל ללא צורך בתהליך בחירת הרשת אם לא. מומלץ לבחור באפשרות זו בדפים שאינם דף הכניסה הייעודי, אבל שבו רוצים שהמשתמשים יישארו מחוברים לחשבון למשל, דף פריט באתר משלוחים או דף מאמר בחדשות האתר.
'conditional': השירות משמש ל-WebAuthn ולא זמין ל-FedCM כרגע.

בשיחה הזו, האימות מחדש האוטומטי מתקיים בתנאים הבאים:

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

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

כאשר mediation: optional, האימות מחדש עשוי להיות לא זמין עקב סיבות רק הדפדפן יודע, הגורם המוגבל (RP) יכול לבדוק אם האימות מחדש האוטומטי מתבצע על ידי בודק את המאפיין isAutoSelected.

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

משתמש שמבצע אימות מחדש באופן אוטומטי באמצעות FedCM.

אכיפת גישור באמצעות `preventSilentAccess()`

אימות מחדש אוטומטי של משתמשים מיד לאחר שהם יוצאים מהחשבון לא יאפשר חוויית משתמש טובה מאוד. לכן יש ל-FedCM תקופה שקטה של 10 דקות אחרי אימות אוטומטי מחדש כדי למנוע התנהגות כזו. המשמעות היא שהאימות מחדש מתבצע לכל היותר פעם אחת בכל 10 דקות, אלא אם המשתמש נכנס שוב לחשבון בתוך 10 דקות. הגורם המוגבל (RP) צריך לקרוא ל-navigator.credentials.preventSilentAccess() ל- לבקש במפורש מהדפדפן להשבית אימות מחדש אוטומטי כאשר משתמש יוצא את הגורם המוגבל (RP) באופן מפורש, לדוגמה, על ידי לחיצה על לחצן יציאה.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

המשתמשים יכולים לבטל את ההסכמה לאימות אוטומטי בהגדרות

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

ב-Chrome במחשב, עוברים אל chrome://password-manager/settings > איך נכנסים באופן אוטומטי.
ב-Android Chrome, פותחים את הגדרות > מנהל הסיסמאות > מקישים על גלגל השיניים בפינה הימנית העליונה > כניסה אוטומטית.

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

מנתקים את ה-IdP מה-RP

אם משתמש נכנס בעבר ל-RP באמצעות IdP דרך FedCM, זוכרים את היחסים על ידי הדפדפן באופן מקומי כרשימת חשבונות. ה-RP יכול ליזום ניתוק על ידי הפעלה של IdentityCredential.disconnect(). ניתן לקרוא לפונקציה הזו מתוך מסגרת של גורם מוגבל (RP) ברמה העליונה. הגורם המוגבל (RP) צריך להעביר configURL, שהוא clientId שבו הוא משתמש מתחת ל-IdP ו בצורה accountHint כדי שה-IdP ינותק. חשבון הרמז יכול להיות מחרוזת שרירותית, כל עוד נקודת הקצה לניתוק יכולה לזהות החשבון, לדוגמה, כתובת אימייל או מזהה משתמש שלא בהכרח תואם למספר החשבון שסופק בנקודת הקצה של רשימת החשבונות:

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

הפונקציה IdentityCredential.disconnect() מחזירה Promise. ההבטחה הזו עלולה לגרום חריג, מהסיבות הבאות:

המשתמש לא נכנס ל-RP באמצעות IdP דרך FedCM.
ה-API מופעל מתוך iframe ללא מדיניות הרשאות של FedCM.
השדה configURL לא תקין או שחסרה בו נקודת הקצה של ניתוק.
הבדיקה של Content Security Policy (CSP) נכשלה.
יש בקשת ניתוק בהמתנה.
המשתמש השבית את FedCM בהגדרות הדפדפן.

כשנקודת הקצה (endpoint) של ה-IdP של ה-IdP מחזירה , ה-RP וה-IdP מנותקים הדפדפן וההבטחה נפתרה. המזהים של החשבונות המנותקים הם מצוין בתגובה מהניתוק נקודת קצה (endpoint).

קריאה ל-FedCM מתוך iframe ממקורות שונים

אפשר להפעיל FedCM מתוך iframe ממקורות שונים באמצעות מדיניות ההרשאות של identity-credentials-get, אם מסגרת ההורה מאפשרת זאת. שפת תרגום לעשות זאת, יש להוסיף את המאפיין allow="identity-credentials-get" לתג ה-iframe ככה:

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

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

לחלופין, אם מסגרת ההורה רוצה להגביל את המקורות לקריאה ל-FedCM: לשלוח כותרת Permissions-Policy עם רשימה של מקורות מורשים.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

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

מדריך למפתחים בנושא Federated Credential Management API

סביבת הפיתוח של FedCM

קוד לניפוי באגים ב-Chrome ב-Android

חסימת קובצי cookie של צד שלישי ב-Chrome

שימוש ב-FedCM API

יצירת קובץ ידוע

יצירת קובץ תצורה ונקודות קצה של IdP

נקודת הקצה של חשבונות

נקודת קצה למטא-נתונים של לקוח

נקודת קצה של טענת נכוֹנוּת (assertion) של המזהה

החזרת תגובת שגיאה

ניתוק נקודת הקצה

כתובת URL להתחברות

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

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

כניסה לצד הנסמך באמצעות ספק הזהויות

ממשק API של רמז להתחברות

ממשק API של Domain Hint

להציג הודעת שגיאה

אימות מחדש אוטומטי של משתמשים אחרי האימות הראשוני

אכיפת גישור באמצעות preventSilentAccess()

המשתמשים יכולים לבטל את ההסכמה לאימות אוטומטי בהגדרות

מנתקים את ה-IdP מה-RP

קריאה ל-FedCM מתוך iframe ממקורות שונים

אכיפת גישור באמצעות `preventSilentAccess()`