כניסה באמצעות חשבון Google באמצעות ממשקי API של FedCM

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

סטטוס הספרייה

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

עדכון שתומך בתאימות לאחור מוסיף לספריית הכניסה באמצעות חשבון Google את ממשקי ה-API של FedCM. רוב השינויים מתבצעים בצורה חלקה, אבל יש הבדלים בין הגרסה הקודמת לעדכון בהנחיות למשתמשים, ב-permissions-policy של iframe ובמדיניות אבטחת התוכן (CSP). השינויים האלה עשויים להשפיע על אפליקציית האינטרנט שלכם, וייתכן שתצטרכו לבצע שינויים בקוד האפליקציה ובהגדרות האתר.

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

אחרי תקופת המעבר, ממשקי FedCM API יהיו חובה לכל אפליקציות האינטרנט שמשתמשות בספריית Google Sign-In.

ציר הזמן

עדכון אחרון: ספטמבר 2024

אלה התאריכים והשינויים שמשפיעים על התנהגות הכניסה של המשתמשים:

  • מרץ 2023 הוצאה משימוש של התמיכה בספריית הפלטפורמה של כניסה באמצעות חשבון Google.
  • מתחיל תקופת המעבר של יולי 2024, ונוספת תמיכה בספריית הפלטפורמה של כניסה באמצעות חשבון Google בממשקי FedCM API. כברירת מחדל, Google קובעת את אחוז הבקשות של משתמשים לכניסה באמצעות FedCM במהלך התקופה הזו. אפליקציות אינטרנט יכולות לשנות את ההתנהגות הזו באופן מפורש באמצעות הפרמטר use_fedcm.
  • החל ממרץ 2025, חובה להשתמש בממשקי ה-API של FedCM בספריית הפלטפורמה של 'כניסה באמצעות חשבון Google'. לאחר מכן, הפרמטר use_fedcm יתעלם וכל הבקשות של משתמשים לכניסה ישתמשו ב-FedCM.

השלבים הבאים

יש שלוש אפשרויות:

  1. מבצעים הערכת השפעה, ואם צריך, מעדכנים את אפליקציית האינטרנט. הגישה הזו מאפשרת לבדוק אם נעשה שימוש בתכונות שדורשות שינויים באפליקציית האינטרנט. ההוראות מפורטות בקטע הבא במדריך.
  2. מעבר ל ספריית Google Identity Services‏ (GIS). מומלץ מאוד לעבור לספריית הכניסה העדכנית והנתמכת. כדי לעשות זאת, פועלים לפי ההוראות האלה.
  3. לא לעשות דבר. אפליקציית האינטרנט תתעדכן באופן אוטומטי כשספריית הכניסה לחשבון Google תועבר לממשקי FedCM API לכניסת משתמשים. זו האפשרות שמצריכה את המאמץ הקטן ביותר, אבל יש סיכון מסוים שהמשתמשים לא יוכלו להיכנס לאפליקציית האינטרנט.

ביצוע הערכת השפעה

יש לפעול לפי ההוראות הבאות כדי לקבוע אם אפשר לעדכן את אפליקציית האינטרנט בצורה חלקה באמצעות עדכון תואם לאחור, או אם יש צורך בשינויים כדי למנוע מהמשתמשים להיכנס לחשבון כשספריית הפלטפורמה של Google Sign-in תאמץ באופן מלא את ממשקי ה-API של FedCM.

הגדרה

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

לפני שממשיכים:

  • מעדכנים את Chrome למחשב לגרסה האחרונה. כדי לבדוק את Chrome ל-Android צריך את הגרסה M128 ואילך, ולא ניתן לבדוק אותו בגרסאות קודמות.
  • מגדירים את use_fedcm לערך true כשמאתחלים את הספרייה של פלטפורמת הכניסה באמצעות חשבון Google באפליקציית האינטרנט. בדרך כלל, האיפוס נראה כך:
    • gapi.client.init({use_fedcm: true}), או
    • gapi.auth2.init({use_fedcm: true}), או
    • gapi.auth2.authorize({use_fedcm: true}).
  • ביטול התוקף של גרסאות ששמורות במטמון של ספריית הפלטפורמה לכניסה באמצעות חשבון Google. בדרך כלל אין צורך בשלב הזה, כי הגרסה האחרונה של הספרייה נשלחת ישירות לדפדפן על ידי הכללת api.js, ‏ client.js או platform.js בתג <script src> (הבקשה עשויה להשתמש בכל אחד משמות החבילות האלה לספרייה).

  • מאשרים את הגדרות ה-OAuth של מזהה הלקוח ב-OAuth:

    1. פותחים את הדף Credentials (פרטי כניסה) של Google API Console

    2. מוודאים שה-URI של האתר נכלל במקורות JavaScript מורשים. ה-URI כולל רק את הסכימה ואת שם המארח המלא. לדוגמה, https://www.example.com.

    3. אפשר גם להחזיר את פרטי הכניסה באמצעות הפניה אוטומטית לנקודת קצה שאתם מארחים, במקום באמצעות קריאה חוזרת (callback) של JavaScript. במקרה כזה, צריך לוודא שה-URI להפניה האוטומטית נכללים בURI להפניה אוטומטית מורשים. מזהי URI להפניה אוטומטית כוללים את הסכימה, שם המארח המלא והנתיב, ועליהם לעמוד בכללי האימות של מזהי URI להפניה אוטומטית. לדוגמה: https://www.example.com/auth-receiver.

