การลิงก์ที่มีประสิทธิภาพยิ่งขึ้นด้วย 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

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

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

ตรวจหาบัญชีผู้ใช้ที่มีอยู่ (ตรวจสอบความตั้งใจ)

หลังจากผู้ใช้ให้คํายินยอมในการเข้าถึงโปรไฟล์ Google แล้ว Google จะส่งคําขอที่มีการยืนยันข้อมูลประจําตัวของผู้ใช้ Google ที่ลงชื่อแล้ว ข้อความยืนยันประกอบด้วยรหัสบัญชี ชื่อ และอีเมลใน Google ของผู้ใช้ ปลายทางของการแลกเปลี่ยนโทเค็นที่กําหนดค่าไว้สําหรับโปรเจ็กต์จะจัดการคําขอนั้น

หากมีบัญชี 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 (JWT) ที่ยืนยันตัวตนผู้ใช้ของ Google พร้อมลงนาม JWT มีข้อมูลที่รวมรหัสบัญชี Google, ชื่อ และอีเมลของ Google
client_id รหัสไคลเอ็นต์ที่คุณกําหนดให้ Google
client_secret รหัสลับไคลเอ็นต์ที่คุณกําหนดให้ Google

ในการตอบสนองต่อคําขอ Intent ของ check ปลายทางของการแลกเปลี่ยนโทเค็นของคุณจะต้องทําตามขั้นตอนต่อไปนี้

  • ตรวจสอบและถอดรหัสการยืนยัน JWT
  • ตรวจสอบว่าบัญชี Google ดังกล่าวอยู่ในระบบการตรวจสอบสิทธิ์แล้วหรือไม่
验证并解码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并不具有权威性，建议您使用密码或其他验证方法来验证用户。当Google在创建Google帐户时最初验证了用户时， email_verfied也可能为true，但是此后第三方电子邮件帐户的所有权可能已更改。

ตรวจสอบว่ามีบัญชี Google อยู่ในระบบการตรวจสอบสิทธิ์แล้วหรือไม่

ตรวจสอบว่าเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้เป็นจริงหรือไม่

  • รหัสบัญชี Google ที่พบในช่อง sub การยืนยันอยู่ในฐานข้อมูลผู้ใช้ของคุณ
  • อีเมลในโปรแกรมยืนยันตรงกับผู้ใช้ในฐานข้อมูลผู้ใช้

หากเงื่อนไขข้อใดข้อหนึ่งเป็นจริง แสดงว่าผู้ใช้ลงชื่อสมัครใช้แล้ว ในกรณีดังกล่าว ให้ตอบกลับดังนี้

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

{
  "account_found":"true",
}

หากรหัสบัญชี Google และอีเมลที่ระบุในการยืนยันไม่ตรงกับผู้ใช้ในฐานข้อมูลของคุณ ผู้ใช้ก็ยังไม่ได้ลงชื่อสมัครใช้ ในกรณีนี้ ปลายทางของการแลกเปลี่ยนโทเค็นของคุณต้องตอบกลับด้วยข้อผิดพลาด 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 帐号，则您的令牌交换端点会返回用户的令牌。如果 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解码库来验证和解码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并不具有权威性，建议您使用密码或其他验证方法来验证用户。当Google在创建Google帐户时最初验证了用户时， email_verfied也可能为true，但是此后第三方电子邮件帐户的所有权可能已更改。

检查您的身份验证系统中是否已存在该 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 关联流程完成帐号关联。

Handle account creation via Google Sign-In (create intent)

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create.

The request has the following form:

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

Your token exchange endpoint must able to handle the following parameters:

Token endpoint parameters
intent For these requests, the value of this parameter is create.
grant_type The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
client_id The client ID you assigned to Google.
client_secret The client secret you assigned to Google.

The JWT within the assertion parameter contains the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to the create intent requests, your token exchange endpoint must perform the following steps:

  • Validate and decode the JWT assertion.
  • Validate user information and create new account.
验证并解码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并不具有权威性，建议您使用密码或其他验证方法来验证用户。当Google在创建Google帐户时最初验证了用户时， email_verfied也可能为true，但是此后第三方电子邮件帐户的所有权可能已更改。

Validate user information and create new account

Check whether either of the following conditions are true:

  • The Google Account ID, found in the assertion's sub field, is in your user database.
  • The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account. To do so, respond to the request with an HTTP 401 error that specifies error=linking_error and gives the user's email address as the login_hint. The following is a sample response:

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

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

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.

When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example: 

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

  "expires_in": SECONDS_TO_EXPIRATION
}

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

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

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

  1. เปิดหน้าข้อมูลเข้าสู่ระบบของคอนโซล Google API

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

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

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

您可以通过使用验证实现的OAuth 2.0游乐场工具。

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

  1. 单击配置打开的OAuth 2.0配置窗口。
  2. 在OAuth流场中，选择客户端。
  3. 在OAuth端点字段中，选择自定义。
  4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
  5. 在步骤1部分，不要选择任何谷歌范围。相反，将此字段留空或键入对您的服务器有效的范围（如果不使用 OAuth 范围，则输入任意字符串）。当您完成后，单击授权的API。
  6. 在步骤2和步骤3段，完成OAuth 2.0流程和验证每个步骤按预期工作。

您可以通过验证您的实现谷歌帐户链接演示工具。

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

  1. 点击登录在与谷歌按钮。
  2. 选择您要关联的帐户。
  3. 输入服务标识。
  4. （可选）输入您将请求访问的一个或多个范围。
  5. 单击开始演示。
  6. 出现提示时，确认您可以同意并拒绝链接请求。
  7. 确认您被重定向到您的平台。