סקירה כללית

בחירת מסלול השילוב

בוחרים את הנתיב שהכי מתאים לצרכים שלכם:

נתיב	הכי טוב עבור	מידע נוסף
Universal Commerce Protocol‏ (UCP)	מוֹכרים וקמעונאים.	מסמכי UCP
קישור חשבונות רגיל	בית חכם, טלוויזיה ו-YouTube.	Docs

הערה: דרכי השילוב האלה משלימות זו את זו. אם אתם מטמיעים את UCP, מומלץ לעיין במדריך UCP Identity Linking כדי לקבל מידע על הדרישות הספציפיות למוצר, ובמסמכי התיעוד האלה כדי לקבל פרטים על הטמעת OAuth.

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

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

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

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

אלה כמה מהסיבות להטמעת קישור של חשבון Google:

• שיתוף נתונים של משתמש מהפלטפורמה עם אפליקציות ושירותים של Google.

• שילוב עם Google שופינג ופלטפורמות שמבוססות על AI (חיפוש Google, ‏ Gemini) באמצעות Universal Commerce Protocol‏ (UCP).

• הפעלת תוכן של סרטונים וסרטים באמצעות Google TV.

• ניהול ושליטה במכשירים שמחוברים ל-Google Smart Home באמצעות אפליקציית Google Home ו-Google Assistant, למשל "Ok Google, תדליק את האורות".

• ליצור חוויות ופונקציות מותאמות אישית למשתמשים ב-Google Assistant באמצעות פעולות שיחה, כמו "Ok Google, תזמין לי את הקפה הרגיל שלי מסטארבקס".

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

• מילוי מראש של חשבונות חדשים במהלך ההרשמה בנתונים ששותפו בהסכמה מפרופיל בחשבון Google.

יכולות ודרישות

בטבלה הבאה מוגדרים התמיכה וההמלצות לכל תהליך קישור.

קישור Flow	תכונות רגילות	תכונות UCP
App Flip	מומלץ	מומלץ
קישור יעיל יותר	מומלץ	מומלץ
קישור OAuth	חובה (Fallback)	חובה (Fallback)
OAuth 2.1	מומלץ	מומלץ

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

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

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

תהליכי קישור חשבונות

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

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

קישור OAuth

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

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

שימו לב: בתהליכי עבודה של MCP,‏ UCP ותהליכי עבודה מונחי סוכנים, חובה להשתמש ב-OAuth 2.1, וזרם הענקת גישה משתמע לא אפשרי. במקום זאת, אפשר להשתמש בתהליך של הרשאה באמצעות קוד.

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

איור 1. קישור חשבון בטלפון של משתמש באמצעות קישור OAuth

קישור אפליקציות מבוסס-OAuth ('קישור אפליקציות')

תהליך OAuth שמפנה משתמשים אל האפליקציה שלכם לצורך קישור.

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

התכונה 'החלפת אפליקציות' נתמכת ב-Android וב-iOS.

איך זה עובד:

אפליקציית Google בודקת אם האפליקציה שלכם מותקנת במכשיר של המשתמש:

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

איור 2. קישור חשבון בטלפון של משתמש באמצעות App Flip

קישור יעיל מבוסס-OAuth ('יעיל')

‫Sign in with Google מבוסס-OAuth לקישור יעיל מוסיף את האפשרות 'כניסה באמצעות חשבון Google' לקישור מבוסס-OAuth, ומאפשר למשתמשים להשלים את תהליך הקישור בלי לצאת מהממשק של Google. כך מצמצמים את החיכוך ומקטינים את שיעור הנטישה. קישור יעיל מבוסס-OAuth מציע את חוויית המשתמש הטובה ביותר עם כניסה חלקה, יצירת חשבון וקישור חשבון על ידי שילוב של כניסה באמצעות חשבון Google עם קישור OAuth. השירות שלכם צריך לתמוך בנקודות קצה של הרשאה ותחלופת אסימונים שתואמות ל-OAuth 2.0. בנוסף, נקודת הקצה להחלפת טוקנים צריכה לתמוך בהצהרות JSON Web Token‏ (JWT) וליישם את הכוונות check,‏ create ו-get.

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

איך זה עובד:

‫Google מאמתת את חשבון המשתמש ומעבירה את המידע הזה אליכם:

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

