הטמעת פתרון זהויות באמצעות FedCM בצד של ספק הזהויות

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

כדי להטמיע את FedCM, IdPs צריכים לבצע את השלבים הבאים:

1. יוצרים קובץ well-known.
2. יוצרים קובץ תצורה.
3. יוצרים את נקודות הקצה הבאות:
   • נקודת קצה של חשבון
   • נקודת קצה של הצהרת זהות
   • [אופציונלי] ניתוק נקודת קצה
   • [אופציונלי] Client metadata endpoint
   • נקודת קצה להתחברות
4. לעדכן את הדפדפן לגבי סטטוס ההתחברות של המשתמש.

יצירת קובץ ‎.well-known

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

הקובץ המוכר יכול לכלול את המאפיינים הבאים:

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

  {
     // You must include accounts_endpoint and login_url if your
     // config file specifies a client_metadata_endpoint
    "accounts_endpoint": "https://accounts.idp.example/accounts",
    "login_url": "https://accounts.idp.example/login"
  }

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

• ספק זהויות צריך לתמוך בכמה הגדרות שונות של בדיקה וייצור.
• ספק הזהויות צריך לתמוך בהגדרות שונות לכל אזור (לדוגמה, eu-idp.example ו-us-idp.example).

כדי לתמוך במספר הגדרות (לדוגמה, כדי להבדיל בין סביבת בדיקה לסביבת ייצור), ספק ה-IdP צריך לציין את accounts_endpoint ואת login_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

יצירת קובץ תצורה של ספק זהויות ונקודות קצה

קובץ התצורה של ספק הזהויות מספק רשימה של נקודות קצה שנדרשות לדפדפן. ספקי הזהויות צריכים לארח קובץ תצורה אחד או יותר, ונקודות קצה וכתובות URL נדרשות. כל התשובות בפורמט JSON צריכות להישלח עם סוג התוכן application/json.

כתובת ה-URL של קובץ ההגדרות נקבעת לפי הערכים שמועברים לקריאה navigator.credentials.get() שמופעלת ב-RP. ה-RP יעביר את כתובת ה-URL של קובץ ההגדרות לכל ספק זהויות:

  // Executed on RP's side:
  try {
    const credential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            // To allow users to sign in with the IdP1 using FedCM, RP specifies the IdP's config file URL:
            configUrl: 'https://idp1.example/foo.json', // first IdP
            clientId: '123',
          },
          // To allow users to sign in with the IdP2 using FedCM, RP specifies the IdP's config file URL.
          // Note that multiple IdPs in a single get() are supported from Chrome 136.
          {
            configUrl: 'https://idp2.example/bar.json', // second IdP
            clientId: '456',
          },
        ],
      },
    });

    const token = credential.token;
    // Get the current IdP's configURL to identify which provider the user is signed in with
    const currentIdpConfigUrl = credential.configURL;
    if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
      // handle the case where the user signed in with idp1
    } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
      // handle the case where the user signed in with idp2
    }
  } catch (error) {
    // handle error
  }

הדפדפן יאחזר את קובץ ההגדרות באמצעות בקשת GET ללא הכותרת Origin או הכותרת Referer. לבקשה אין קובצי Cookie והיא לא עוקבת אחרי הפניות אוטומטיות. הפעולה הזו מונעת מספק הזהויות לדעת מי שלח את הבקשה ואיזה RP מנסה להתחבר. לדוגמה:

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

ספק הזהויות צריך להטמיע נקודת קצה של הגדרות שמגיבה עם JSON. קובץ ה-JSON כולל את המאפיינים הבאים:

זוהי דוגמה לגוף התגובה מ-IdP:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "account_label": "developer",
    "supports_use_other_account": true,
    "branding": {
      "background_color": "green",
      "color": "#FFEEAA",
      "icons": [{
        "url": "https://idp.example/icon.ico",
        "size": 25
      }]
    }
  }

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

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

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

כדי לאפשר למשתמש לבחור חשבונות אחרים, ספק הזהויות צריך לציין את התכונה הזו בקובץ ההגדרות:

  {
    "accounts_endpoint" : "/accounts.example",
    "supports_use_other_account": true
  }

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

