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

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

אם הלקוח שלכם משתמש בספריית הלקוח של Google API ל-JavaScript או בספריות קודמות אחרות להרשאה, תוכלו לקרוא מידע נוסף במאמר מעבר ל-Google Identity Services.

אימות והרשאה

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

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

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

אם התרחיש לדוגמה שלכם נוגע רק לאימות, כדאי להמשיך לקרוא את הדף הזה.

אם התרחיש לדוגמה שלכם כולל הרשאה, קראו את המאמרים איך הרשאות המשתמשים פועלות והעברה ל-Google Identity Services כדי לוודא שהאפליקציה שלכם משתמשת בממשקי ה-API החדשים והמשופרים.

מה השתנה

למשתמשים, הספרייה החדשה של Google Identity Services מציעה שיפורים רבים בנוחות השימוש. בין התכונות המרכזיות:

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

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

• האפשרות להוסיף כניסה של משתמשים לתוכן הסטטי של האתר באמצעות HTML בלבד,
• בין אימות כניסה לבין הרשאה ושיתוף נתוני משתמשים, אין יותר צורך במורכבות של שילוב OAuth 2.0 כדי להכניס משתמשים לאתר.
• אנחנו עדיין תומכים בשני המצבים – חלון קופץ והפניה אוטומטית – אבל התשתית של Google ל-OAuth 2.0 מפנה עכשיו לנקודת הקצה של הכניסה של שרת הקצה העורפי.
• איחוד היכולות משתי הספריות הקודמות של Google Identity ו-Google API ל-JavaScript לספרייה חדשה אחת,
• בתשובות של כניסה לחשבון, עכשיו תוכלו להחליט אם להשתמש בהבטחה או לא, והסרנו את ההפניה באמצעות פונקציות בסגנון getter כדי לפשט את הפשטות.

דוגמה להעברת כניסה

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

ספריות והגדרות

הספרייה הקודמת של הפלטפורמה לכניסה באמצעות חשבון Google: apis.google.com/js/platform.js וספריית הלקוח של Google APIs ל-JavaScript: gapi.client, לא נדרשות יותר לאימות ולהרשאה של המשתמשים. הן הוחלפו בספריית JavaScript חדשה אחת של Google Identity Services:‏ accounts.google.com/gsi/client.

שלושת המודולים הקודמים של JavaScript‏: api,‏ client ו-platform, המשמשים לכניסה, נטענים מ-apis.google.com. כדי לעזור לכם לזהות מיקומים שבהם הספרייה הקודמת עשויה להיכלל באתר שלכם, בדרך כלל:

• לחצן ברירת המחדל לכניסה לחשבון טען את apis.google.com/js/platform.js,
• גרפיקת לחצן בהתאמה אישית נטענת apis.google.com/js/api:client.js, וגם
• שימוש ישיר ב-gapi.client טוען את apis.google.com/js/api.js.

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

• באפליקציות לבדיקה ולייצור נעשה שימוש בפרויקטים נפרדים, ולכל אחת מהן יש מזהי לקוח משלה.
• סוג מזהה הלקוח ב-OAuth 2.0 הוא 'אפליקציית אינטרנט', וגם
• הפרוטוקול HTTPS משמש למקורות מורשים של JavaScript ולהפניות אוטומטיות של מזהי URI.

זיהוי הקוד המושפע ובדיקה

קובץ cookie לניפוי באגים יכול לעזור לכם לאתר את הקוד המושפע ולבדוק את ההתנהגות אחרי ההוצאה משימוש.

באפליקציות גדולות או מורכבות, יכול להיות שיהיה קשה למצוא את כל הקוד שמושפע מההוצאה משימוש של המודול gapi.auth2. כדי לתעד במסוף את השימוש הקיים ביכולות שיוצאו משימוש בקרוב, צריך להגדיר את הערך של קובץ ה-cookie G_AUTH2_MIGRATION לערך informational. אפשר גם להוסיף נקודתיים ואחריה ערך מפתח כדי לרשום ביומן גם באחסון הסשן. אחרי הכניסה וקבלת פרטי הכניסה, בודקים או שולחים יומנים שנאספו לקצה עורפי לניתוח מאוחר יותר. לדוגמה, הפקודה informational:showauth2use שומרת את המקור ואת כתובת ה-URL במפתח אחסון של סשן בשם showauth2use.