בדיקה

אחרי שמבצעים את ההוראות בקטע 'הגדרה':

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

כדי לבדוק אם יש צורך בשינויים ב-permissions-policy וב-Content Security Policy, בודקים את הבקשה לספריית הפלטפורמה של כניסה באמצעות חשבון Google. כדי לעשות זאת, מאתרים את הבקשה לפי השם והמקור של הספרייה:

  • ב-Chrome, פותחים את החלונית רשת בכלי הפיתוח וטוענים מחדש את הדף.
  • משתמשים בערכים בעמודות Domain ו-Name כדי לאתר את הבקשה לספרייה:
    • הדומיין הוא apis.google.com ו-
    • השם הוא api.js,‏ client.js או platform.js. הערך הספציפי של Name תלוי בחבילת הספרייה שהמסמך ביקש.

לדוגמה, אפשר לסנן לפי apis.google.com בעמודה Domain וplatform.js בעמודה Name.

בדיקת המדיניות בנושא הרשאות iframe

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

אחרי שמבצעים את ההוראות לאיתור הבקשה של ספריית הכניסה לחשבון Google, בוחרים את הבקשה של ספריית הכניסה לחשבון Google בחלונית Network (רשת) של DevTools ומאתרים את הכותרת Sec-Fetch-Site בקטע Request Headers (כותרות הבקשה) בכרטיסייה Headers (כותרות). אם הערך של הכותרת הוא:

  • same-siteאו same-origin, כללי המדיניות לגבי מקורות שונים לא חלים ואין צורך לבצע שינויים.
  • יכול להיות שיהיה צורך לבצע שינויים ב-cross-origin אם נעשה שימוש ב-iframe.

כדי לוודא ש-iframe קיים:

  • בוחרים בחלונית Elements (רכיבים) ב-Chrome DevTools,
  • מקישים על Ctrl-F כדי למצוא iframe במסמך.

אם נמצא iframe, בודקים את המסמך כדי לחפש קריאות לפונקציות של gapi.auth2 או להנחיות script src שמטעינות את ספריית הכניסה לחשבון Google בתוך ה-iframe. במקרה כזה:

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

בדיקת מדיניות Content Security Policy

אם באתר שלכם מוגדרת מדיניות אבטחת תוכן, יכול להיות שתצטרכו לעדכן את ה-CSP כדי לאפשר שימוש בספריית 'כניסה באמצעות חשבון Google'.

אחרי שמבצעים את ההוראות לאיתור הבקשה של ספריית הכניסה לחשבון Google, בוחרים את הבקשה של ספריית הכניסה לחשבון Google בחלונית Network (רשת) של DevTools ומאתרים את הכותרת Content-Security-Policy בקטע Response Headers (כותרות התגובה) בכרטיסייה Headers (כותרות).

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

  • הוספת https://apis.google.com/js/, https://accounts.google.com/gsi/ ו-https://acounts.google.com/o/fedcm/ לכל הוראה מסוג connect-src,‏ default-src או frame-src.

  • הוספת https://apis.google.com/js/bundle-name.js להנחיה script-src. מחליפים את bundle-name.js ב-api.js, ב-client.js או ב-platform.js, בהתאם לחבילת הספריות שהמסמך מבקש.

בדיקת שינויים בהנחיות למשתמשים

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

תמונה של תיבת הדו-שיח של FedCM

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

הפעלת משתמשים

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

  • משתמש נכנס בפעם הראשונה לאפליקציית אינטרנט באמצעות מכונה חדשה של דפדפן, או
  • מתבצעת קריאה ל-GoogleAuth.signIn.

כיום, אם המשתמש נכנס בעבר לאתר שלכם, תוכלו לקבל את פרטי הכניסה שלו כשאתם מאתחלים את הספרייה של Google Sign-In באמצעות gapi.auth2.init, בלי אינטראקציות נוספות עם המשתמש. לא ניתן לעשות זאת יותר, אלא אם המשתמש עבר לפחות פעם אחת את תהליך הכניסה ל-FedCM.

