การลิงก์กับ OAuth และ Google Sign-In ที่มีประสิทธิภาพยิ่งขึ้น

ภาพรวม

การลิงก์ Google Sign-In ที่ใช้ OAuth ได้รับการปรับปรุงให้มีประสิทธิภาพมากขึ้นจะเพิ่ม Google Sign-In ไว้เหนือการลิงก์ OAuth ซึ่งจะช่วยให้ผู้ใช้ Google ลิงก์บัญชีได้อย่างราบรื่น ทั้งยังเปิดใช้การสร้างบัญชี ซึ่งช่วยให้ผู้ใช้สร้างบัญชีใหม่ในบริการของคุณโดยใช้บัญชี Google ได้

หากต้องการลิงก์บัญชีด้วย OAuth และ Google Sign-In ให้ทําตามขั้นตอนทั่วไปต่อไปนี้

  1. ก่อนอื่น ให้ขอให้ผู้ใช้ให้ความยินยอมในการเข้าถึงโปรไฟล์ Google
  2. ใช้ข้อมูลในโปรไฟล์เพื่อตรวจสอบว่าบัญชีผู้ใช้มีอยู่หรือไม่
  3. สำหรับผู้ใช้เดิม ให้ลิงก์บัญชี
  4. หากไม่พบผู้ใช้ Google ที่ตรงกันในระบบการตรวจสอบสิทธิ์ ให้ตรวจสอบโทเค็นระบุตัวตนที่ได้รับจาก Google จากนั้นคุณจะสร้างผู้ใช้โดยอิงตามข้อมูลโปรไฟล์ที่อยู่ในโทเค็นระบุตัวตนได้
รูปภาพนี้แสดงขั้นตอนที่ผู้ใช้ต้องดำเนินการเพื่อลิงก์บัญชี Google โดยใช้ขั้นตอนการลิงก์ที่มีประสิทธิภาพมากขึ้น ภาพหน้าจอแรกแสดงวิธีที่ผู้ใช้เลือกแอปของคุณเพื่อลิงก์ ภาพหน้าจอที่ 2 ช่วยให้ผู้ใช้ยืนยันได้ว่าตนมีบัญชีในบริการของคุณอยู่แล้วหรือไม่ ภาพหน้าจอที่ 3 แสดงให้ผู้ใช้เลือกบัญชี Google ที่ต้องการลิงก์ ภาพหน้าจอที่ 4 แสดงการยืนยันการลิงก์บัญชี Google กับแอปของคุณ ภาพหน้าจอที่ 5 แสดงบัญชีผู้ใช้ที่ลิงก์เรียบร้อยแล้วในแอป Google

รูปที่ 1 การลิงก์บัญชีในโทรศัพท์ของผู้ใช้ด้วยการลิงก์แบบมีประสิทธิภาพ

ข้อกำหนดสำหรับการลิงก์แบบมีประสิทธิภาพ

  • ใช้โฟลว์การลิงก์ OAuth พื้นฐานบนเว็บ บริการของคุณต้องรองรับปลายทางการให้สิทธิ์และการเปลี่ยนโทเค็นที่เป็นไปตามข้อกำหนด OAuth 2.0
  • ปลายทางการแลกเปลี่ยนโทเค็นต้องรองรับการยืนยัน JSON Web Token (JWT) และใช้ Intent check, create และ get

ใช้เซิร์ฟเวอร์ OAuth