כדי לאמת את התנהגות האפליקציה כשהמודול gapi.auth2 כבר לא נטען, מגדירים את הערך של קובץ ה-cookie G_AUTH2_MIGRATION כ-enforced. כך אפשר לבדוק התנהגות לאחר ההוצאה משימוש לפני תאריך האכיפה.

ערכים אפשריים של קובץ ה-cookie G_AUTH2_MIGRATION:

• enforced לא לטעון את המודול gapi.auth2.
• informational רישום ביומן של השימוש ביכולות שהוצאו משימוש במסוף JS. בנוסף, מתעדים ביומן את אחסון הסשן כשמגדירים שם מפתח אופציונלי: informational:key-name.

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

HTML ו-JavaScript

בתרחיש הזה של כניסה לאימות בלבד, מוצגים קוד לדוגמה ורינדורים של לחצן 'כניסה באמצעות חשבון Google' הקיים. בוחרים מבין המצבים 'חלון קופץ' או 'הפניה אוטומטית' כדי לראות את ההבדלים באופן שבו התשובה לאימות מטופלת על ידי קריאה חוזרת (callback) של JavaScript או על ידי הפניה אוטומטית מאובטחת לנקודת הקצה להתחברות לשרת הקצה העורפי.

הדרך הקודמת

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

הדרך החדשה

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

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

בדוגמה הזו לאימות בלבד, הספרייה accounts.google.com/gsi/client, הכיתה g_id_signin והאובייקט g_id_onload החדשים מחליפים את הספרייה apis.google.com/js/platform.js ואת האובייקט g-signin2 הקודמים.

בנוסף לעיבוד הלחצן החדש המותאם אישית, קוד הדוגמה מציג גם את חלון הקופץ החדש של One Tap. בכל מקום שבו אתם מציגים את הלחצן המותאם אישית, מומלץ מאוד להציג גם את החלון הקופץ של One Tap כדי לצמצם את החיכוך של המשתמשים במהלך ההרשמה והכניסה.

לא מומלץ לעשות זאת בגלל החיכוך המוגבר בתהליך הכניסה, אבל אפשר להציג את הלחצן המותאם אישית החדש לבד, בלי להציג בו-זמנית את תיבת הדו-שיח של One Tap. כדי לעשות זאת, צריך להגדיר את המאפיין data-auto_prompt כ-false.

ממשקי API ל-HTML ול-JavaScript

בדוגמה הקודמת מוצג איך להשתמש ב-HTML API החדש כדי להוסיף כניסה לאתר. לחלופין, אפשר להשתמש ב-JavaScript API, שהוא מקביל מבחינה פונקציונלית, או לשלב בין ממשקי API של HTML ו-JavaScript באתר.

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

כניסה מכל דף בהקשה אחת

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

כדי לאפשר כניסה מכל דף, מומלץ לכלול את g_id_onload בכותרת עליונה, בכותרת תחתונה או באובייקט אחר ששותף בכל האתר.

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

תגובת אסימון

כדי לבצע כניסה של משתמשים, לא תצטרכו יותר להבין את קודי ההרשאות, אסימוני הגישה או אסימוני הרענון של OAuth 2.0 או לעבוד איתם. במקום זאת, נעשה שימוש באסימון מזהה מסוג JSON Web Token‏ (JWT) כדי לשתף את סטטוס הכניסה ואת פרופיל המשתמש. כתוצאה מכך, לא צריך יותר להשתמש בשיטות גישה בסגנון 'getter' כדי לעבוד עם נתוני פרופיל המשתמש.

פרטי הכניסה המאובטחים של אסימון המזהה מסוג JWT חתום על ידי Google מוחזרים:

• למטפל ה-callback של JavaScript שמבוסס על הדפדפן של המשתמש במצב חלון קופץ, או
• לשרת הקצה העורפי דרך הפניה אוטומטית של Google לנקודת הקצה להתחברות, כשהלחצן 'כניסה באמצעות חשבון Google' ux_mode מוגדר כ-redirect.

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

• שיחות אל googleUser.getBasicProfile(),
• הפניות אל BasicProfile וקריאות משויכות ל-methods getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail(),
• שימוש באובייקט AuthResponse.

במקום זאת, כדי לעבוד עם נתונים של פרופיל המשתמש, משתמשים בהפניות ישירות לשדות משנה של credential באובייקט ה-JWT החדש CredentialResponse.

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

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

הסכמה מהמשתמשים וביטול ההרשאה

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

המשתמשים יכולים לבטל את ההרשאות ולנתק את האפליקציה שלכם מחשבון Google שלהם בכתובת https://myaccount.google.com/permissions. לחלופין, הם יכולים להתנתק ישירות מהאפליקציה על ידי הפעלת קריאה ל-API שתטמיעו. השיטה הקודמת disconnect הוחלפה בשיטה החדשה revoke.

כשמשתמש מוחק את החשבון שלו בפלטפורמה, מומלץ להשתמש ב-revoke כדי לנתק את האפליקציה מחשבון Google שלו.

בעבר, אפשר היה להשתמש ב-auth2.signOut() כדי לנהל את היציאה של המשתמשים מהאפליקציה. צריך להסיר את כל השימוש ב-auth2.signOut(), והאפליקציה צריכה לנהל ישירות את סטטוס הכניסה וסטטוס הסשן של כל משתמש.

מצב הסשן ומאזינים

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

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

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

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

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

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

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

מסירים את כל ההפניות ל-auth2.attachClickHandler() ולמפעילי ה-callback הרשומים שלו.

בעבר, נעשה שימוש ב-Listeners כדי לשתף שינויים בסטטוס המחובר בחשבון Google של משתמש. אין יותר תמיכה במאזינים.

מסירים את כל ההפניות אל listen(), auth2.currentUser ו-auth2.isSignedIn.

עוגיות

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

קובץ ה-cookie G_ENABLED_IDPS שהוגדר על ידי ספריית הפלטפורמה הקודמת לכניסה באמצעות חשבון Google לא נמצא יותר בשימוש.

הספרייה החדשה של Google Identity Services עשויה להגדיר את קובצי ה-cookie האלה בכמה דומיינים, בהתאם לאפשרויות ההגדרה שלכם:

• המשתנה g_state שומר את סטטוס היציאה של המשתמש מהחשבון, והוא מוגדר כשמשתמשים בחלון הקופץ של 'הקשה אחת' או בכניסה האוטומטית.

• g_csrf_token הוא קובץ cookie לשליפה כפולה שמשמש למניעת התקפות CSRF, והוא מוגדר כשנקודת הקצה של הכניסה לחשבון נקראת. אפשר להגדיר במפורש את הערך של ה-URI להתחברות, או להגדיר אותו כברירת מחדל ל-URI של הדף הנוכחי. יכול להיות שנקודת הקצה להתחברות תתקשר בתנאים הבאים כשמשתמשים ב:

  • HTML API עם data-ux_mode=redirect או כשמוגדר data-login_uri, או

  • JavaScript API עם ux_mode=redirect, שבו google.accounts.id.prompt() לא משמש להצגת 'הקשה אחת' או 'כניסה אוטומטית'.

אם יש לכם שירות שמנהל קובצי cookie, הקפידו להוסיף את שני קובצי ה-cookie החדשים ולהסיר את קובץ ה-cookie הקודם בסיום ההעברה.

אם אתם מנהלים מספר דומיינים או תת-דומיינים, ראו Display One Tap במספר תת-דומיינים לקבלת הוראות נוספות לעבודה עם קובץ ה-cookie g_state.

חומר עזר בנושא העברת אובייקטים לכניסה של משתמשים