קישור חשבון 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 控制台。
2. 点击 Create project 。
3. 输入名称或接受生成的建议。
4. 确认或修改任何剩余字段。
5. 点击创建 。

如需查看项目 ID，请执行以下操作：

1. 前往 Google API 控制台。
2. 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

配置 OAuth 权限请求页面

Google 账号关联过程包含一个权限请求页面，该页面会告知用户请求访问其数据的应用、应用请求的数据类型以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

1. 打开 Google API 控制台的 OAuth 权限请求页面 页面。
2. 如果系统提示您选择项目，请选择您刚刚创建的项目。

3. 在“OAuth 权限请求页面”上，填写表单，然后点击“保存”按钮。

   应用名称 ：向用户征求同意的应用的名称。该名称应准确反映您的应用，并且与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求页面上。

   应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

   支持邮箱 ：用户用于针对其同意问题与您联系的邮箱。

   Google API 的范围 ：范围允许您的应用访问用户的私有 Google 数据。对于 Google 账号关联用例，默认范围（邮箱、个人资料、openid）就足够了，您无需添加任何敏感范围。通常，最佳做法是在需要访问权限时逐步请求范围，而不是提前请求。了解详情。

   已获授权的网域 ：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。

   应用首页链接 ：应用的首页。必须托管在已获授权的网域上。

   应用隐私权政策链接 ：显示在 Google 账号关联权限请求页面上。必须托管在已获授权的网域上。

   应用服务条款链接（可选） ：必须托管在已获授权的网域上。

   

   图 1. 虚构应用 Tunery 的 Google 账号关联权限请求页面

4. 查看“验证状态”，如果您的应用需要验证，请点击“提交以进行验证”按钮，提交应用以进行验证。如需了解详情，请参阅 OAuth 验证要求。

הטמעת שרת OAuth

n

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

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

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

קישור של חשבון Google: תהליך מרומז של OAuth

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

איור 1. רצף האירועים בזרם הענקת גישה משתמע של OAuth 2.0 לקישור של חשבון Google.

תפקידים ותחומי אחריות

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

המשתמש / הרכיב	תפקיד ב-GAL	תחומי אחריות
אפליקציית Google / שרת	לקוח OAuth	מתחיל את התהליך, מקבל את אסימון הגישה באמצעות הפניה אוטומטית בדפדפן, ומאחסן אותו בצורה מאובטחת כדי לגשת לממשקי ה-API של השירות.
נקודת הקצה להרשאה	שרת הרשאות	השירות מאמת את המשתמשים, מקבל את ההסכמה שלהם ומנפיק אסימוני גישה לטווח ארוך ישירות ל-Google.
‫URI של הפניה לכתובת אחרת ב-Google	נקודת קצה של קריאה חוזרת (callback)	מקבל את ההפניה האוטומטית של המשתמש משירות ההרשאה עם הערכים access_token ו-state בקטע של כתובת ה-URL.

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

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

טיפול בבקשות הרשאה

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

פרמטרים של נקודת קצה להרשאה
client_id	מזהה הלקוח שהקציתם ל-Google.
redirect_uri	כתובת ה-URL שאליה שולחים את התשובה לבקשה הזו.
state	ערך לניהול חשבונות שמועבר בחזרה ל-Google ללא שינוי ב-URI של ההפניה.
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.
   • בודקים שכתובת ה-URL שצוינה על ידי הפרמטר 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 שמפנה את הדפדפן של המשתמש לכתובת ה-URL שצוינה בפרמטר redirect_uri. צריך לכלול את כל הפרמטרים הבאים בפרגמנט URL:

   • ‫access_token: אסימון הגישה שיצרתם
   • token_type: המחרוזת bearer
   • ‫state: ערך הסטטוס שלא השתנה מהבקשה המקורית

   דוגמה לכתובת ה-URL שמתקבלת:

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

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

טיפול בבקשות למידע על משתמשים

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

• כניסה לחשבון המקושר באמצעות Google One Tap.
• מינוי פשוט וקל ב-AndroidTV.

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

כותרות של בקשות של נקודות קצה של userinfo
Authorization header	אסימון הגישה מסוג נושא.

לדוגמה, אם נקודת הקצה של Userinfo זמינה https://myservice.example.com/userinfo, בקשה עשויה להיראות כך:

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

כדי שנקודת הקצה של userinfo תטפל בבקשות, מבצעים את השלבים הבאים:

1. מחלצים את אסימון הגישה מהכותרת Authorization ומחזירים מידע עבור המשתמש שמשויך לאסימון הגישה.
2. אם אסימון הגישה לא חוקי, צריך להחזיר שגיאה מסוג HTTP 401 מאושר עם שימוש בכותרת התגובה WWW-Authenticate. דוגמה לתגובה עם שגיאה של userinfo:

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

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

3. אם אסימון הגישה תקין, מוחזר ותגובת HTTP 200 עם אובייקט ה-JSON הבא בגוף ה-HTTPS תגובה:

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

   אם נקודת הקצה (endpoint) של userinfo מחזירה תגובה מוצלחת מסוג HTTP 200, האסימון שאוחזר וההצהרות על זכויות יוצרים יירשמו בחשבון Google של המשתמש.

   תגובה של נקודת הקצה של userinfo
   sub	מזהה ייחודי שמזהה את המשתמש במערכת שלכם.
   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. מוודאים שמופנים לפלטפורמה שלכם.