החל מגרסה 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 של המשך
אפשר לעיין בהדגמה של ה-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();
אם מסיבה כלשהי המשתמש שינה את החשבון שלו בחלון הקופץ (לדוגמה, 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¶m_foo=BAR¶m_ETC=MOAR¶m_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¶m_IDP_SPECIFIC_PARAM=1¶m_foo=BAR¶m_ETC=MOAR¶m_scope=calendar.readonly%20photos.write
קבלת הרשאות באופן דינמי
באופן כללי, הכי מועיל לבקש משתמשים שנדרשים, ולא כשהמפתח חושב שהכי קל ליישם אותו. עבור למשל, בקשת הרשאת גישה למצלמה כשהמשתמש עומד לצלם תמונה מועדפת עליך לבקש אישור ברגע שהמשתמש מגיע האתר. אותה שיטה חלה גם על משאבי שרתים. בקשת הרשאות בלבד כשהם נחוצים למשתמש. פעולה זו נקראת 'הרשאה דינמית'.
כדי לבקש הרשאה באופן דינמי באמצעות FedCM, ה-IdP יכול:
- קוראים לפונקציה
navigator.credentials.get()
עם הפרמטרים הנדרשים שה-IdP יכול כמוscope
. - טענת נכוֹנוּת (assertion) של המזהה
נקודת קצה (endpoint)
מאשרת שהמשתמש כבר מחובר ומגיב עם כתובת URL מסוג
continue_on
. - הדפדפן פותח חלון קופץ עם דף ההרשאות של ה-IdP שבו מופיעה בקשה הרשאה נוספת שתואמת להיקפים המבוקשים.
- אחרי קבלת ההרשאה מה-IdP של
IdentityProvider.resolve()
, החלון נסגרה והשיחה המקוריתnavigator.credentials.get()
של הגורם המוגבל (RP) מקבלת באסימון רלוונטי או בקוד הרשאה, כדי שהגורם המוגבל (RP) יוכל להחליף אותם אסימון גישה מתאים.
ממשק API של Fields
Fields API מאפשר ל-RP: להצהיר על מאפייני חשבון לבקש מה-IdP כדי שהדפדפן יוכל לרנדר ממשק משתמש מתאים לגילוי נאות בתיבת הדו-שיח של FedCM. באחריות ה-IdP כדי לכלול את השדות המבוקשים באסימון המוחזר. כדאי לשקול את הבקשה 'פרופיל בסיסי' ב-OpenID Connect לעומת 'היקפים' ב-OAuth.
![הודעת גילוי נאות במצב ווידג'ט.](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-widget.jpg?authuser=7&hl=he)
![הודעת גילוי נאות במצב לחצן.](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-button.jpg?authuser=7&hl=he)
כדי להשתמש ב-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
אם ה-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
הוא מערך ריק, סוכן המשתמש ידלג על ממשק המשתמש של הגילוי הנאות.
![הודעת הגילוי הנאות לא מוצגת במצב ווידג'ט. בתהליך הצגת הלחצן, המערכת מדלגת לגמרי על ממשק המשתמש של הגילוי הנאות.](https://developers.google.cn/static/privacy-sandbox/assets/images/blog/fedcm-126-without-disclosure-widget.jpg?authuser=7&hl=he)
גם אם תתקבל ממך תגובה בחשבונות
נקודת קצה (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"
}
הפעולה הזאת מאפשרת לנו:
- לשמור על תאימות אחורה וקדימה עם קבצים ידועים קיימים. ובגרסה הקודמת של דפדפנים שכבר פרוסים ברחבי העולם.
- לכלול מספר שרירותי של קובצי תצורה - כל עוד כולם מצביעים על
אותם
accounts_endpoint
ו-login_url
. - לא קיימת הזדמנות להוסיף את האנטרופיה לבקשת האחזור עם פרטי הכניסה
בוצע ל
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": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"labels": ["consumer"]
}], [{
"id": "4567",
"given_name": "Jane",
"name": "Jane Doe",
"email": "jane_doe@idp.example",
"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 באתר הזה.
גרסת מקור לניסיון: 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 פעיל. כלומר, ברגע שהמשתמש מנותק, עם בקשת ההרשאה, תוצג הנחיה.
השתתפות בגרסת המקור לניסיון
אפשר לנסות את חבילת 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
- עוברים לדף הרישום לגרסת המקור לניסיון.
- לוחצים על הלחצן Register וממלאים את הטופס כדי לבקש אסימון.
- מזינים את מקור ה-IdP בתור מקור אינטרנט.
- בדיקת התאמות של צד שלישי כדי להחדיר את האסימון עם JavaScript במקורות אחרים.
- לוחצים על שליחה.
- מטמיעים את האסימון שהונפק באתר של צד שלישי.
כדי להטמיע את האסימון באתר של צד שלישי, צריך להוסיף את הקוד הבא ספריית JavaScript או SDK שמוצגים מהמקור של ה-IdP.
const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);
מחליפים את TOKEN_GOES_HERE
באסימון שלכם.