כאן מוסבר איך משתמשים ב-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 לחסימה שלהם](https://developers.google.cn/static/privacy-sandbox/assets/images/simulate-third-party-cook-8416bea1ab2b.png?authuser=0000&hl=he)
אתם יכולים לבדוק איך 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 במערך מוגבלות למחרוזת אחת, אבל הדבר עשוי להשתנות
משוב בעתיד.
יצירת קובץ תצורה ונקודות קצה של 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
הדפדפן מצפה לתגובת 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 (אופציונלי) |
אפשרות מיתוג שמגדירה את אובייקט הסמל שמוצג בתיבת הדו-שיח לכניסה. אובייקט הסמל הוא מערך עם שני פרמטרים:
|
הגורם המוגבל (RP) יכול לשנות את המחרוזת בממשק המשתמש של תיבת הדו-שיח של FedCM באמצעות ערך של identity.context
בשביל navigator.credentials.get()
כדי לאפשר אימות מוגדר מראש
הקשרים שונים. המאפיין האופציונלי יכול להיות אחד מהערכים האלה: "signin"
(ברירת מחדל), "signup"
,
"use"
או "continue"
.
![איך מחילים מיתוג בתיבת הדו-שיח של FedCM](https://developers.google.cn/static/privacy-sandbox/assets/images/RZwmFnyJChjlki8QsnBB.png?authuser=0000&hl=he)
לפניכם דוגמה לגוף התשובה מה-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:
![נקודות קצה ב-IdP](https://developers.google.cn/static/privacy-sandbox/assets/images/idp-endpoints-a67327f46da51.png?authuser=0000&hl=he)
נקודת הקצה של חשבונות
נקודת הקצה (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
למזהה של החשבון שמחובר כבר. דחייה אם הם לא תואמים. - להשיב באמצעות אסימון. אם הבקשה תידחה, יש להשיב עם שגיאה תשובה.
אופן הנפקת האסימון תלוי ב-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 הפורמט.
דוגמה למטען ייעודי (payload) של JSON עם תגובה:
{
"account_id": "account456"
}
במקום זאת, אם ה-IdP רוצה שהדפדפן ינתק את כל החשבונות שמשויכים אל
ה-RP, מעבירים מחרוזת שלא תואמת לאף מספר חשבון. לדוגמה: "*"
.
כתובת URL להתחברות
באמצעות Login Status API, ה-IdP חייב ליידע את המשתמש
התחברות לדפדפן. עם זאת, ייתכן שהסטטוס לא מסונכרן, למשל
כאשר תוקף הסשן יפוג. במקרה כזה,
הדפדפן יכול לאפשר באופן דינמי למשתמש להיכנס ל-IdP דרך דף ההתחברות
כתובת ה-URL שצוינה ב-login_url
של קובץ התצורה של idp.
בתיבת הדו-שיח של FedCM מוצגת הודעה שמציעה כניסה, כפי שמוצג התמונה הבאה.
![A](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-120-1.png?authuser=0000&hl=he)
כשהמשתמש לוחץ על הלחצן המשך, הדפדפן פותח חלון קופץ. לדף ההתחברות של ה-IdP.
![An](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-120-2.png?authuser=0000&hl=he)
תיבת הדו-שיח היא חלון דפדפן רגיל שמכיל קובצי cookie מהדומיין הנוכחי. שיהיה בתיבת הדו-שיח עד ל-IdP, ואין כינויים זמינים של חלונות כדי לשלוח בקשת תקשורת בין מקורות לדף ה-RP. אחרי שהמשתמש מחוברים לחשבון, ה-IdP צריך:
- שולחים את הכותרת
Set-Login: logged-in
או קוראים ל- API שלnavigator.login.setStatus("logged-in")
כדי ליידע את הדפדפן ש משתמש מחובר. - קוראים לפונקציה
IdentityProvider.close()
כדי לסגור את תיבת הדו-שיח.
![A](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm.gif?authuser=0000&hl=he)
עדכון הדפדפן לגבי סטטוס ההתחברות של המשתמש בספק הזהויות
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.
לאפשר למשתמשים להיכנס לחשבון באמצעות תהליך התחברות דינמי
גם אם ה-IdP מיידע שוב ושוב את סטטוס ההתחברות של המשתמש לדפדפן,
יכול להיות לא מסונכרן, למשל, כשפג תוקף הסשן. הדפדפן מנסה
לשלוח בקשה עם פרטי כניסה לנקודת הקצה של החשבונות כשסטטוס ההתחברות הוא
logged-in
, אך השרת אינו מחזיר חשבונות מפני שהסשן כבר לא
זמינים. בתרחיש כזה, הדפדפן יכול לאפשר למשתמש להיכנס באופן דינמי
ל-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) שולח קריאה אל navigator.credentials.get()
, הפעילויות הבאות מתבצעות
מקום:
- הדפדפן שולח בקשות ומאחזר מספר מסמכים:
- הקובץ הידוע והגדרת IdP שמצהיר על נקודות הקצה.
- רשימת חשבונות.
- אופציונלי: כתובות URL למדיניות הפרטיות ולתנאים ולהגבלות של הגורם המוגבל מאוחזר מנקודת הקצה של המטא-נתונים של הלקוח.
- הדפדפן מציג את רשימת החשבונות שהמשתמש יכול להשתמש בהם כדי להיכנס, וגם את התנאים וההגבלות ומדיניות הפרטיות, אם יש כאלה.
- אחרי שהמשתמש יבחר חשבון להיכנס באמצעותו, תישלח בקשה למזהה נקודת קצה של טענת נכוֹנוּת (assertion) נשלחת ל-IdP כדי לאחזר ב-Assistant.
- הגורם המוגבל (RP) יכול לאמת את האסימון כדי לאמת את המשתמש.
![קריאה ל-API להתחברות](https://developers.google.cn/static/privacy-sandbox/assets/images/login-api-call-a55fdb8f753e8.png?authuser=0000&hl=he)
המערכות ה-RP אמורות לתמוך בדפדפנים שלא תומכים ב-FedCM, לכן למשתמשים צריכה להיות אפשרות להשתמש בתהליך כניסה קיים שאינו של FedCM. עד קובצי Cookie של צד שלישי הופסקו לחלוטין, הם אמורים להישאר לא בעייתי.
לאחר שהאסימון מאומת על ידי שרת ה-RP, ה-RP עשוי לרשום את המשתמש או לאפשר להם להיכנס ולהתחיל סשן חדש.
ממשק API של רמז להתחברות
אחרי שהמשתמש נכנס לחשבון, לפעמים הגורם הנסמך (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
, בתיבת הדו-שיח של FedCM מוצגת בקשת התחברות,
שמאפשר למשתמש להתחבר לחשבון IdP שתואם לרמז המבוקש
הגורם המוגבל. כשהמשתמש יקיש על ההנחיה, ייפתח חלון קופץ עם
כתובת ה-URL לכניסה שצוינה בקובץ התצורה. לאחר מכן הקישור
מצורף לרמז להתחברות ולפרמטרים של השאילתה בקשר לדומיין.
![דוגמה לבקשת התחברות כשאין חשבונות שתואמים ל-domainHint.](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-123.jpg?authuser=0000&hl=he)
domainHint
.להציג הודעת שגיאה
לפעמים, יכול להיות ש-IdP לא יוכל להנפיק אסימון מסיבות לגיטימיות, כאילו הלקוח אינו מורשה, השרת אינו זמין באופן זמני. אם המיקום ה-IdP מחזיר 'שגיאה' התגובה, גם ה-RP יכול לקלוט אותו, וגם Chrome מודיע למשתמש על ידי הצגת ממשק משתמש של דפדפן עם פרטי השגיאה שסופקו על ידי ה-IdP.
![A](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-120-4.png?authuser=0000&hl=he)
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
.
אכיפת גישור באמצעות 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")
אפשר לקבל מידע נוסף על אופן הפעולה של מדיניות ההרשאות בקטע שליטה תכונות דפדפן עם הרשאות מדיניות.