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

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

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

ในกระบวนการรหัสการให้สิทธิ์ คุณต้องมีปลายทาง 2 จุด ได้แก่

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

• ปลายทาง token Exchange ซึ่งรับผิดชอบ Exchange 2 ประเภทดังนี้

  1. แลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นการรีเฟรชเป็นระยะเวลานานและโทเค็นเพื่อการเข้าถึงที่ใช้งานได้เป็นระยะเวลาสั้นๆ ซึ่ง Exchange นี้จะเกิดขึ้นเมื่อผู้ใช้ทําตามขั้นตอนการลิงก์บัญชี
  2. แลกเปลี่ยนโทเค็นการรีเฟรชเป็นระยะเวลานานสําหรับโทเค็นเพื่อการเข้าถึงเป็นระยะเวลาสั้นๆ Exchange นี้จะเกิดขึ้นเมื่อ 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&#39 ด้วย โปรดดูโลโก้และเครื่องหมายการค้า

รูปที่ 2 หลักเกณฑ์การออกแบบสําหรับผู้ใช้ในการลงชื่อเข้าใช้ Google และหน้าจอคํายินยอม

สร้างโปรเจ็กต์

หมายเหตุ: คุณนําโปรเจ็กต์ที่มีอยู่มาใช้ซ้ำได้และไม่จําเป็นต้องสร้างโปรเจ็กต์ใหม่เพื่อลิงก์บัญชีเป็นหลัก

วิธีสร้างโปรเจ็กต์เพื่อใช้การลิงก์บัญชี

1. Go to the Google API Console.
2. คลิก สร้างโครงการ
3. ป้อนชื่อหรือยอมรับคำแนะนำที่สร้างขึ้น
4. ยืนยันหรือแก้ไขฟิลด์ที่เหลือ
5. คลิก สร้าง

วิธีดูรหัสโครงการของคุณ:

1. Go to the Google API Console.
2. ค้นหาโครงการของคุณในตารางบนหน้า Landing Page รหัสโครงการจะปรากฏในคอลัมน์ ID

กำหนดค่าหน้าจอขอความยินยอม OAuth

กระบวนการลิงก์บัญชี Google ประกอบด้วยหน้าจอคำยินยอมที่แจ้งให้ผู้ใช้ทราบถึงแอปพลิเคชันที่ขอเข้าถึงข้อมูล ประเภทของข้อมูลที่ผู้ใช้ขอ และข้อกำหนดที่บังคับใช้ คุณจะต้องกำหนดค่าหน้าจอขอความยินยอม OAuth ก่อนสร้างรหัสไคลเอ็นต์ของ Google API

1. เปิดหน้าหน้าจอขอความยินยอม OAuth ของคอนโซล Google APIs
2. เมื่อได้รับข้อความแจ้ง ให้เลือกโปรเจ็กต์ที่คุณเพิ่งสร้าง