איור 3. קישור חשבונות בטלפון של משתמש באמצעות קישור פשוט

באיזה תהליך כדאי להשתמש?

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

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

עבודה עם טוקנים

קישור של חשבון Google מבוסס על תקן OAuth 2.0 המקובל בתחום.

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

令牌类型

OAuth 2.0 使用称为令牌的字符串在用户代理、客户端应用和 OAuth 2.0 服务器之间进行通信。

在帐号关联期间，可以使用三种类型的 OAuth 2.0 令牌：

• 授权代码 。一种短期令牌，可以交换为访问令牌和刷新令牌。出于安全考虑，Google 会调用您的授权端点来获取一次性或短期代码。

• 访问令牌 。一种令牌，用于授予持有者对资源的访问权限。为了限制因丢失此令牌而可能造成的风险，此令牌的生命周期有限，通常会在大约一小时后过期。

• 刷新令牌 。一种长期令牌，当访问令牌过期时，可以交换为新的访问令牌。当您的服务与 Google 集成时，此令牌仅由 Google 存储和使用。Google 会调用您的令牌交换端点，以将刷新令牌交换为访问令牌，而访问令牌又用于访问用户数据。

令牌处理

在集群环境和客户端-服务器交换中，竞争条件可能会导致在使用令牌时出现复杂的时序和错误处理场景。 例如：

• 您收到有关新访问令牌的请求，并签发了新的访问令牌。同时，您收到有关使用之前未过期的访问令牌访问您服务资源的请求。
• Google 尚未收到（或永远不会收到）您的刷新令牌回复。与此同时，之前有效的刷新令牌在 Google 的请求中使用。

由于集群中运行的异步服务、网络行为或其他方式，请求和回复可能会以任何顺序到达，或者根本不会到达。

无法保证您的令牌处理系统和 Google 的令牌处理系统之间以及内部的即时且完全一致的共享状态。在短时间内，多个有效且未过期的令牌可能会在系统内或跨系统共存。为了最大限度地减少对用户的负面影响，我们建议您执行以下操作：

• 接受未过期的访问令牌，即使在签发新令牌后也是如此。
• 使用 刷新令牌轮替的替代方案。
• 支持多个同时有效的访问令牌和刷新令牌。出于安全考虑，您应限制令牌数量和令牌生命周期。

维护和服务中断处理

在维护期间或计划外中断期间，Google 可能无法调用您的授权端点或令牌交换端点来获取访问令牌和刷新令牌。

您的端点应返回 503 错误代码和空正文。在这种情况下，Google 会在有限的时间内重试失败的令牌交换请求。前提是 Google 稍后能够获取刷新令牌和访问令牌，否则用户将无法看到失败的请求。

**警告** ：请勿在维护或中断期间返回 400 错误代码和 {"error": "invalid_grant"} 正文 。这样做会删除之前签发的令牌，并要求用户重新关联其帐号。

如果用户发起的访问令牌请求失败，则会导致显示错误。如果使用隐式 OAuth 2.0 流程，则用户需要重试关联失败。

建议

有很多解决方案可以最大限度地减少维护影响。您可以考虑以下选项：

• 维护现有服务，并将有限数量的请求路由到新更新的服务。仅在确认预期功能后才迁移所有请求。

• 减少维护期间的令牌请求数量：

  • 将维护期限制为小于访问令牌生命周期。

  • 暂时延长访问令牌生命周期：

    1. 将令牌生命周期延长到大于维护期。
    2. 等待访问令牌生命周期的两倍时长，以便用户将短期令牌交换为长期令牌。
    3. 进入维护期。
    4. 使用 503 错误代码和空正文响应令牌请求。
    5. 退出维护期。
    6. 将令牌生命周期缩短回正常水平。

קישור מתמשך

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

כדי להטמיע קישור מתמשך, משתמשים בגישה של 'חלון נע': מאריכים את תוקף טוקן הרענון הקיים במקום להחליף אותו (בהתאם לסעיף 6 ב-RFC 6749). כך נמנעים מצבי מירוץ וביטול קישור לא מכוון שיכולים להתרחש אם מונפק טוקן רענון חדש אבל Google לא מקבלת או מאחסנת אותו.

הרשמה באמצעות Google

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