אם תבחרו להצטרף ל-FedCM ותפעילו את GoogleAuth.signIn, בפעם הבאה שאותו משתמש יבקר באתר שלכם, gapi.auth2.init יוכל לקבל את פרטי הכניסה של המשתמש במהלך האינטראליזציה בלי אינטראקציה מהמשתמש.

תרחישים נפוצים לדוגמה

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

  • שילוב של 'כניסה באמצעות חשבון Google' באפליקציית האינטרנט

    בהדגמה הזו, רכיב <div> וכיתה מעבדים את הלחצן, ולמשתמשים שכבר מחוברים, האירוע onload בדף מחזיר את פרטי הכניסה של המשתמש. נדרש אינטראקציה של המשתמש כדי להיכנס לחשבון וליצור סשן חדש.

    האימפוליזציה של הספרייה מתבצעת על ידי המחלקה g-signin2 שמפעילה את gapi.load ואת gapi.auth2.init.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn במהלך הכניסה או ל-auth2.signOut ביציאה.

  • יצירת לחצן מותאם אישית לכניסה באמצעות חשבון Google

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

    האתחול של הספרייה מתבצע באמצעות אירוע onload לספרייה platform.js, והלחצן מוצג על ידי gapi.signin2.render.

    תנועת משתמש, לחיצה על לחצן הכניסה, גורמת לקריאה ל-auth2.signIn.

    בהדגמה השנייה, נעשה שימוש ברכיב <div>, בסגנונות CSS ובגרפיקה בהתאמה אישית כדי לשלוט במראה של לחצן הכניסה. צריכה להיות אינטראקציה של משתמש כדי להיכנס לחשבון ולהתחיל סשן חדש.

    האתחול של הספרייה מתבצע בזמן הטעינה של המסמך באמצעות פונקציית התחלה שמפעילה את gapi.load,‏ gapi.auth2.init ו-gapi.auth2.attachClickHandler.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut ביציאה.

  • מעקב אחרי מצב הסשן של המשתמש

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

    כדי לאתחל את הספרייה, קוראים ישירות ל-gapi.load, ל-gapi.auth2.init ול-gapi.auth2.attachClickHandler() אחרי ש-platform.js נטען באמצעות script src.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut ביציאה.

  • בקשה להרשאות נוספות

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

    האירוע onload בספרייה platform.js מבצע את האיניציאליזציה של הספרייה באמצעות קריאה ל-gapi.signin2.render.

    תנועת משתמש, לחיצה על רכיב <button>, מפעילה בקשה להיקפי הרשאות נוספים של OAuth 2.0 באמצעות googleUser.grant או auth2.signOut בזמן היציאה מהחשבון.

  • שילוב של כניסה באמצעות חשבון Google באמצעות מאזינים

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

    האתחול של הספרייה מתבצע בזמן הטעינה של המסמך באמצעות פונקציית התחלה שמפעילה את gapi.load,‏ gapi.auth2.init ו-gapi.auth2.attachClickHandler. לאחר מכן, משתמשים ב-auth2.isSignedIn.listen וב-auth2.currentUser.listen כדי להגדיר התראות על שינויים במצב הסשן. לבסוף, auth2.SignIn נקרא כדי להחזיר את פרטי הכניסה של משתמשים שנכנסו לחשבון.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut ביציאה.

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

    בהדגמה הזו, תנועת משתמש משמשת לבקשת קוד אימות של OAuth 2.0, וקריאה חוזרת (callback) של JS מבצעת קריאה ל-AJAX כדי לשלוח את התשובה לשרת הקצה העורפי לצורך אימות.

    האתחול של הספרייה מתבצע באמצעות אירוע onload לספרייה platform.js, שמשתמש בפונקציית התחלה כדי לקרוא ל-gapi.load ול-gapi.auth2.init.

    תנועת משתמש, לחיצה על רכיב <button>, מפעילה בקשה לקוד הרשאה באמצעות קריאה ל-auth2.grantOfflineAccess.

  • SSO בפלטפורמות שונות

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

ניהול תקופת המעבר

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

אם בוחרים להביע הסכמה, המשתמש עובר את תהליך הכניסה של FedCM. אם בוחרים לבטל את ההסכמה, המשתמש עובר את תהליך הכניסה הקיים. ההתנהגות הזו נשלטת באמצעות הפרמטר use_fedcm.

הבעת הסכמה

כדאי לקבוע אם כל ניסיונות הכניסה לאתר שלכם, או חלק מהם, ישתמשו בממשקי ה-API של FedCM. כדי לעשות זאת, מגדירים את use_fedcm לערך true כשמאתחלים את ספריית הפלטפורמה. במקרה הזה, בקשת הכניסה של המשתמש משתמשת ב-API של FedCM.

ביטול הצטרפות

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

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

עזרה

אפשר לחפש או לפרסם שאלות ב-StackOverflow באמצעות התג google-signin.