การลิงก์บัญชี Google กับ OAuth

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

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

ในขั้นตอนรหัสการให้สิทธิ์ คุณต้องมีปลายทาง 2 รายการดังนี้

• ปลายทางการให้สิทธิ์ ซึ่งแสดง UI การลงชื่อเข้าใช้ต่อผู้ใช้ที่ยังไม่ได้ลงชื่อเข้าใช้ ปลายทางการให้สิทธิ์จะสร้างรหัสการให้สิทธิ์ที่มีอายุสั้นเพื่อบันทึกความยินยอมของผู้ใช้ในการเข้าถึงที่ขอ

• ปลายทางการแลกเปลี่ยนโทเค็น ซึ่งรับผิดชอบต่อการแลกเปลี่ยน 2 ประเภทดังนี้

  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 ของผู้ใช้และหน้าจอความยินยอม

Create the project

Note: You can reuse an existing project and do not need to create a new project primarily for account linking.

To create your project to use account linking:

1. Go to the Google API Console.
2. Click Create project.
3. Enter a name or accept the generated suggestion.
4. Confirm or edit any remaining fields.
5. Click Create.

To view your project ID:

1. Go to the Google API Console.
2. Find your project in the table on the landing page. The project ID appears in the ID column.

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

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

บริการของคุณจะให้สิทธิ์เพื่อรองรับขั้นตอน implicit ของ OAuth 2.0 ปลายทางที่พร้อมใช้งานผ่าน HTTPS ปลายทางนี้มีหน้าที่ในการตรวจสอบสิทธิ์และ ได้รับความยินยอมจากผู้ใช้ในการเข้าถึงข้อมูล ปลายทางการให้สิทธิ์ แสดง UI การลงชื่อเข้าใช้แก่ผู้ใช้ที่ยังไม่ได้ลงชื่อเข้าใช้และบันทึกไว้ ความยินยอมต่อการเข้าถึงที่ขอ

เมื่อแอปพลิเคชันของ Google ต้องเรียกใช้ API ที่ได้รับอนุญาตของบริการ Google ใช้ปลายทางนี้เพื่อขอสิทธิ์จากผู้ใช้เพื่อเรียกใช้ API เหล่านี้ ในนามของผู้ลงโฆษณา

เซสชันโฟลว์แบบโดยนัยของ 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

เครื่องจัดการการเปลี่ยนเส้นทาง OAuth 2.0 ของ Google ได้รับโทเค็นเพื่อการเข้าถึงและยืนยัน ค่า 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	可选：用户的个人资料照片。

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

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign-in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.