דף זה תורגם על ידי Cloud Translation API.

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

סקירה כללית

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

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

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

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

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

דרישות לקישור פשוט

מטמיעים את התהליך של קישור Web OAuth בסיסי. השירות חייב לתמוך בנקודות קצה (endpoint) מסוג הרשאה והחלפת אסימונים התואמות ל-OAuth 2.0.
נקודת הקצה החלפת אסימונים חייבת לתמוך בהצהרות אסימון אינטרנט של JSON (JWT) וליישם את הכוונות check, create ו-get.

רושמים את מספר הלקוח שלכם ב-Google API.

הטמעה של שרת ה-OAuth

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

האם למשתמש יש חשבון במערכת האימות שלך? (המשתמש מחליט: 'כן' או 'לא')
1. כן : האם המשתמש משתמש בכתובת האימייל המשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה? (המשתמש מחליט: 'כן' או 'לא')
  1. כן : האם למשתמש יש חשבון תואם במערכת האימות שלך? (check intent יתקשר כדי לאשר)
    1. כן: התקבלה שיחה אל get intent והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה.
    2. לא : ליצור חשבון חדש? (המשתמש מחליט: 'כן' או 'לא')
      1. כן : התקבלה שיחה מ-create intent, והחשבון יקושר אם כוונת הרכישה תשוחזר.
      2. לא : תהליך ה-OAuth באינטרנט מופעל, המשתמש מופנה לדפדפן שלו, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
  2. לא : זרימת ה-OAuth מופעלת, המשתמש מופנה לדפדפן, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
2. לא : האם למשתמש יש חשבון תואם במערכת האימות שלך? (check intent יתקשר כדי לאשר)
  1. כן : התקבלה שיחה אל get intent והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה.
  2. לא : בוצעה קריאה ל-create intent והחשבון מקושר אם כוונת הרכישה חוזרת בהצלחה.

检查现有用户帐号（检查 intent）

在用户同意访问其 Google 个人资料后，Google 会发送一个请求，其中包含 Google 用户身份的签名断言。该断言包含用户的 Google 帐号 ID、姓名和电子邮件地址。为您的项目配置的令牌交换端点会处理该请求。

如果您的身份验证系统中已存在相应的 Google 帐号，则您的令牌交换端点会返回 account_found=true。如果 Google 帐号与现有用户不匹配，那么您的令牌交换端点会返回 account_found=false 的 HTTP 404 Not Found 错误。

请求的格式如下：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
`intent`	对于这些请求，此参数的值为 `check`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	一个 JSON Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

为了响应 check intent 请求，您的令牌交换端点必须执行以下步骤：

验证并解码 JWT 断言。
检查您的身份验证系统中是否已存在该 Google 帐号。

אימות ופענוח של טענת הנכוֹנוּת (assertion) של JWT

אפשר לאמת ולפענח את טענת הנכוֹנוּת (assertion) של JWT באמצעות ספריית פענוח קוד JWT לשפה שלכם. כדאי להשתמש המפתחות הציבוריים של Google זמינים ב JWK או של PEM לצורך אימות לחתימה של האסימון.

אחרי הפענוח, טענת הנכוֹנוּת (assertion) של ה-JWT תיראה כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

בנוסף לאימות החתימה של האסימון, צריך לוודא מנפיק (השדה iss) הוא https://accounts.google.com, שהקהל (השדה aud) הוא מזהה הלקוח שהוקצה לך, ושתוקף האסימון לא פג (השדה exp).

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

מקרים שבהם Google היא מהימן:

ל-email יש סיומת @gmail.com. זהו חשבון Gmail.
email_verified מוגדר כ-True ו-hd מוגדר. זהו חשבון G Suite.

משתמשים יכולים להירשם לחשבונות Google בלי להשתמש ב-Gmail או ב-G Suite. מתי email לא מכיל סיומת @gmail.com ו-hd חסר Google מומלץ לאמת סיסמה או סיסמה או שיטות אחרות לאימות למשתמש. email_verified יכול להיות גם נכון כי Google אימתה בהתחלה את משתמש כשחשבון Google נוצר, אבל בעלות על הצד השלישי ייתכן שחשבון האימייל השתנה מאז.

检查您的身份验证系统中是否已存在该 Google 帐号

检查是否满足以下任一条件：

Google 帐号 ID 可在用户的数据库中找到，可在断言的 sub 字段找到。
断言中的电子邮件地址与您的用户数据库中的用户匹配。

如果其中任一条件为 true，则表示用户已注册。在这种情况下，系统将返回如下所示的响应：

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

如果断言中指定的 Google 帐号 ID 和电子邮件地址都与用户数据库中的用户不匹配，则表示用户尚未注册。在这种情况下，您的令牌交换端点需要使用包含 "account_found": "false" 的 HTTP 404 错误进行响应，如以下示例所示：

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

处理自动链接（获取 intent）

如果您的身份验证系统中已存在相应的 Google 帐号，则您的令牌交换端点会返回用户的令牌。如果 Google 帐号与现有用户不匹配，您的令牌交换端点会返回 linking_error 错误和可选的 login_hint。

请求的格式如下：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
`intent`	对于这些请求，此参数的值为 `get`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	一个 JSON Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
`scope`	可选：您已将 Google 配置为向用户请求的任何范围。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

为了响应 get intent 请求，您的令牌交换端点必须执行以下步骤：