נקודת הקצה של החשבונות בספק הזהויות מחזירה רשימה של חשבונות שהמשתמש מחובר אליהם בספק הזהויות. אם ספק הזהויות תומך במספר חשבונות, נקודת הקצה הזו תחזיר את כל החשבונות המחוברים.

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

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

כשהשרת מקבל את הבקשה, הוא צריך:

1. מוודאים שהבקשה מכילה כותרת HTTP‏ Sec-Fetch-Dest: webidentity.
2. התאמה בין קובצי ה-Cookie של הסשן לבין המזהים של החשבונות שכבר מחוברים.
3. התשובה תכיל את רשימת החשבונות.

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

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

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "john_doe@idp.example",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "label_hints": ["enterprise", "developer"]
    }, {
      "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"],
      "domain_hints": ["@domain.example"]
    }]
  }

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

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

נקודת קצה של הצהרת זהות

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

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

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&fields=email,picture&disclosure_shown_for=email,picture

כשהשרת מקבל את הבקשה, הוא צריך:

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

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

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

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

{
  // IdP can respond with a token object to authenticate the user
  "token": {
    "access_token": "a1b2c3d4e5f6...",
    "user_info": {
      "email": "jane.doe@company.example",
      "given_name": "Jane",
      "family_name": "Doe"
    }
  }
}

המשך בתכונה

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

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

נקודת הקצה של הצהרת הזהות יכולה להחזיר מאפיין continue_on שכולל נתיב מוחלט או יחסי לנקודת הקצה של הצהרת הזהות.

  {
    // In the id_assertion_endpoint, instead of returning a typical
    // "token" response, the IdP decides that it needs the user to
    // continue on a dialog window:
    "continue_on": "https://idp.example/continue_on_url"
  }

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

  document.getElementById('example-button').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.resolve() חד-פעמית היא הדרך היחידה שבה החלון הראשי (RP) וחלון הדו-שיח (IdP) יכולים לתקשר.
אם המשתמש דוחה את הבקשה, ספק ה-IdP יכול לסגור את החלון על ידי קריאה ל-IdentityProvider.close().

  IdentityProvider.close();

כדי שה-API של Continuation יפעל, נדרשת אינטראקציה מפורשת של המשתמש (קליקים). כך פועל Continuation API במצבי גישור שונים:

• במצב passive:
  • ‫mediation: 'optional' (ברירת מחדל): Continuation API יפעל רק עם תנועת משתמש, כמו לחיצה על לחצן בדף או בממשק המשתמש של FedCM. כשמופעל אימות מחדש אוטומטי ללא תנועת משתמש, לא נפתח חלון דו-שיח וההבטחה נדחית.
  • ‫mediation: 'required': תמיד מבקש מהמשתמש לבצע אינטראקציה, ולכן ה-Continuation API תמיד פועל.
• במצב פעיל:
  • תמיד נדרשת הפעלת המשתמש. ה-API של ההמשכיות תמיד תואם.

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

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

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

‫id_assertion_endpoint יכול גם להחזיר תגובה מסוג error, שיש בה שני שדות אופציונליים:

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

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

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

באמצעות תוויות חשבון בהתאמה אישית, ספק הזהויות יכול להוסיף הערות לחשבונות משתמשים באמצעות תוויות, וספק השירות יכול לבחור לאחזר רק חשבונות עם תוויות ספציפיות על ידי ציון configURL עבור התווית הספציפית הזו. האפשרות הזו שימושית כשספק הזהויות צריך לסנן חשבונות לפי קריטריונים ספציפיים, למשל כדי להציג רק חשבונות ספציפיים לתפקיד כמו "developer" או "hr".

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

נניח שספק זהויות רוצה להבדיל בין חשבונות "developer" לבין חשבונות "hr". כדי לעשות את זה, ספק ה-IdP צריך לתמוך בשתי כתובות configURL עבור "developer" ו-"hr" בהתאמה:

• בקובץ התצורה של המפתח https://idp.example/developer/fedcm.json יש תווית "developer", ובקובץ התצורה של הארגון https://idp.example/hr/fedcm.json יש תווית "hr", כמו בדוגמה הבאה:

  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "account_label": "developer"
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "account_label": "hr"
  }