3. ในหน้า "หน้าจอขอความยินยอม OAuth" ให้กรอกแบบฟอร์มแล้วคลิกปุ่ม "บันทึก"

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

   โลโก้แอปพลิเคชัน: รูปภาพบนหน้าจอคำยินยอมที่จะช่วยให้ผู้ใช้จดจำแอปของคุณ โลโก้จะแสดงในหน้าจอความยินยอมในการลิงก์บัญชีและในการตั้งค่าบัญชี

   อีเมลสนับสนุน: เพื่อให้ผู้ใช้ติดต่อคุณเมื่อมีคำถามเกี่ยวกับความยินยอม

   ขอบเขตสำหรับ Google APIs: ขอบเขตช่วยให้แอปพลิเคชันของคุณเข้าถึงข้อมูล Google ส่วนตัวของผู้ใช้ สำหรับ Use Case การลิงก์บัญชี Google ขอบเขตเริ่มต้น (อีเมล, โปรไฟล์, openid) นั้นเพียงพอแล้ว คุณไม่จำเป็นต้องเพิ่มขอบเขตที่ละเอียดอ่อนใดๆ โดยทั่วไปแล้ว แนวทางปฏิบัติแนะนำคือให้ขอขอบเขตเพิ่มขึ้นเรื่อยๆ ในเวลาที่จำเป็นต้องเข้าถึง แทนที่จะขอตั้งแต่แรก ดูข้อมูลเพิ่มเติม

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

   ลิงก์หน้าแรกของแอปพลิเคชัน: หน้าแรกของแอปพลิเคชัน ต้องโฮสต์ในโดเมนที่ได้รับอนุญาต

   ลิงก์นโยบายความเป็นส่วนตัวของแอปพลิเคชัน: แสดงในหน้าจอขอความยินยอมการลิงก์บัญชี Google ต้องโฮสต์ในโดเมนที่ได้รับอนุญาต

   ลิงก์ข้อกำหนดในการให้บริการของแอปพลิเคชัน (ไม่บังคับ): ต้องโฮสต์ในโดเมนที่ได้รับอนุญาต

   

   รูปที่ 1 หน้าจอแสดงความยินยอมในการเชื่อมโยงบัญชี Google สำหรับแอปพลิเคชันที่สมมติขึ้น เช่น Tunery

4. ตรวจสอบ "สถานะการยืนยัน" หากใบสมัครของคุณต้องมีการยืนยัน ให้คลิกปุ่ม "ส่งเพื่อขอรับการยืนยัน" เพื่อส่งใบสมัครเข้ารับการยืนยัน โปรดดูรายละเอียดที่ข้อกำหนดการยืนยัน OAuth

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

เพื่อสนับสนุนการไหลนัย 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 การบริการของคุณในภายหลัง

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header	The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

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

For your userinfo endpoint to handle requests, do the following steps:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response:

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

   If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

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

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   userinfo endpoint response
   sub	A unique ID that identifies the user in your system.
   email	Email address of the user.
   given_name	Optional: First name of the user.
   family_name	Optional: Last name of the user.
   name	Optional: Full name of the user.
   picture	Optional: Profile picture of the user.

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

คุณสามารถตรวจสอบการดำเนินงานของคุณโดยใช้ OAuth 2.0 สนามเด็กเล่น เครื่องมือ

ในเครื่องมือ ให้ทำตามขั้นตอนต่อไปนี้:

1. คลิกการกำหนดค่า เพื่อเปิดหน้าต่าง OAuth 2.0 การกำหนดค่า
2. ในด้านการไหล OAuth เลือกฝั่งไคลเอ็นต์
3. ในฟิลด์ OAuth ปลายทางเลือกที่กำหนดเอง
4. ระบุตำแหน่งข้อมูล OAuth 2.0 และรหัสไคลเอ็นต์ที่คุณกำหนดให้กับ Google ในช่องที่เกี่ยวข้อง
5. ในขั้นตอนที่ 1 ส่วนที่ไม่ได้เลือกขอบเขตใด ๆ ของ Google ให้ปล่อยฟิลด์นี้ว่างไว้หรือพิมพ์ขอบเขตที่ถูกต้องสำหรับเซิร์ฟเวอร์ของคุณ (หรือสตริงที่กำหนดเองหากคุณไม่ได้ใช้ขอบเขต OAuth) เมื่อคุณทำเสร็จแล้วคลิกอนุญาต APIs
6. ในขั้นตอนที่ 2 และขั้นตอนที่ 3 ส่วนไปไหลผ่าน OAuth 2.0 และตรวจสอบว่าแต่ละขั้นตอนการทำงานตามที่ตั้งใจไว้

คุณสามารถตรวจสอบการดำเนินงานของคุณโดยใช้ บัญชี Google เชื่อมโยงการสาธิต เครื่องมือ

ในเครื่องมือ ให้ทำตามขั้นตอนต่อไปนี้:

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