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

הצדדים הנסמכים (RP) צריכים לבצע את השלבים הבאים כדי להפעיל את FedCM באתר שלהם:

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

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

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

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

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

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

מאפיין הקשר

באמצעות המאפיין האופציונלי context, ה-RP יכול לשנות את המחרוזת בממשק המשתמש של תיבת הדו-שיח של FedCM (לדוגמה, 'כניסה אל rp.example…', 'שימוש ב-idp.example…') כדי להתאים את ההודעה להקשרי אימות מוגדרים מראש, למשל. המאפיין context יכול לקבל את הערכים הבאים:

• ‫signin (ברירת מחדל)
• signup
• use

לדוגמה, הגדרת context ל-use תוביל להודעה הבאה:

הדפדפן מטפל בתרחישים לדוגמה של הרשמה וכניסה באופן שונה, בהתאם לנוכחות של approved_clients בתגובה מנקודת הקצה של רשימת החשבונות. בדפדפן לא יוצג טקסט של גילוי נאות "To continue with ...." אם המשתמש כבר נרשם ל-RP.
הנכס providers מקבל מערך של אובייקטים מסוג IdentityProvider שיש להם את המאפיינים הבאים:

מאפיין Providers

הנכס providers מקבל מערך של אובייקטים מסוג IdentityProvider שיש להם את המאפיינים הבאים:

מצב פעיל

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

כדי להשתמש ב-FedCM במצב פעיל:

1. בודקים את הזמינות של התכונה בדפדפן של המשתמש.
2. קריאה ל-API באמצעות תנועת משתמש זמנית, כמו לחיצה על לחצן.
3. מעבירים את הפרמטר mode לקריאה ל-API:

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

סמל מותאם אישית במצב פעיל

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

קריאה ל-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")

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

Login Hint API

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

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

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

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

Domain Hint API

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

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

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

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

פרמטרים מותאמים אישית

התכונה 'פרמטרים מותאמים אישית' מאפשרת ל-RP לספק פרמטרים נוספים של מפתח/ערך לנקודת הקצה של טענת הנכוֹנוּת (assertion) של הזהות. באמצעות Parameters API, ספקי ה-RP יכולים להעביר פרמטרים נוספים ל-IdP כדי לבקש הרשאות למשאבים מעבר לכניסה בסיסית. העברת פרמטרים נוספים יכולה להיות שימושית בתרחישים הבאים:

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

כדי להשתמש ב-API, ה-RP מוסיף פרמטרים לנכס 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'
        }
      },
    }
  });

הדפדפן יתרגם את זה באופן אוטומטי לבקשת POST ל-IdP עם פרמטרים כאובייקט יחיד של JSON שעבר סריאליזציה וקידוד לכתובת URL:

  // The assertion endpoint is drawn from the config file
  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

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

אם ל-RP נדרשות הרשאות נוספות, ה-IdP יכול לספק קישור להפניה אוטומטית. לדוגמה, ב-node.js:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

שדות

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

כדי להשתמש בתכונה 'שדות', RP צריך להוסיף מערך fields בקריאה ל-navigator.credentials.get(). השדות יכולים להכיל כל שילוב של name, ‏ email ו-picture. אפשר להרחיב את האפשרות הזו כך שתכלול ערכים נוספים בעתיד. בקשה עם fields תיראה כך:

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only user email and profile picture
        fields: [ 'email', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',

      },
    }
  });

הדפדפן יתרגם אותו באופן אוטומטי לבקשת HTTP לנקודת הקצה של טענת הנכוֹנוּת של הזהות, שכוללת את הפרמטר fields שצוין על ידי RP, עם השדות שהדפדפן חשף למשתמש בפרמטר disclosure_shown_for. מטעמי תאימות לאחור, הדפדפן ישלח גם את הערך disclosure_text_shown=true אם טקסט הגילוי הנאות הוצג והשדות המבוקשים כוללים את כל שלושת השדות: 'name',‏ 'email' ו-'picture'.

  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

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

אם fields הוא מערך ריק, סוכן המשתמש ידלג על ממשק המשתמש של הגילוי הנאות.

זה קורה גם אם התגובה מנקודת הקצה accounts לא מכילה מזהה לקוח שתואם ל-RP ב-approved_clients.

במקרה כזה, הערך של disclosure_text_shown שנשלח אל נקודת הקצה של טענת הנכוֹנוּת של הזהות הוא 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

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

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

  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. 'אימות ראשוני' כאן פירושו שהמשתמש יוצר חשבון או נכנס לאתר של RP על ידי הקשה על הלחצן 'המשך בתור…' בתיבת הדו-שיח של 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 הוא מאפיין ב-Credential Management API, והוא פועל באותו אופן כמו ב-PasswordCredential וב-FederatedCredential, ויש לו תמיכה חלקית גם ב-PublicKeyCredential. המאפיין יכול לקבל את ארבעת הערכים הבאים:

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

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

• אפשר להשתמש ב-FedCM. לדוגמה, המשתמש לא השבית את FedCM ברמת הארגון או ברמת RP בהגדרות.
• המשתמש השתמש רק בחשבון אחד עם FedCM API כדי להיכנס לאתר בדפדפן הזה.
• המשתמש נכנס ל-IdP באמצעות החשבון הזה.
• האימות מחדש האוטומטי לא התרחש ב-10 הדקות האחרונות.
• ה-RP לא קרא ל-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 > כניסה אוטומטית.
• ב-Chrome ל-Android, פותחים את הגדרות > מנהל הסיסמאות > מקישים על גלגל השיניים בפינה השמאלית העליונה > כניסה אוטומטית.

השבתת המתג מאפשרת למשתמש לבטל את ההסכמה להתנהגות של אימות אוטומטי לגמרי. ההגדרה הזו מאוחסנת ומסונכרנת במכשירים השונים, אם המשתמש מחובר לחשבון 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 בהגדרות הדפדפן.

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

השלבים הבאים