קישור חשבון Google באמצעות OAuth

החשבונות מקושרים באמצעות תהליכי הרשאה ומרומזים של OAuth 2.0, שהם תהליכים מקובלים בתחום.

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

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

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

בתהליך קוד ההרשאה, נדרשות שתי נקודות קצה:

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

• נקודת הקצה (endpoint) של החלפת אסימונים, שאחראית על שני סוגים של החלפות:

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

בחירת תהליך OAuth 2.0

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

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

זרם הענקת גישה משתמע קוד הרשאה

הנחיות עיצוב

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

איור 1. המשתמשים נכנסים לחשבון Google ומסכי הסכמה מוצגים להם.

דרישות

1. חשוב להבהיר למשתמש שהחשבון שלו יקושר ל-Google, ולא למוצר ספציפי של Google כמו Google Home או Google Assistant.

המלצות

מה אתם יכולים לעשות?

1. הצגת מדיניות הפרטיות של Google במסך ההסכמה, צריך לכלול קישור למדיניות הפרטיות של Google.

2. הנתונים שישותפו. השתמשו בשפה ברורה ותמציתית כדי להסביר למשתמשים אילו נתונים שלהם נדרשים ל-Google ולמה.

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

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

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

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

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

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

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

איור 2. הנחיות עיצוב למסכי כניסה של משתמשים ל-Google ולמסכי הסכמה

יצירת הפרויקט

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

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

1. עוברים אל Google API Console.
2. לוחצים על יצירת פרויקט.
3. מזינים שם או מאשרים את ההצעה שנוצרה.
4. מאשרים או עורכים את השדות שנותרו.
5. לוחצים על יצירה.

כדי לראות את מזהה הפרויקט:

1. עוברים אל Google API Console.
2. מחפשים את הפרויקט בטבלה בדף הנחיתה. מזהה הפרויקט מופיע בעמודה ID.

הגדרה של מסך ההסכמה ל-OAuth

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

1. פותחים את הדף מסך ההסכמה ל-OAuth ב-Google APIs Console.
2. אם מתבקשים, בוחרים את הפרויקט שיצרתם.

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

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

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

   כתובת אימייל לתמיכה: כתובת אימייל שאליה משתמשים יכולים לפנות אם יש להם שאלות לגבי ההסכמה שלהם.

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

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

   קישור לדף הבית של האפליקציה: דף הבית של האפליקציה. הן חייבות להתארח בדומיין מורשה.

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

   קישור לתנאים ולהגבלות של האפליקציה (אופציונלי): הקישור צריך להיות מאוחסן בדומיין מורשה.

   

   איור 1. מסך הסכמה לקישור של חשבון Google לאפליקציה פיקטיבית, Tunery

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

הטמעת שרת OAuth

n

危险：MCP、UCP 和代理驱动的流程不支持隐式流程。出于安全考虑，一般不建议所有新集成使用此方法。请改用授权代码流程。

为了支持 OAuth 2.0 隐式流程，您的服务通过 HTTPS 提供授权端点。此端点负责身份验证和征得用户同意以获取数据访问权限。授权端点会向尚未登录的用户显示登录界面，并记录用户对所请求访问权限的同意情况。

当 Google 应用需要调用您服务的某个已获授权的 API 时，Google 会使用此端点来征得用户同意，以便代表用户调用这些 API。

Google 账号关联：OAuth 隐式授权流程

以下序列图详细说明了用户、Google 和您服务的端点之间的互动。

图 1. Google 账号关联的 OAuth 2.0 隐式流程中的事件序列。

角色和职责

下表定义了 Google 账号关联 (GAL) OAuth 隐式流程中各个参与者的角色和职责。请注意，在 GAL 中，Google 充当 OAuth 客户端，而您的服务充当身份/服务提供方。

执行者 / 组件	GAL 角色	职责
Google 应用 / 服务器	OAuth 客户端	启动流程，使用浏览器重定向接收访问令牌，并安全地存储该令牌以访问服务的 API。
您的授权端点	授权服务器	对用户进行身份验证，征得用户同意，并直接向 Google 签发长期有效的访问令牌。
Google 重定向 URI	回调端点	从授权服务接收用户重定向，其中包含网址 fragment 中的 access_token 和 state 值。

由 Google 发起的典型 OAuth 2.0 隐式流程会话具有以下流程：

1. Google 会在用户的浏览器中打开您的授权端点。用户登录（如果尚未登录），并授予 Google 权限以通过您的 API 访问其数据（如果尚未授予权限）。
2. 您的服务会创建访问令牌并将其返回给 Google。为此，请将用户的浏览器重定向回 Google，并将访问令牌附加到请求中。
3. Google 会调用您服务的 API，并在每个请求中附加访问令牌。您的服务会验证该访问令牌是否授予了 Google 访问相应 API 的授权，然后完成 API 调用。