ปลายทางการแลกเปลี่ยนโทเค็นต้องรองรับ Intent check, create, get ด้านล่างแสดงขั้นตอนที่เสร็จสมบูรณ์ผ่านขั้นตอนการลิงก์บัญชี และระบุเวลาที่เรียกใช้ Intent ต่างๆ

  1. ผู้ใช้มีบัญชีในระบบการตรวจสอบสิทธิ์หรือไม่ (ผู้ใช้ตัดสินใจโดยเลือก "ใช่" หรือ "ไม่")
    1. ใช่ : ผู้ใช้ใช้อีเมลที่เชื่อมโยงกับบัญชี Google เพื่อลงชื่อเข้าใช้แพลตฟอร์มของคุณหรือไม่ (ผู้ใช้ตัดสินใจโดยเลือก "ใช่" หรือ "ไม่")
      1. ใช่ : ผู้ใช้มีบัญชีที่ตรงกันในระบบการตรวจสอบสิทธิ์หรือไม่ (โทรหา check intent เพื่อยืนยัน)
        1. ใช่ : มีการเรียกใช้ get intent และระบบจะลิงก์บัญชีหาก get intent แสดงผลสําเร็จ
        2. ไม่ : สร้างบัญชีใหม่ (ผู้ใช้ตัดสินใจโดยเลือก "ใช่" หรือ "ไม่")
          1. ใช่ : มีการเรียกใช้ create intent และลิงก์บัญชีหากสร้าง Intent สำเร็จ
          2. ไม่ : ระบบจะเรียกใช้ขั้นตอนการลงชื่อเข้าใช้ด้วย OAuth บนเว็บ ระบบจะนําผู้ใช้ไปยังเบราว์เซอร์ และผู้ใช้จะมีตัวเลือกให้ลิงก์กับอีเมลอื่น
      2. ไม่ : ระบบจะเรียกใช้ขั้นตอนการลงชื่อเข้าใช้ด้วย OAuth บนเว็บ ระบบจะนําผู้ใช้ไปยังเบราว์เซอร์ และผู้ใช้จะมีตัวเลือกให้ลิงก์กับอีเมลอื่น
    2. ไม่ : ผู้ใช้มีบัญชีที่ตรงกันในระบบการตรวจสอบสิทธิ์หรือไม่ (โทรหา check intent เพื่อยืนยัน)
      1. ใช่ : มีการเรียกใช้ get intent และระบบจะลิงก์บัญชีหาก get intent แสดงผลสําเร็จ
      2. ไม่ : มีการเรียกใช้ create intent และระบบจะลิงก์บัญชีหาก createIntent แสดงผลสำเร็จ

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

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

如果您的身份验证中已有相应的 Google 账号 系统时，您的令牌交换端点会返回 account_found=true。如果 Google 账号与现有用户不匹配，您的令牌交换端点 返回“HTTP 404 Not Found”错误以及 account_found=false。

请求的格式如下：

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 账号。
验证和解码 JWT 断言

您可以使用 适用于您所用语言的 JWT 解码库。使用 Google 的公钥，在 JWK 或 PEM 格式，用于验证 令牌的签名。

解码后，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 字段）是分配给您的客户端 ID，并且令牌未过期 （exp 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

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

请检查以下任一条件是否成立：

  • Google 账号 ID（可在断言的 sub 字段中找到）位于您的用户中 数据库。
  • 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，则表明用户已注册。在这种情况下 返回如下所示的响应：

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

{
  "account_found":"true",
}

如果 Google 账号 ID 和 断言与您的数据库中的用户匹配，该用户尚未注册。在 在这种情况下，您的令牌交换端点需要返回 HTTP 404 错误 指定 "account_found": "false"，如以下示例所示：

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

{
  "account_found":"false",
}

处理自动链接（获取 intent）

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

如果您的身份验证中已有相应的 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 账号。
验证和解码 JWT 断言

您可以使用 适用于您所用语言的 JWT 解码库。使用 Google 的公钥，在 JWK 或 PEM 格式，用于验证 令牌的签名。

解码后，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 字段）是分配给您的客户端 ID，并且令牌未过期 （exp 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

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

请检查以下任一条件是否成立：

  • Google 账号 ID（可在断言的 sub 字段中找到）位于您的用户中 数据库。
  • 断言中的电子邮件地址与用户数据库中的用户匹配。

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

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

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

