การลิงก์บัญชี 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 หลังจากที่แอปของ Google เรียกแล้ว #, แพลตฟอร์มจะแสดงการลงชื่อเข้าใช้หน้า Google และหน้าจอคํายินยอมในการลิงก์บัญชีแก่ผู้ใช้ ระบบจะเปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปของ Google หลังจากให้ความยินยอมในการลิงก์บัญชี

รูปนี้แสดงขั้นตอนที่ผู้ใช้ลิงก์บัญชี Google กับระบบการตรวจสอบสิทธิ์ ภาพหน้าจอแรกแสดงการลิงก์ที่ผู้ใช้เริ่มต้นจากแพลตฟอร์ม รูปภาพที่ 2 แสดงการลงชื่อเข้าใช้ Google ของผู้ใช้ ในขณะที่รูปที่ 3 แสดงคํายินยอมของผู้ใช้และการยืนยันเพื่อลิงก์บัญชี 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 ด้วย โปรดดูโลโก้และเครื่องหมายการค้า

Create the project

To create your project to use account linking:

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

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

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

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

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
  2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
  3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.
user_locale The Google Account language setting in RFC5646 format used to localize your content in the user's preferred language.

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

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: The access token you just generated
    • token_type: The string bearer
    • state: The unmodified state value from the original request

    The following is an example of the resulting URL: 

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

จัดการคำขอข้อมูลผู้ใช้

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

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

ส่วนหัวคำขอปลายทางข้อมูลผู้ใช้
Authorization header โทเค็นการเข้าถึงของประเภท Bearer

ตัวอย่างเช่นถ้าปลายทางของคุณ UserInfo สามารถใช้ได้ที่ https://myservice.example.com/userinfo คำขออาจมีลักษณะดังต่อไปนี้:

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

เพื่อให้ปลายทางข้อมูลผู้ใช้ของคุณจัดการกับคำขอ ให้ทำตามขั้นตอนต่อไปนี้:

  1. แยกโทเค็นการเข้าถึงออกจากส่วนหัวการให้สิทธิ์และส่งคืนข้อมูลสำหรับผู้ใช้ที่เชื่อมโยงกับโทเค็นการเข้าถึง
  2. ถ้าโทเค็นการเข้าถึงไม่ถูกต้องกลับ HTTP 401 ข้อผิดพลาดไม่ได้รับอนุญาตในการใช้ WWW-Authenticate ตอบสนองส่วนหัว ด้านล่างนี้เป็นตัวอย่างของการตอบสนองต่อข้อผิดพลาด UserInfo นี้:
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    ถ้า 401 ไม่ได้รับอนุญาตหรือการตอบสนองต่อข้อผิดพลาดไม่ประสบความสำเร็จอื่น ๆ จะถูกส่งกลับในระหว่างขั้นตอนการเชื่อมโยงข้อผิดพลาดจะไม่สามารถกู้คืนโทเค็นที่ดึงจะถูกยกเลิกและผู้ใช้จะต้อง เพื่อเริ่มกระบวนการเชื่อมโยงอีกครั้ง

  3. ถ้าโทเค็นการเข้าถึงที่ถูกต้องผลตอบแทนและ HTTP 200 ตอบสนองกับวัตถุ JSON ต่อไปในร่างกายของการตอบสนอง https: 

    {
"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 รูปโปรไฟล์ของผู้ใช้ตัวเลือก:

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

คุณสามารถตรวจสอบการดำเนินงานของคุณโดยใช้ 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. ยืนยันว่าคุณถูกเปลี่ยนเส้นทางไปยังแพลตฟอร์มของคุณ