• בהגדרה כזו, קובץ well-known צריך לכלול את הערכים accounts_endpoint ו-login_url כדי לאפשר שימוש בכמה כתובות configURL:

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

• נקודת הקצה של החשבונות של ספק הזהויות הנפוץ (במקרה הזה https://idp.example/accounts) מחזירה רשימה של חשבונות שכוללת מאפיין label_hints עם תוויות שהוקצו במערך לכל חשבון:

  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "label_hints": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "jane_doe@idp.example",
    "picture": "https://idp.example/profile/4567",
    "label_hints": ["hr"]
    }]
  }

כשספק זהויות רוצה לאפשר למשתמשי "hr" להיכנס לחשבון, הוא יכול לציין את https://idp.example/hr/fedcm.json configURL בקריאה navigator.credentials.get():

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

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

שיקולים נוספים:

• תוויות הן מחרוזות. אם המערך label_hints או השדה account_label משתמשים בערך שהוא לא מחרוזת, המערכת מתעלמת מהערך.
• אם לא מציינים תוויות ב-configURL, כל החשבונות יוצגו בבורר החשבונות של FedCM.
• אם לא מציינים תוויות לחשבון, החשבון הזה יוצג בכלי לבחירת חשבון רק אם גם configURL לא מציין תוויות.
• אם אין חשבון שתואם לתווית המבוקשת במצב פסיבי (בדומה לתכונה Domain Hint), בתיבת הדו-שיח של FedCM מוצגת הנחיה לכניסה, שמאפשרת למשתמש להיכנס לחשבון IdP. במצב הפעיל, חלון תיבת הדו-שיח של הכניסה נפתח ישירות.

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

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

  POST /disconnect.example 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

כשהשרת מקבל את הבקשה, הוא צריך:

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

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

  {
    "account_id": "account456"
  }

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

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

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

הדפדפן שולח בקשת GET באמצעות client_id navigator.credentials.get ללא קובצי Cookie. אם מתבצעת קריאה ל-FedCM API ממקור חוצה אתרים, נשלח גם הפרמטר top_frame_origin. לדוגמה:

  GET /client_metadata.example?client_id=1234&top_frame_origin=https%3A%2F%2Ftop-frame.example HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Accept: application/json
  Sec-Fetch-Dest: webidentity

כשהשרת מקבל את הבקשה, הוא צריך:

1. קובעים את נקודת ההסתמכות (RP) עבור client_id.
2. [אופציונלי] אם top_frame_origin נכלל בבקשה, צריך לבדוק אם ה-RP והמסגרת העליונה הם אותו צד כדי להחליט אם הדפדפן צריך להציג את דומיין ה-iframe. ספקי הזהויות צריכים להגדיר את הלוגיקה המותאמת אישית שלהם כדי לקבוע את זה.
3. שולחים תגובה עם המטא-נתונים של הלקוח.

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

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

  {
    "privacy_policy_url": "https://rp.example/privacy_policy.html",
    "terms_of_service_url": "https://rp.example/terms_of_service.html",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

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

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

נקודת הקצה הזו משמשת כדי לאפשר למשתמש להיכנס ל-IdP.

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

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

כשהמשתמש לוחץ על הלחצן המשך, בדפדפן נפתח חלון דו-שיח של דף הכניסה של ספק הזהויות.

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

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

דיווח לדפדפן על סטטוס הכניסה של המשתמש

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

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

• logged-in
• logged-out
• ‫unknown (ברירת מחדל)

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

  Set-Login: logged-in

לחלופין, אפשר לקרוא לשיטת JavaScript‏ navigator.login.setStatus('logged-in') מהמקור של ספק הזהויות בניווט ברמה העליונה:

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

סטטוס ההתחברות של המשתמש יוגדר כ-logged-in.

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

  Set-Login: logged-out

אפשרות אחרת היא להפעיל את JavaScript API‏ navigator.login.setStatus('logged-out') מהמקור של ספק הזהויות בניווט ברמה העליונה:

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

סטטוס ההתחברות של המשתמש יוגדר כ-logged-out.

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

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

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

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