在某些情况下，基于 ID 令牌的账号关联可能会失败。如果 因为任何原因，您的令牌交换端点都需要以 HTTP 响应 指定 error=linking_error 的 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。 姓名和电子邮件地址，可用于在 Gmail 中创建新账号 服务。

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

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

您可以使用 适用于您所用语言的 JWT 解码库。使用 Google 的公钥，在 JWK 或 PEM 格式，用于验证 令牌的签名。

解码后，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 字段）是分配给您的客户端 ID，并且令牌未过期 （exp 字段）。

使用 email、email_verified 和 hd 字段，您可以确定 Google 负责托管电子邮件地址，并对其具有权威性。如果 Google 权威性 - 用户当前被认定为合法账号所有者 您可以跳过密码或其他验证方法。否则，这些方法 可用于在关联之前验证账号。

Google 具有权威性的情形：

  • email 的后缀为 @gmail.com，这是一个 Gmail 账号。
  • email_verified 为 true 且 hd 已设置，这是 G Suite 账号。

用户无需使用 Gmail 或 G Suite 即可注册 Google 账号。时间 email 不包含 @gmail.com 后缀，且 hd 不存在 Google 不 建议使用权威凭据和密码或其他验证方法进行验证 用户。email_verified 可能为 true，因为 Google 最初验证了 创建 Google 账号后，该用户会获得第三方的所有权， 后，电子邮件账号可能已更改。

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

请检查以下任一条件是否成立：

  • Google 账号 ID（可在断言的 sub 字段中找到）位于您的用户中 数据库。
  • 断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足上述任一条件，请提示用户关联其现有账号 与其 Google 账号关联。为此，请使用 HTTP 401 错误响应请求 该参数指定 error=linking_error 并将用户的电子邮件地址作为 login_hint。以下是示例响应：

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 登录功能添加到其他平台，以便用户 使用 Google 账号登录。或者 可以通过电子邮件向用户发送链接，启动密码恢复流程，以允许 用户设置密码，以便在其他平台上登录。

创建完成后，发出一个访问令牌 和刷新令牌 并在 HTTPS 响应的正文，如以下示例所示： 

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

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

รับรหัสไคลเอ็นต์ Google API

คุณจะต้องระบุรหัสไคลเอ็นต์ Google API ในระหว่างกระบวนการลงทะเบียนการลิงก์บัญชี

วิธีรับรหัสไคลเอ็นต์ API โดยใช้โปรเจ็กต์ที่คุณสร้างขึ้นขณะทำตามขั้นตอนการลิงก์ OAuth โดยทำตามขั้นตอนต่อไปนี้

  2. สร้างหรือเลือกโปรเจ็กต์ Google APIs

    หากโปรเจ็กต์ไม่มีรหัสไคลเอ็นต์สำหรับประเภทเว็บแอปพลิเคชัน ให้คลิกสร้างไคลเอ็นต์เพื่อสร้างรหัส อย่าลืมใส่โดเมนของเว็บไซต์ในช่องต้นทางของ JavaScript ที่ได้รับอนุญาต เมื่อทำการทดสอบหรือพัฒนาในเครื่อง คุณต้องเพิ่มทั้ง http://localhost และ http://localhost:<port_number> ลงในช่องต้นทาง JavaScript ที่อนุญาต

ตรวจสอบการติดตั้งใช้งาน

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

  1. 点击配置 以打开 OAuth 2.0 配置窗口。
  2. 在 OAuth flow 字段中，选择 Client-side（客户端）。
  3. 在 OAuth 端点字段中，选择自定义。
  4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
  5. 在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
  6. 在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示版工具验证您的实现。

在该工具中，执行以下步骤：

  1. 点击使用 Google 账号登录按钮。
  2. 选择您要关联的账号。
  3. 输入服务 ID。
  4. （可选）输入您要请求访问权限的一个或多个范围。
  5. 点击开始演示。
  6. 当系统提示时，请确认您同意或拒绝关联请求。
  7. 确认您已被重定向到您的平台。