验证并解码 JWT 断言。
检查您的身份验证系统中是否已存在该 Google 帐号。

אימות ופענוח של טענת הנכוֹנוּת (assertion) של JWT

אחרי הפענוח, טענת הנכוֹנוּת (assertion) של ה-JWT תיראה כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

מקרים שבהם Google היא מהימן:

ל-email יש סיומת @gmail.com. זהו חשבון Gmail.
email_verified מוגדר כ-True ו-hd מוגדר. זהו חשבון G Suite.

检查您的身份验证系统中是否已存在该 Google 帐号

检查是否满足以下任一条件：

Google 帐号 ID 可在用户的数据库中找到，可在断言的 sub 字段找到。
断言中的电子邮件地址与您的用户数据库中的用户匹配。

如果找到了用户的帐号，请发出访问令牌，并在 HTTPS 响应的正文中以 JSON 对象形式返回值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

在某些情况下，基于 ID 令牌的帐号关联可能会为用户失败。如果出现任何此类情况，您的令牌交换端点都需要使用返回 error=linking_error 的 HTTP 401 错误进行响应，如以下示例所示：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Google 收到包含 linking_error 的 401 错误响应后，会将用户作为授权参数 login_hint 发送到您的授权端点。用户在浏览器中使用 OAuth 关联流程完成帐号关联。

通过 Google 登录功能创建帐号（创建 intent）

当用户需要在您的服务上创建帐号时，Google 会向您的令牌交换端点发出请求，并指定 intent=create。

请求的格式如下：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
`intent`	对于这些请求，此参数的值为 `create`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	一个 JSON Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

assertion 参数中的 JWT 包含用户的 Google 帐号 ID、名称和电子邮件地址，您可以使用这些信息在服务中创建新帐号。

为了响应 create intent 请求，您的令牌交换端点必须执行以下步骤：

验证并解码 JWT 断言。
验证用户信息并创建新帐号。

אימות ופענוח של טענת הנכוֹנוּת (assertion) של JWT

אחרי הפענוח, טענת הנכוֹנוּת (assertion) של ה-JWT תיראה כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

מקרים שבהם Google היא מהימן:

ל-email יש סיומת @gmail.com. זהו חשבון Gmail.
email_verified מוגדר כ-True ו-hd מוגדר. זהו חשבון G Suite.

验证用户信息并创建新帐号

检查是否满足以下任一条件：

Google 帐号 ID 可在用户的数据库中找到，可在断言的 sub 字段找到。
断言中的电子邮件地址与您的用户数据库中的用户匹配。

如果任一条件为 true，请提示用户将其现有帐号与其 Google 帐号相关联。为此，请对请求进行响应，并提供指定 error=linking_error 并将用户的电子邮件地址作为 login_hint 的 HTTP 401 错误。以下是一个示例响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

如果两个条件都不满足，请使用 JWT 中提供的信息创建新的用户帐号。新帐号通常不会设置密码。建议您将 Google 登录功能添加到其他平台，以便用户能够在应用界面使用 Google 帐号登录。或者，您也可以通过电子邮件向用户发送一个启动密码恢复流程的链接，以便用户设置密码以在其他平台上登录。

创建完成后，发出访问令牌，并在 HTTPS 响应的正文中以 JSON 对象形式返回值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

קבלת מספר הלקוח של Google API

תצטרכו לספק את מספר הלקוח שלכם ב-Google API בתהליך ההרשמה לקישור.

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

פותחים את הדף פרטי הכניסה במסוף Google API.
יוצרים או בוחרים פרויקט ב-Google APIs.

אם לפרויקט שלך אין Client-ID לסוג אפליקציית האינטרנט, לוחצים על יצירת פרטי כניסה ו-gt; מזהה לקוח ב-OAuth כדי ליצור מזהה. הקפידו לכלול את הדומיין של האתר שלכם בתיבה מקורות JavaScript מורשים. כשמבצעים בדיקות או פיתוח מקומיים, צריך להוסיף את http://localhost וגם את http://localhost:<port_number> לשדה מקורות JavaScript מורשים.

מפתח חשוב: עליך להוסיף את http://localhost וגם http://localhost:<port_number> לשדה מקורות JavaScript מורשים לבדיקות או פיתוח מקומיים.
הערה: מספר לקוח נראה כמו בדוגמה הבאה:
```
1234567890-abc123def456.apps.googleusercontent.com
```

אימות ההטמעה

אתה יכול לאמת את הביצוע שלך באמצעות מגרש 2.0 OAuth הכלי.

בצע את הפעולות הבאות בכלי:

לחץ תצורת כדי לפתוח את חלון תצורת 2.0 OAuth.
בתחום זרימת OAuth, בחר בצד הלקוח.
בתחום נקודות קצה OAuth, בחר Custom.
ציין את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקצית ל- Google בשדות המתאימים.
במקטע שלב 1, לא יבחר אף היקפי Google. במקום זאת, השאר שדה זה ריק או הקלד טווח תקף עבור השרת שלך (או מחרוזת שרירותית אם אינך משתמש בהיקפי OAuth). כשתסיים, לחץ על הרשה APIs.
בסעיפים שלב 2 ושלב 3, לעבור את זרימת 2.0 OAuth ולוודא כי כל צעד עובד כמתוכנן.

אתה יכול לאמת את הביצוע שלך באמצעות קישור הדגמת חשבון Google הכלי.

בצע את הפעולות הבאות בכלי:

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