处理授权请求

当 Google 应用需要使用 OAuth 2.0 隐式流程执行账号关联时，Google 会将用户发送到您的授权端点，并发送包含以下参数的请求：

授权端点参数
client_id	您分配给 Google 的客户 ID。
redirect_uri	您将对此请求的响应发送到的网址。
state	一种簿记值，在重定向 URI 中原封不动地传递回 Google。
response_type	要在响应中返回的值的类型。对于 OAuth 2.0 隐式流程，响应类型始终为 token。
user_locale	Google 账号语言设置（采用 RFC5646 格式），用于以用户的首选语言本地化您的内容。

例如，如果您的授权端点位于 https://myservice.example.com/auth，则请求可能如下所示：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

如需让授权端点处理登录请求，请执行以下步骤：

1. 验证 client_id 和 redirect_uri 值，以防止向意外或配置错误的客户端应用授予访问权限：

   • 确认 client_id 与您分配给 Google 的客户端 ID 相一致。
   • 确认 redirect_uri 参数指定的网址具有以下格式：

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

2. 检查用户是否已登录您的服务。如果用户未登录，请完成服务的登录或注册流程。

3. 生成供 Google 用于访问您的 API 的访问令牌。访问令牌可以是任何字符串值，但必须唯一表示用户和令牌所针对的客户端，并且不得是可猜测的值。

4. 发送 HTTP 响应，将用户的浏览器重定向到 redirect_uri 参数指定的网址。在网址片段中包含以下所有参数：

   • access_token：您刚刚生成的访问令牌
   • token_type：字符串 bearer
   • state：原始请求中的未修改状态值

   以下是生成的网址示例：

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google 的 OAuth 2.0 重定向处理程序会接收访问令牌，并确认 state 值未发生变化。在 Google 为您的服务获取访问令牌后，Google 会将该令牌附加到后续对您的服务 API 的调用中。

处理 userinfo 请求

userinfo 端点是受 OAuth 2.0 保护的资源，会返回关联用户的声明。实现和托管 userinfo 端点是可选的，但以下用例除外：

• 使用 Google One Tap 登录关联的账号。
• Android TV 提供顺畅的订阅体验。

从您的令牌端点成功检索到访问令牌后，Google 会向您的 userinfo 端点发送请求，以检索关联用户的基本个人资料信息。

userinfo 端点请求标头
Authorization header	Bearer 类型的访问令牌。

例如，如果您的 userinfo 端点可通过 https://myservice.example.com/userinfo 时，请求可能如下所示：

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

为了让 userinfo 端点能够处理请求，请执行以下步骤：

1. 从 Authorization 标头中提取访问令牌，并返回与访问令牌相关联的用户的信息。
2. 如果访问令牌无效，则使用 WWW-Authenticate 响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例：

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应，该错误将无法恢复，检索到的令牌将被舍弃，并且用户必须重新开始关联流程。

3. 如果访问令牌有效，则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回答：

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   如果您的 userinfo 端点返回 HTTP 200 成功响应，则系统会针对用户的 Google 账号注册检索到的令牌和声明。

   userinfo 端点响应
   sub	系统中用于识别用户的唯一 ID。
   email	用户的电子邮件地址。
   given_name	可选：用户的名字。
   family_name	可选：用户的姓氏。
   name	可选：用户的全名。
   picture	可选：用户的个人资料照片。

אימות ההטמעה

כדי לאמת את ההטמעה, אפשר להשתמש בכלי OAuth 2.0 Playground.

בכלי, מבצעים את השלבים הבאים:

1. לוחצים על Configuration (הגדרה) כדי לפתוח את חלון ההגדרה של OAuth 2.0.
2. בשדה OAuth flow (תהליך OAuth), בוחרים באפשרות Client-side (בצד הלקוח).
3. בשדה OAuth Endpoints (נקודות קצה של OAuth), בוחרים באפשרות Custom (מותאם אישית).
4. בשדות המתאימים, מציינים את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקציתם ל-Google.
5. בקטע Step 1, לא בוחרים אף היקף של Google. במקום זאת, משאירים את השדה הזה ריק או מקלידים היקף הרשאות שתקף לשרת (או מחרוזת שרירותית אם לא משתמשים בהיקפי הרשאות OAuth). בסיום, לוחצים על הרשאת ממשקי API.
6. בקטעים שלב 2 ושלב 3, עוברים על תהליך ההרשאה באמצעות OAuth 2.0 ומוודאים שכל שלב פועל כמו שצריך.

כדי לאמת את ההטמעה, אפשר להשתמש בכלי Google Account Linking Demo.

בכלי, מבצעים את השלבים הבאים:

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