การใช้ OAuth 2.0 สําหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์

เอกสารนี้อธิบายวิธีที่แอปพลิเคชันเว็บเซิร์ฟเวอร์ใช้ไลบรารีของไคลเอ็นต์ Google API หรือปลายทาง OAuth 2.0 ของ Google เพื่อใช้การให้สิทธิ์ OAuth 2.0 เพื่อเข้าถึง Google API

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

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

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

ไลบรารีของไคลเอ็นต์

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

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

ไลบรารีของไคลเอ็นต์ Google API สําหรับแอปพลิเคชันฝั่งเซิร์ฟเวอร์มีให้บริการในภาษาต่อไปนี้

สิ่งที่ต้องมีก่อน

เปิดใช้ API สําหรับโปรเจ็กต์

แอปพลิเคชันใดก็ตามที่เรียกใช้ Google API ต้องเปิดใช้ API เหล่านั้นใน API Console

วิธีเปิดใช้ API สําหรับโปรเจ็กต์

  1. Open the API Library ใน Google API Console
  2. If prompted, select a project, or create a new one.
  3. API Library จะแสดงรายการ API ที่มีอยู่ทั้งหมด โดยจัดกลุ่มตามประเภทผลิตภัณฑ์และความนิยม หากไม่เห็น API ที่ต้องการเปิดใช้ในรายการ ให้ใช้การค้นหาเพื่อค้นหาหรือคลิก ดูทั้งหมด ในตระกูลผลิตภัณฑ์
  4. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

สร้างข้อมูลรับรองการให้สิทธิ์

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

  1. Go to the Credentials page.
  2. คลิกสร้างข้อมูลรับรอง &gt รหัสไคลเอ็นต์ OAuth
  3. เลือกประเภทแอปพลิเคชันเว็บแอปพลิเคชัน
  4. กรอกข้อมูลในแบบฟอร์ม และคลิกสร้าง แอปพลิเคชันที่ใช้ภาษาและเฟรมเวิร์ก เช่น PHP, Java, Python, Ruby และ .NET ต้องระบุ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาต URI การเปลี่ยนเส้นทางคือปลายทางที่เซิร์ฟเวอร์ OAuth 2.0 ส่งการตอบกลับได้ ปลายทางเหล่านี้ต้องเป็นไปตามกฎการตรวจสอบของ Google

    สําหรับการทดสอบ คุณระบุ URI ที่อ้างอิงถึงเครื่องตนเองได้ เช่น http://localhost:8080 โปรดทราบว่าตัวอย่างทั้งหมดในเอกสารนี้ใช้ http://localhost:8080 เป็น URI การเปลี่ยนเส้นทาง

    เราขอแนะนําให้ออกแบบปลายทางการตรวจสอบสิทธิ์ของแอปเพื่อให้แอปพลิเคชันไม่เปิดเผยรหัสการให้สิทธิ์แก่ทรัพยากรอื่นๆ ในหน้าเว็บ

หลังจากสร้างข้อมูลรับรองแล้ว ให้ดาวน์โหลดไฟล์ client_secret.json จาก API Consoleโปรดเก็บไฟล์ไว้ในตําแหน่งที่ปลอดภัย ซึ่งจะมีเพียงแอปพลิเคชันเท่านั้นที่เข้าถึงได้

ระบุขอบเขตการเข้าถึง

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

ก่อนที่จะเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนําให้ระบุขอบเขตที่แอปจําเป็นต้องมีสิทธิ์เข้าถึง

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

เอกสารขอบเขต OAuth 2.0 API จะมีรายการขอบเขตทั้งหมดที่คุณอาจนําไปใช้เข้าถึง Google API ได้

ข้อกําหนดเฉพาะภาษา

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

PHP

ในการเรียกใช้ตัวอย่างโค้ด PHP ในเอกสารนี้ คุณจะต้องมีสิ่งต่อไปนี้

  • PHP 5.6 หรือสูงกว่าที่มีการติดตั้งส่วนขยายบรรทัดคําสั่ง (CLI) และส่วนขยาย JSON
  • เครื่องมือจัดการทรัพยากร Dependency ของ Composer
  • ไลบรารีของไคลเอ็นต์ Google APIs สําหรับ PHP:

    composer require google/apiclient:^2.10

Python

หากต้องการเรียกใช้ตัวอย่างโค้ด Python ในเอกสารนี้ คุณจะต้องมีสิ่งต่อไปนี้

  • Python 2.6 ขึ้นไป
  • เครื่องมือจัดการแพ็กเกจ pip
  • ไลบรารีของไคลเอ็นต์ Google API สําหรับ Python
    pip install --upgrade google-api-python-client
  • google-auth, google-auth-oauthlib และ google-auth-httplib2 สําหรับการให้สิทธิ์ผู้ใช้
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • เฟรมเวิร์กเว็บแอปพลิเคชัน Flask Python
    pip install --upgrade flask
  • ไลบรารี HTTP requests
    pip install --upgrade requests

Ruby

หากต้องการเรียกใช้ตัวอย่างโค้ด Ruby ในเอกสารนี้ คุณจะต้องมีสิ่งต่อไปนี้

  • Ruby 2.2.2 หรือสูงกว่า
  • ไลบรารีของไคลเอ็นต์ Google APIs สําหรับ Ruby:

    gem install google-api-client
  • เฟรมเวิร์กเว็บแอปพลิเคชัน Sinatra Ruby

    gem install sinatra

Node.js

หากต้องการเรียกใช้ตัวอย่างโค้ด Node.js ในเอกสารนี้ คุณจะต้องมีสิ่งต่อไปนี้

  • LTS การบํารุงรักษา, LTS ที่ใช้งานอยู่ หรือ Node.js ที่เผยแพร่ในปัจจุบัน
  • ไคลเอ็นต์ Node.js ของ Google APIs:

    npm install googleapis

HTTP/REST

คุณไม่จําเป็นต้องติดตั้งไลบรารีใดๆ เพื่อให้สามารถเรียกใช้ปลายทาง OAuth 2.0 ได้โดยตรง

การรับโทเค็นเพื่อการเข้าถึง OAuth 2.0

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

รายการด้านล่างนี้จะสรุปขั้นตอนเหล่านี้ไว้อย่างรวดเร็ว

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

ขั้นตอนที่ 1: ตั้งค่าพารามิเตอร์การให้สิทธิ์

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

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

แท็บด้านล่างจะกําหนดพารามิเตอร์การให้สิทธิ์ที่รองรับสําหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์ ตัวอย่างภาษาที่เจาะจงจะแสดงวิธีใช้ไลบรารีของไคลเอ็นต์หรือไลบรารีการให้สิทธิ์เพื่อกําหนดค่าออบเจ็กต์ที่ตั้งค่าพารามิเตอร์เหล่านั้น

PHP

ข้อมูลโค้ดด้านล่างจะสร้างออบเจ็กต์ Google\Client() ซึ่งจะกําหนดพารามิเตอร์ในคําขอการให้สิทธิ์

ออบเจ็กต์ดังกล่าวใช้ข้อมูลจากไฟล์ client_secret.json เพื่อระบุแอปพลิเคชัน (ดูรายละเอียดเพิ่มเติมเกี่ยวกับไฟล์ดังกล่าวในการสร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์) ออบเจ็กต์ยังระบุขอบเขตที่แอปพลิเคชันกําลังขอสิทธิ์เข้าถึงและ URL ไปยังปลายทางการตรวจสอบสิทธิ์ของแอปพลิเคชันของคุณด้วย ซึ่งจะจัดการกับการตอบกลับจากเซิร์ฟเวอร์ OAuth 2.0 ของ Google สุดท้าย โค้ดจะตั้งค่าพารามิเตอร์ access_type และ include_granted_scopes ซึ่งไม่บังคับ

ตัวอย่างเช่น โค้ดนี้ขอเข้าถึง Google ไดรฟ์ของผู้ใช้แบบอ่านอย่างเดียวและออฟไลน์อยู่

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

คําขอจะระบุข้อมูลต่อไปนี้

พารามิเตอร์
client_id จำเป็น

รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials page

ใน PHP ให้เรียกฟังก์ชัน setAuthConfig เพื่อโหลดข้อมูลเข้าสู่ระบบการให้สิทธิ์จากไฟล์ client_secret.json

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
redirect_uri จำเป็น

กําหนดเซิร์ฟเวอร์ API ที่เปลี่ยนเส้นทางผู้ใช้หลังจากที่ผู้ใช้ให้สิทธิ์ในกระบวนการเสร็จสมบูรณ์ ค่านี้ต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าใน API Consoleของ Credentials pageหากค่านี้ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับ client_id ที่ระบุ คุณจะได้รับข้อผิดพลาด redirect_uri_mismatch

โปรดทราบว่ารูปแบบ เคส และเครื่องหมายทับปิดท้าย ( #39;/') ของ http หรือ https ต้องตรงกันทั้งหมด

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกฟังก์ชัน setRedirectUri โปรดทราบว่าคุณต้องระบุ URI การเปลี่ยนเส้นทางที่ถูกต้องสําหรับ client_id ที่ระบุ

$client->setRedirectUri('https://oauth2.example.com/code');
scope จำเป็น

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

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

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน addScope:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

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

access_type แนะนำ

ระบุว่าแอปพลิเคชันจะรีเฟรชโทเค็นเพื่อการเข้าถึงหรือไม่เมื่อไม่มีผู้ใช้อยู่ในเบราว์เซอร์ ค่าพารามิเตอร์ที่ถูกต้องคือ online ซึ่งเป็นค่าเริ่มต้นและ offline

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

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน setAccessType:

$client->setAccessType('offline');
state แนะนำ

ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์ เซิร์ฟเวอร์จะแสดงผลค่าที่แน่นอนที่คุณส่งเป็นคู่ name=value ในคอมโพเนนต์คําค้นหา URL (?) ของ redirect_uri หลังจากที่ผู้ใช้ให้ความยินยอมหรือปฏิเสธคําขอเข้าถึงแอปพลิเคชันของคุณ

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

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน setState:

$client->setState($sample_passthrough_value);
include_granted_scopes ไม่บังคับ

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

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน setIncludeGrantedScopes:

$client->setIncludeGrantedScopes(true);
login_hint ไม่บังคับ

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

ตั้งค่าพารามิเตอร์เป็นอีเมลหรือตัวระบุ sub ซึ่งเทียบเท่ากับรหัส Google ของผู้ใช้

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน setLoginHint:

$client->setLoginHint('None');
prompt ไม่บังคับ

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

หากต้องการตั้งค่านี้เป็น PHP ให้เรียกใช้ฟังก์ชัน setApprovalPrompt:

$client->setApprovalPrompt('consent');

ค่าที่เป็นไปได้มีดังนี้

none ไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือคํายินยอม ต้องไม่ระบุค่าอื่นๆ
consent แจ้งให้ผู้ใช้ขอความยินยอม
select_account แจ้งเตือนให้ผู้ใช้เลือกบัญชี

Python

ข้อมูลโค้ดต่อไปนี้ใช้โมดูล google-auth-oauthlib.flow เพื่อสร้างคําขอการให้สิทธิ์

โค้ดนี้จะสร้างออบเจ็กต์ Flow ซึ่งระบุแอปพลิเคชันโดยใช้ข้อมูลจากไฟล์ client_secret.json ที่คุณดาวน์โหลดหลังการสร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์ ออบเจ็กต์ดังกล่าวยังระบุขอบเขตที่แอปพลิเคชันกําลังขอสิทธิ์เข้าถึงและ URL ไปยังปลายทางการตรวจสอบสิทธิ์ของแอปพลิเคชันของคุณด้วย ซึ่งจะจัดการกับการตอบกลับจากเซิร์ฟเวอร์ OAuth 2.0 ของ Google สุดท้าย โค้ดจะตั้งค่าพารามิเตอร์ access_type และ include_granted_scopes ซึ่งไม่บังคับ

ตัวอย่างเช่น โค้ดนี้ขอเข้าถึง Google ไดรฟ์ของผู้ใช้แบบอ่านอย่างเดียวและออฟไลน์อยู่

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

คําขอจะระบุข้อมูลต่อไปนี้

พารามิเตอร์
client_id จำเป็น

รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials page

ใน Python ให้เรียกใช้เมธอด from_client_secrets_file เพื่อเรียกรหัสไคลเอ็นต์จากไฟล์ client_secret.json (คุณยังใช้เมธอด from_client_config ซึ่งส่งการกําหนดค่าไคลเอ็นต์ตามที่ปรากฏในไฟล์ข้อมูลลับของไคลเอ็นต์ได้ด้วยแต่จะเข้าถึงไฟล์ไม่ได้)

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
redirect_uri จำเป็น

กําหนดเซิร์ฟเวอร์ API ที่เปลี่ยนเส้นทางผู้ใช้หลังจากที่ผู้ใช้ให้สิทธิ์ในกระบวนการเสร็จสมบูรณ์ ค่านี้ต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าใน API Consoleของ Credentials pageหากค่านี้ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับ client_id ที่ระบุ คุณจะได้รับข้อผิดพลาด redirect_uri_mismatch

โปรดทราบว่ารูปแบบ เคส และเครื่องหมายทับปิดท้าย ( #39;/') ของ http หรือ https ต้องตรงกันทั้งหมด

หากต้องการตั้งค่านี้ใน Python ให้ตั้งค่าพร็อพเพอร์ตี้ flow object's redirect_uri

flow.redirect_uri = 'https://oauth2.example.com/code'
scope จำเป็น

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

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

ใน Python ให้ใช้วิธีเดียวกับที่ใช้ตั้งค่า client_id เพื่อระบุรายการขอบเขต

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

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

access_type แนะนำ

ระบุว่าแอปพลิเคชันจะรีเฟรชโทเค็นเพื่อการเข้าถึงหรือไม่เมื่อไม่มีผู้ใช้อยู่ในเบราว์เซอร์ ค่าพารามิเตอร์ที่ถูกต้องคือ online ซึ่งเป็นค่าเริ่มต้นและ offline

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

ใน Python ให้ตั้งพารามิเตอร์ access_type โดยระบุ access_type เป็นอาร์กิวเมนต์คีย์เวิร์ดเมื่อเรียกใช้เมธอด flow.authorization_url ดังนี้

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
state แนะนำ

ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์ เซิร์ฟเวอร์จะแสดงผลค่าที่แน่นอนที่คุณส่งเป็นคู่ name=value ในคอมโพเนนต์คําค้นหา URL (?) ของ redirect_uri หลังจากที่ผู้ใช้ให้ความยินยอมหรือปฏิเสธคําขอเข้าถึงแอปพลิเคชันของคุณ

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

ใน Python ให้ตั้งพารามิเตอร์ state โดยระบุ state เป็นอาร์กิวเมนต์คีย์เวิร์ดเมื่อเรียกใช้เมธอด flow.authorization_url ดังนี้

authorization_url, state = flow.authorization_url(
    access_type='offline',
    state=sample_passthrough_value,
    include_granted_scopes='true')
include_granted_scopes ไม่บังคับ

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

ใน Python ให้ตั้งพารามิเตอร์ include_granted_scopes โดยระบุ include_granted_scopes เป็นอาร์กิวเมนต์คีย์เวิร์ดเมื่อเรียกใช้เมธอด flow.authorization_url ดังนี้

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
login_hint ไม่บังคับ

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

ตั้งค่าพารามิเตอร์เป็นอีเมลหรือตัวระบุ sub ซึ่งเทียบเท่ากับรหัส Google ของผู้ใช้

ใน Python ให้ตั้งพารามิเตอร์ login_hint โดยระบุ login_hint เป็นอาร์กิวเมนต์คีย์เวิร์ดเมื่อเรียกใช้เมธอด flow.authorization_url ดังนี้

authorization_url, state = flow.authorization_url(
    access_type='offline',
    login_hint='None',
    include_granted_scopes='true')
prompt ไม่บังคับ

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

ใน Python ให้ตั้งพารามิเตอร์ prompt โดยระบุ prompt เป็นอาร์กิวเมนต์คีย์เวิร์ดเมื่อเรียกใช้เมธอด flow.authorization_url ดังนี้

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

ค่าที่เป็นไปได้มีดังนี้

none ไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือคํายินยอม ต้องไม่ระบุค่าอื่นๆ
consent แจ้งให้ผู้ใช้ขอความยินยอม
select_account แจ้งเตือนให้ผู้ใช้เลือกบัญชี

Ruby

ใช้ไฟล์ client_secrets.json ที่คุณสร้างขึ้นเพื่อกําหนดค่าออบเจ็กต์ไคลเอ็นต์ในแอปพลิเคชัน เมื่อกําหนดค่าออบเจ็กต์ไคลเอ็นต์ คุณจะระบุขอบเขตที่แอปพลิเคชันจําเป็นต้องเข้าถึง พร้อมกับ URL ไปยังปลายทางการตรวจสอบสิทธิ์ของแอปพลิเคชัน ซึ่งจะจัดการการตอบสนองจากเซิร์ฟเวอร์ OAuth 2.0

ตัวอย่างเช่น โค้ดนี้ขอเข้าถึง Google ไดรฟ์ของผู้ใช้แบบอ่านอย่างเดียวและออฟไลน์อยู่

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'

client_secrets = Google::APIClient::ClientSecrets.load
auth_client = client_secrets.to_authorization
auth_client.update!(
  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
  :redirect_uri => 'http://www.example.com/oauth2callback',
  :additional_parameters => {
    "access_type" => "offline",         # offline access
    "include_granted_scopes" => "true"  # incremental auth
  }
)

แอปพลิเคชันของคุณใช้ออบเจ็กต์ไคลเอ็นต์เพื่อดําเนินการ OAuth 2.0 เช่น การสร้าง URL คําขอการให้สิทธิ์และใช้โทเค็นเพื่อการเข้าถึงกับคําขอ HTTP

Node.js

ข้อมูลโค้ดด้านล่างจะสร้างออบเจ็กต์ google.auth.OAuth2 ซึ่งจะกําหนดพารามิเตอร์ในคําขอการให้สิทธิ์

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

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

หมายเหตุสําคัญ - refresh_token จะแสดงผลในการให้สิทธิ์ครั้งแรกเท่านั้น ดูรายละเอียดเพิ่มเติมที่นี่

HTTP/REST

ปลายทางของ OAuth 2.0 ของ Google อยู่ที่ https://accounts.google.com/o/oauth2/v2/auth ปลายทางนี้เข้าถึงได้ผ่าน HTTPS เท่านั้น การเชื่อมต่อ HTTP ธรรมดาถูกปฏิเสธ

เซิร์ฟเวอร์การให้สิทธิ์ของ Google รองรับพารามิเตอร์สตริงการค้นหาต่อไปนี้สําหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์

พารามิเตอร์
client_id จำเป็น

รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials page

redirect_uri จำเป็น

กําหนดเซิร์ฟเวอร์ API ที่เปลี่ยนเส้นทางผู้ใช้หลังจากที่ผู้ใช้ให้สิทธิ์ในกระบวนการเสร็จสมบูรณ์ ค่านี้ต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าใน API Consoleของ Credentials pageหากค่านี้ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับ client_id ที่ระบุ คุณจะได้รับข้อผิดพลาด redirect_uri_mismatch

โปรดทราบว่ารูปแบบ เคส และเครื่องหมายทับปิดท้าย ( #39;/') ของ http หรือ https ต้องตรงกันทั้งหมด

response_type จำเป็น

ระบุว่าปลายทาง OAuth 2.0 ของ Google แสดงรหัสการให้สิทธิ์หรือไม่

ตั้งค่าพารามิเตอร์เป็น code สําหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์

scope จำเป็น

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

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

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

access_type แนะนำ

ระบุว่าแอปพลิเคชันจะรีเฟรชโทเค็นเพื่อการเข้าถึงหรือไม่เมื่อไม่มีผู้ใช้อยู่ในเบราว์เซอร์ ค่าพารามิเตอร์ที่ถูกต้องคือ online ซึ่งเป็นค่าเริ่มต้นและ offline

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

state แนะนำ

ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์ เซิร์ฟเวอร์จะแสดงผลค่าที่แน่นอนที่คุณส่งเป็นคู่ name=value ในคอมโพเนนต์คําค้นหา URL (?) ของ redirect_uri หลังจากที่ผู้ใช้ให้ความยินยอมหรือปฏิเสธคําขอเข้าถึงแอปพลิเคชันของคุณ

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

include_granted_scopes ไม่บังคับ

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

login_hint ไม่บังคับ

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

ตั้งค่าพารามิเตอร์เป็นอีเมลหรือตัวระบุ sub ซึ่งเทียบเท่ากับรหัส Google ของผู้ใช้

prompt ไม่บังคับ

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

ค่าที่เป็นไปได้มีดังนี้

none ไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือคํายินยอม ต้องไม่ระบุค่าอื่นๆ
consent แจ้งให้ผู้ใช้ขอความยินยอม
select_account แจ้งเตือนให้ผู้ใช้เลือกบัญชี

ขั้นตอนที่ 2: เปลี่ยนเส้นทางไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google

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

PHP

  1. สร้าง URL เพื่อขอสิทธิ์เข้าถึงเซิร์ฟเวอร์ OAuth 2.0 ของ Google
    $auth_url = $client->createAuthUrl();
  2. เปลี่ยนเส้นทางผู้ใช้ไปที่ $auth_url:
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

ตัวอย่างนี้แสดงวิธีเปลี่ยนเส้นทางผู้ใช้ไปยัง URL การให้สิทธิ์โดยใช้เฟรมเวิร์กเว็บแอปพลิเคชัน Flask

return flask.redirect(authorization_url)

Ruby

  1. สร้าง URL เพื่อขอสิทธิ์เข้าถึงเซิร์ฟเวอร์ OAuth 2.0 ของ Google
    auth_uri = auth_client.authorization_uri.to_s
  2. เปลี่ยนเส้นทางผู้ใช้ไปที่ auth_uri

Node.js

  1. ใช้ URL ที่สร้างขึ้น authorizationUrl จากเมธอดขั้นตอนที่ 1 generateAuthUrl เพื่อขอสิทธิ์เข้าถึงจากเซิร์ฟเวอร์ OAuth 2.0 ของ Google
  2. เปลี่ยนเส้นทางผู้ใช้ไปที่ authorizationUrl
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

หลังจากที่สร้าง URL คําขอแล้ว ให้เปลี่ยนเส้นทางผู้ใช้ไปที่ URL นั้น

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

ขั้นตอนที่ 3: Google แสดงข้อความขอความยินยอมจากผู้ใช้

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

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

ข้อผิดพลาด

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

admin_policy_enforced

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

disallowed_useragent

ปลายทางการให้สิทธิ์จะแสดงใน User Agent ที่ฝังซึ่งนโยบาย OAuth 2.0 ของ Google ไม่อนุญาต

Android

นักพัฒนาแอป Android อาจพบข้อความแสดงข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน android.webkit.WebView นักพัฒนาซอฟต์แวร์ควรใช้ไลบรารี Android แทน เช่น Google Sign-In สําหรับ Android หรือ OpenID Foundation' AppAuth for Android

นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป Android เปิดลิงก์เว็บทั่วไปใน User Agent แบบฝัง และผู้ใช้ไปที่ปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรอนุญาตให้ลิงก์ทั่วไปเปิดได้ในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งรวมทั้งเครื่องจัดการ Android App Link หรือแอปเบราว์เซอร์เริ่มต้น ไลบรารีแท็บที่กําหนดเองของ Android ก็เป็นอีกตัวเลือกหนึ่งที่รองรับเช่นกัน

iOS

นักพัฒนา iOS และ macOS อาจพบข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน WKWebView นักพัฒนาแอปควรใช้ไลบรารี iOS เช่น Google Sign-In สําหรับ iOS หรือ OpenID Foundation's AppAuth for iOS

นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป iOS หรือ macOS เปิดลิงก์เว็บทั่วไปใน User Agent ที่ฝัง และผู้ใช้ไปที่ปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรอนุญาตให้ลิงก์ทั่วไปเปิดในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งรวมทั้งเครื่องจัดการ Universal Link หรือแอปเบราว์เซอร์เริ่มต้น รวมถึงรองรับไลบรารี SFSafariViewController ด้วย

org_internal

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

redirect_uri_mismatch

redirect_uri ที่ส่งผ่านในคําขอการให้สิทธิ์ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับรหัสไคลเอ็นต์ OAuth ตรวจสอบ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตใน Google API Console Credentials page

ขั้นตอนที่ 4: จัดการการตอบกลับของเซิร์ฟเวอร์ OAuth 2.0

เซิร์ฟเวอร์ OAuth 2.0 จะตอบสนองคําขอเข้าถึงของแอปพลิเคชันโดยใช้ URL ที่ระบุในคําขอ

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

การตอบกลับข้อผิดพลาด:

https://oauth2.example.com/auth?error=access_denied

การตอบกลับรหัสการให้สิทธิ์

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

ตัวอย่างการตอบสนองของเซิร์ฟเวอร์ OAuth 2.0

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

หลังจากเสร็จสิ้นขั้นตอน OAuth 2.0 แล้ว คุณควรเปลี่ยนเส้นทางไปยัง http://localhost/oauth2callback ซึ่งมีแนวโน้มที่จะเกิดข้อผิดพลาด 404 NOT FOUND เว้นแต่เครื่องในระบบจะแสดงไฟล์ในที่อยู่นั้น ขั้นตอนถัดไปจะให้รายละเอียดเพิ่มเติมเกี่ยวกับข้อมูลที่แสดงใน URI เมื่อมีการเปลี่ยนเส้นทางผู้ใช้กลับไปที่แอปพลิเคชัน

ขั้นตอนที่ 5: รหัสการให้สิทธิ์ของ Exchange สําหรับการรีเฟรชโทเค็น

หลังจากที่เว็บเซิร์ฟเวอร์ได้รับรหัสการให้สิทธิ์ ก็จะแลกเปลี่ยนรหัสการให้สิทธิ์กับโทเค็นเพื่อการเข้าถึงได้

PHP

หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึง ให้ใช้เมธอด authenticate ดังนี้

$client->authenticate($_GET['code']);

คุณเรียกดูโทเค็นเพื่อการเข้าถึงได้โดยใช้เมธอด getAccessToken ดังนี้

$access_token = $client->getAccessToken();

Python

ในหน้าการติดต่อกลับ ให้ใช้ไลบรารี google-auth เพื่อยืนยันการตอบสนองของเซิร์ฟเวอร์การให้สิทธิ์ จากนั้นใช้ flow.fetch_token เพื่อแลกเปลี่ยนรหัสการให้สิทธิ์ในการตอบสนองนั้นสําหรับโทเค็นเพื่อการเข้าถึง โดยทําดังนี้

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึง ให้ใช้เมธอด fetch_access_token! ดังนี้

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึง ให้ใช้เมธอด getToken ดังนี้

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

หากต้องการเปลี่ยนรหัสการให้สิทธิ์ของโทเค็นเพื่อการเข้าถึง ให้เรียกใช้ปลายทาง https://oauth2.googleapis.com/token และตั้งค่าพารามิเตอร์ต่อไปนี้

ช่อง
client_id รหัสไคลเอ็นต์ที่ได้จาก API Console Credentials page
client_secret รหัสลับไคลเอ็นต์ที่ได้จาก API Console Credentials page
code รหัสการให้สิทธิ์ที่ส่งคืนจากคําขอเริ่มต้น
grant_type ตามที่กําหนดไว้ในข้อกําหนด OAuth 2.0 ช่องนี้ต้องตั้งค่าเป็น authorization_code
redirect_uri URI เปลี่ยนเส้นทางรายการใดรายการหนึ่งในโปรเจ็กต์ของคุณในช่วง API ConsoleCredentials page สําหรับ client_id ที่ระบุ

ข้อมูลโค้ดต่อไปนี้แสดงคําขอตัวอย่าง

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

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

คําตอบประกอบด้วยช่องต่อไปนี้

ช่อง
access_token โทเค็นที่แอปพลิเคชันส่งเพื่อให้สิทธิ์คําขอ Google API
expires_in อายุการใช้งานที่เหลือของโทเค็นเพื่อการเข้าถึงเป็นวินาที
refresh_token โทเค็นที่คุณสามารถใช้เพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ โทเค็นการรีเฟรชจะใช้ได้จนกว่าผู้ใช้จะเพิกถอนสิทธิ์เข้าถึง ขอย้ําอีกครั้งว่าช่องนี้จะปรากฏในการตอบกลับนี้ก็ต่อเมื่อคุณตั้งค่าพารามิเตอร์ access_type เป็น offline ในคําขอเริ่มต้นไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google
scope ขอบเขตของการเข้าถึงที่ได้จาก access_token ซึ่งแสดงเป็นรายการสตริงที่คั่นด้วยช่องว่างและคํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
token_type ประเภทของโทเค็นที่แสดงผล ในตอนนี้ ช่องนี้มีค่าเป็น Bearer เสมอ

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการตอบกลับ

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

กําลังเรียกใช้ Google API

PHP

ใช้โทเค็นเพื่อการเข้าถึงเพื่อเรียกใช้ Google API โดยทําตามขั้นตอนต่อไปนี้

  1. หากต้องการใช้โทเค็นเพื่อการเข้าถึงกับออบเจ็กต์ Google\Client ใหม่ เช่น หากจัดเก็บโทเค็นเพื่อการเข้าถึงในเซสชันผู้ใช้ ให้ใช้เมธอด setAccessToken ดังนี้
    $client->setAccessToken($access_token);
  2. สร้างออบเจ็กต์บริการสําหรับ API ที่ต้องการเรียกใช้ คุณสร้างออบเจ็กต์บริการได้โดยระบุออบเจ็กต์ Google\Client ที่ได้รับอนุญาตให้กับเครื่องมือสร้างสําหรับ API ที่ต้องการเรียกใช้ เช่น หากต้องการเรียก Drive API ให้ทําดังนี้
    $drive = new Google\Service\Drive($client);
  3. ส่งคําขอไปยังบริการ API โดยใช้อินเทอร์เฟซจากออบเจ็กต์บริการ เช่น หากต้องการแสดงไฟล์ใน Google ไดรฟ์ของผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว
    $files = $drive->files->listFiles(array())->getItems();

Python

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

  1. สร้างออบเจ็กต์บริการสําหรับ API ที่ต้องการเรียกใช้ คุณสร้างออบเจ็กต์บริการโดยเรียกใช้เมธอด googleapiclient.discovery ของไลบรารี' build ด้วยชื่อและเวอร์ชันของ API และข้อมูลเข้าสู่ระบบของผู้ใช้ เช่น หากต้องการเรียก Drive API เวอร์ชัน 2
    from googleapiclient.discovery import build
    
    drive = build('drive', 'v2', credentials=credentials)
  2. ส่งคําขอไปยังบริการ API โดยใช้อินเทอร์เฟซจากออบเจ็กต์บริการ เช่น หากต้องการแสดงไฟล์ใน Google ไดรฟ์ของผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว
    files = drive.files().list().execute()

Ruby

ใช้ออบเจ็กต์ auth_client เพื่อเรียกใช้ Google API โดยทําตามขั้นตอนต่อไปนี้

  1. สร้างออบเจ็กต์บริการสําหรับ API ที่ต้องการเรียกใช้ เช่น หากต้องการเรียกใช้ Drive API เวอร์ชัน 2 ให้ทําดังนี้
    drive = Google::Apis::DriveV2::DriveService.new
  2. ตั้งค่าข้อมูลเข้าสู่ระบบในบริการ:
    drive.authorization = auth_client
  3. ส่งคําขอไปยังบริการ API โดยใช้อินเทอร์เฟซจากออบเจ็กต์บริการ เช่น หากต้องการแสดงไฟล์ใน Google ไดรฟ์ของผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว
    files = drive.list_files

อีกทางเลือกหนึ่งคือ คุณให้การให้สิทธิ์ตามวิธีการแต่ละวิธีได้โดยการใส่พารามิเตอร์ options ให้กับเมธอด ดังนี้

files = drive.list_files(options: { authorization: auth_client })

Node.js

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

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

หลังจากที่แอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึงแล้ว คุณจะใช้โทเค็นเพื่อเรียก Google API ในนามของบัญชีผู้ใช้หนึ่งๆ ได้หากขอบเขตการเข้าถึงที่จําเป็นโดย API นั้นได้ โดยใส่โทเค็นเพื่อการเข้าถึงในคําขอไปยัง API โดยรวมพารามิเตอร์การค้นหา access_token หรือค่า Authorization ของส่วนหัว HTTP เป็น Bearer หากเป็นไปได้ ส่วนหัว HTTP แนะนําให้ใช้เนื่องจากสตริงการค้นหามักจะปรากฏในบันทึกของเซิร์ฟเวอร์ ในกรณีส่วนใหญ่ คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียก Google API (เช่น เมื่อเรียกใช้ Drive Files API)

คุณจะลองใช้ Google API ทั้งหมดและดูขอบเขตได้ที่ OAuth 2.0 Playground

ตัวอย่าง HTTP GET

การเรียกใช้ปลายทาง drive.files (Drive Files API) โดยใช้ส่วนหัว HTTP ของ Authorization: Bearer อาจมีลักษณะดังนี้ โปรดทราบว่าคุณต้องระบุโทเค็นเพื่อการเข้าถึงของคุณเองดังนี้

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

นี่คือการเรียก API เดียวกันสําหรับผู้ใช้ที่ตรวจสอบสิทธิ์โดยใช้พารามิเตอร์สตริงการค้นหา access_token

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

ตัวอย่างของ curl

คุณทดสอบคําสั่งเหล่านี้ได้โดยใช้แอปพลิเคชันบรรทัดคําสั่ง curl ต่อไปนี้คือตัวอย่างการใช้ตัวเลือกส่วนหัว HTTP (แนะนํา)

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

หรืออาจเลือกวิธีใส่พารามิเตอร์สตริงคําค้นหาก็ได้เช่นกัน

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

ตัวอย่างที่สมบูรณ์

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

PHP

วิธีเรียกใช้ตัวอย่างนี้

  1. ใน API Consoleให้เพิ่ม URL ของเครื่องลงในรายการ URL เปลี่ยนเส้นทาง เช่น เพิ่ม http://localhost:8080
  2. สร้างไดเรกทอรีใหม่และเปลี่ยนเป็นไดเรกทอรีนั้น เช่น
    mkdir ~/php-oauth2-example
    cd ~/php-oauth2-example
  3. ติดตั้งไลบรารีของไคลเอ็นต์ Google API สําหรับ PHP โดยใช้ Composer ดังนี้
    composer require google/apiclient:^2.10
  4. สร้างไฟล์ index.php และ oauth2callback.php ที่มีเนื้อหาด้านล่าง
  5. เรียกใช้ตัวอย่างที่มีเว็บเซิร์ฟเวอร์ที่กําหนดค่าไว้เพื่อให้บริการ PHP หากใช้ PHP 5.6 หรือใหม่กว่า ให้ใช้เว็บเซิร์ฟเวอร์ทดสอบในตัวของ PHP&#39:
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

ตัวอย่างนี้ใช้เฟรมเวิร์ก Flask ซึ่งเรียกใช้เว็บแอปพลิเคชันที่ http://localhost:8080 ที่ช่วยให้คุณทดสอบขั้นตอน OAuth 2.0 หากไปที่ URL นั้น คุณจะเห็นลิงก์ 4 รายการ

  • ทดสอบคําขอ API: ลิงก์นี้ชี้ไปที่หน้าเว็บที่พยายามดําเนินการคําขอ API ตัวอย่าง หากจําเป็น ระบบจะเริ่มขั้นตอนการให้สิทธิ์ หากยืนยันสําเร็จ หน้าจะแสดงการตอบกลับของ API
  • ทดสอบขั้นตอนการตรวจสอบสิทธิ์โดยตรง: ลิงก์นี้ชี้ไปที่หน้าเว็บที่พยายามส่งผู้ใช้ผ่านขั้นตอนการให้สิทธิ์ แอปขอสิทธิ์ในการส่งคําขอ API ที่ได้รับอนุญาตในนามของผู้ใช้
  • เพิกถอนข้อมูลรับรองปัจจุบัน: ลิงก์นี้นําไปยังหน้าเว็บที่เพิกถอนสิทธิ์ที่ผู้ใช้ให้กับแอปพลิเคชันแล้ว
  • ล้างข้อมูลเข้าสู่ระบบของเซสชัน Flask: ลิงก์นี้จะล้างข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่เก็บไว้ในเซสชัน Flask ซึ่งจะช่วยให้คุณเห็นสิ่งที่จะเกิดขึ้นหากผู้ใช้ที่ให้สิทธิ์แอปของคุณอยู่แล้วพยายามดําเนินการตามคําขอ API ในเซสชันใหม่ นอกจากนี้ยังช่วยให้คุณเห็นการตอบกลับ API ที่แอปจะได้รับหากผู้ใช้เพิกถอนการให้สิทธิ์กับแอป และยังคงพยายามอนุมัติคําขอที่มีโทเค็นเพื่อการเข้าถึงที่เพิกถอนแล้ว
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

ตัวอย่างนี้ใช้เฟรมเวิร์ก Sinatra

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

วิธีเรียกใช้ตัวอย่างนี้

  1. ใน API Consoleให้เพิ่ม URL ของเครื่องในพื้นที่ไปยังรายการ URL เปลี่ยนเส้นทาง เช่น เพิ่ม http://localhost
  2. ตรวจสอบว่าคุณได้ติดตั้ง LTS, LTS ที่ใช้งานอยู่ หรือ Node.js ที่ติดตั้งอยู่ในปัจจุบัน
  3. สร้างไดเรกทอรีใหม่และเปลี่ยนเป็นไดเรกทอรีนั้น เช่น
    mkdir ~/nodejs-oauth2-example
    cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm:
    npm install googleapis
  5. สร้างไฟล์ main.js ที่มีเนื้อหาด้านล่าง
  6. เรียกใช้ตัวอย่าง:
    node .\main.js

Main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

ตัวอย่าง Python นี้ใช้เฟรมเวิร์ก Flask และไลบรารี คําขอ แสดงโฟลว์เว็บ OAuth 2.0 เราขอแนะนําให้ใช้ไลบรารีของไคลเอ็นต์ Google API สําหรับ Python สําหรับขั้นตอนนี้ (ตัวอย่างในแท็บ Python ใช้ไลบรารีของไคลเอ็นต์)

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

กฎการตรวจสอบ URI การเปลี่ยนเส้นทาง

Google ใช้กฎการตรวจสอบความถูกต้องต่อไปนี้ในการเปลี่ยนเส้นทาง URI เพื่อช่วยให้นักพัฒนาแอปรักษาความปลอดภัยของแอปพลิเคชัน URI การเปลี่ยนเส้นทางต้องเป็นไปตามกฎเหล่านี้ ดูคําจํากัดความของโดเมน 3986 ส่วน 3 ของโดเมน โฮสต์ เส้นทาง การค้นหา สคีม และข้อมูลผู้ใช้ ดังที่ระบุด้านล่าง

กฎการตรวจสอบความถูกต้อง
รูปแบบ

URI การเปลี่ยนเส้นทางต้องใช้รูปแบบ HTTPS ไม่ใช่ HTTP ธรรมดา URI ของ localhost (รวมถึง URI ของที่อยู่ IP ของ localhost) จะได้รับการยกเว้นจากกฎนี้

โฮสต์

โฮสต์เป็นที่อยู่ IP ดิบไม่ได้ ที่อยู่ IP ของ localhost จะได้รับการยกเว้นจากกฎนี้

โดเมน
  • TLD โฮสต์ (โดเมนระดับบนสุด) ต้องเป็นของรายการคําต่อท้ายสาธารณะ
  • โดเมนโฮสต์ต้องไม่ใช่ “googleusercontent.com”
  • URI การเปลี่ยนเส้นทางต้องไม่มีโดเมนที่ย่อ URL (เช่น goo.gl) เว้นแต่แอปจะเป็นเจ้าของโดเมน นอกจากนี้ หากแอปที่มีโดเมนสั้นกว่าเลือกที่จะเปลี่ยนเส้นทางไปยังโดเมนดังกล่าว URI การเปลี่ยนเส้นทางดังกล่าวต้องมี “/google-callback/” ในเส้นทางหรือลงท้ายด้วย “/google-callback”
  • ข้อมูลผู้ใช้

    URI การเปลี่ยนเส้นทางต้องไม่มีคอมโพเนนต์ย่อยของ userinfo

    เส้นทาง

    URI การเปลี่ยนเส้นทางต้องไม่มีการข้ามผ่านเส้นทาง (หรือเรียกว่า Backback Directory) ซึ่งนําเสนอโดย “/..” หรือ “\..” หรือการเข้ารหัส URL

    การค้นหา

    URI การเปลี่ยนเส้นทางต้องไม่มีการเปลี่ยนเส้นทางแบบเปิด

    ส่วนย่อย

    URI การเปลี่ยนเส้นทางต้องไม่มีคอมโพเนนต์ส่วนย่อย

    อักขระ URI การเปลี่ยนเส้นทางต้องไม่มีอักขระต่อไปนี้
    • อักขระไวลด์การ์ด ('*')
    • อักขระ ASCII ที่พิมพ์ไม่ได้
    • การเข้ารหัสเปอร์เซ็นต์ไม่ถูกต้อง (การเข้ารหัสเปอร์เซ็นต์ที่ไม่สอดคล้องกับรูปแบบการเข้ารหัส URL ของเครื่องหมายเปอร์เซ็นต์ตามด้วยเลขฐานสิบหก 2 หลัก)
    • อักขระ Null (อักขระ NULL ที่เข้ารหัส เช่น %00, %C0%80)

    การให้สิทธิ์ที่เพิ่มขึ้น

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

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

    ในกรณีนี้ แอปอาจขอขอบเขต openid และ profile ในการลงชื่อเข้าใช้พื้นฐานเมื่อลงชื่อเข้าใช้ จากนั้นขอขอบเขต https://www.googleapis.com/auth/drive.file เมื่อถึงเวลาที่ส่งคําขอแรกเพื่อบันทึกมิกซ์

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

    กฎต่อไปนี้ใช้กับโทเค็นเพื่อการเข้าถึงที่ได้มาจากการให้สิทธิ์ที่เพิ่มขึ้น

    • คุณใช้โทเค็นเพื่อเข้าถึงทรัพยากรที่สอดคล้องกับขอบเขตใดๆ ที่รวมอยู่ในการให้สิทธิ์แบบรวมรูปแบบใหม่ได้
    • เมื่อใช้โทเค็นการรีเฟรชสําหรับการให้สิทธิ์แบบรวมเพื่อรับโทเค็นเพื่อการเข้าถึง โทเค็นเพื่อการเข้าถึงจะแสดงการให้สิทธิ์แบบรวมและใช้กับค่า scope ใดก็ได้ที่รวมอยู่ในการตอบกลับ
    • การให้สิทธิ์แบบรวมนี้รวมขอบเขตทั้งหมดที่ผู้ใช้ให้กับโปรเจ็กต์ API แม้ว่าจะขอไคลเอ็นต์จากไคลเอ็นต์อื่นก็ตาม ตัวอย่างเช่น หากผู้ใช้ให้สิทธิ์เข้าถึงขอบเขต 1 รายการโดยใช้ไคลเอ็นต์บนเดสก์ท็อปของแอปพลิเคชัน แล้วให้สิทธิ์อีกขอบเขตหนึ่งแก่แอปพลิเคชันเดียวกันผ่านไคลเอ็นต์ในอุปกรณ์เคลื่อนที่ การให้สิทธิ์แบบรวมจะมีขอบเขตทั้งสองประเภท
    • หากคุณเพิกถอนโทเค็นที่แสดงถึงการให้สิทธิ์แบบรวม การเข้าถึงขอบเขต การให้สิทธิ์ทั้งหมดในนามของผู้ใช้ที่เกี่ยวข้องจะถูกเพิกถอนพร้อมกัน

    ตัวอย่างโค้ดเฉพาะภาษาในขั้นตอนที่ 1: ตั้งค่าพารามิเตอร์การให้สิทธิ์และตัวอย่าง URL การเปลี่ยนเส้นทาง HTTP/REST ในขั้นตอนที่ 2: เปลี่ยนเส้นทางไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ทั้งหมดใช้การให้สิทธิ์เพิ่มเติม ตัวอย่างโค้ดด้านล่างแสดงโค้ดที่คุณต้องเพิ่มเพื่อใช้การให้สิทธิ์ที่เพิ่มขึ้นด้วย

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

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

    authorization_url, state = flow.authorization_url(
        # Enable offline access so that you can refresh an access token without
        # re-prompting the user for permission. Recommended for web server apps.
        access_type='offline',
        # Enable incremental authorization. Recommended as a best practice.
        include_granted_scopes='true')

    Ruby

    auth_client.update!(
      :additional_parameters => {"include_granted_scopes" => "true"}
    )

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true
    });
    

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
      client_id=your_client_id&
      response_type=code&
      state=state_parameter_passthrough_value&
      scope=https%3A//www.googleapis.com/auth/drive.file&
      redirect_uri=https%3A//oauth2.example.com/code&
      prompt=consent&
      include_granted_scopes=true

    การรีเฟรชโทเค็นเพื่อการเข้าถึง (การเข้าถึงแบบออฟไลน์)

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

    • หากคุณใช้ไลบรารีของไคลเอ็นต์ Google API ออบเจ็กต์ไคลเอ็นต์จะรีเฟรชโทเค็นเพื่อการเข้าถึงตามที่จําเป็น ตราบใดที่คุณกําหนดค่าออบเจ็กต์นั้นสําหรับการเข้าถึงแบบออฟไลน์
    • หากไม่ได้ใช้ไลบรารีของไคลเอ็นต์ คุณต้องตั้งค่าพารามิเตอร์การค้นหา HTTP access_type เป็น offline เมื่อเปลี่ยนเส้นทางผู้ใช้ไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ในกรณีนี้ เซิร์ฟเวอร์การให้สิทธิ์ของ Google จะแสดงโทเค็นการรีเฟรชเมื่อคุณแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึง จากนั้น หากโทเค็นเพื่อการเข้าถึงหมดอายุ (หรือเวลาอื่น) คุณใช้โทเค็นการรีเฟรชเพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ได้

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

    เว็บแอปพลิเคชันฝั่งเซิร์ฟเวอร์ แอปพลิเคชันที่ติดตั้งไว้ และอุปกรณ์ทั้งหมดจะได้รับโทเค็นการรีเฟรชระหว่างขั้นตอนการให้สิทธิ์ โดยทั่วไปโทเค็นการรีเฟรชจะไม่ใช้ในเว็บแอปพลิเคชันฝั่งไคลเอ็นต์ (JavaScript)

    PHP

    หากแอปพลิเคชันของคุณต้องการการเข้าถึง Google API แบบออฟไลน์ ให้ตั้งค่าประเภทการเข้าถึงไคลเอ็นต์ API เป็น offline:

    $client->setAccessType("offline");

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

    Python

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

    authorization_url, state = flow.authorization_url(
        # Enable offline access so that you can refresh an access token without
        # re-prompting the user for permission. Recommended for web server apps.
        access_type='offline',
        # Enable incremental authorization. Recommended as a best practice.
        include_granted_scopes='true')

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

    Ruby

    หากแอปพลิเคชันของคุณต้องการการเข้าถึง Google API แบบออฟไลน์ ให้ตั้งค่าประเภทการเข้าถึงไคลเอ็นต์ API เป็น offline:

    auth_client.update!(
      :additional_parameters => {"access_type" => "offline"}
    )

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

    Node.js

    หากแอปพลิเคชันของคุณต้องการการเข้าถึง Google API แบบออฟไลน์ ให้ตั้งค่าประเภทการเข้าถึงไคลเอ็นต์ API เป็น offline:

    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true
    });
    

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

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

    oauth2Client.on('tokens', (tokens) => {
      if (tokens.refresh_token) {
        // store the refresh_token in your secure persistent database
        console.log(tokens.refresh_token);
      }
      console.log(tokens.access_token);
    });

    เหตุการณ์โทเค็นนี้จะเกิดขึ้นในการให้สิทธิ์ครั้งแรกเท่านั้น และคุณจะต้องตั้งค่า access_type เป็น offline เมื่อเรียกใช้เมธอด generateAuthUrl เพื่อรับโทเค็นการรีเฟรช หากคุณให้สิทธิ์แอปแล้ว โดยไม่มีข้อจํากัดที่เหมาะสมในการรับโทเค็นการรีเฟรช คุณจะต้องให้สิทธิ์แอปพลิเคชันอีกครั้งเพื่อรับโทเค็นการรีเฟรชใหม่

    หากต้องการตั้งค่า refresh_token ในภายหลัง ให้ใช้เมธอด setCredentials ดังนี้

    oauth2Client.setCredentials({
      refresh_token: `STORED_REFRESH_TOKEN`
    });
    

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

    HTTP/REST

    หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันของคุณจะส่งคําขอ HTTPS POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google (https://oauth2.googleapis.com/token) ที่มีพารามิเตอร์ต่อไปนี้

    ช่อง
    client_id รหัสไคลเอ็นต์ที่ได้รับจาก API Console
    client_secret รหัสลับไคลเอ็นต์ที่ได้จาก API Console
    grant_type ตามที่ระบุในข้อมูลจําเพาะของ OAuth 2.0 ช่องนี้ต้องตั้งค่าเป็น refresh_token
    refresh_token โทเค็นการรีเฟรชที่ส่งคืนจากการแลกเปลี่ยนรหัสการให้สิทธิ์

    ข้อมูลโค้ดต่อไปนี้แสดงคําขอตัวอย่าง

    POST /token HTTP/1.1
    Host: oauth2.googleapis.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=your_client_id&
    client_secret=your_client_secret&
    refresh_token=refresh_token&
    grant_type=refresh_token

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

    {
      "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
      "expires_in": 3920,
      "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
      "token_type": "Bearer"
    }

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

    กําลังเพิกถอนโทเค็น

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

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

    PHP

    หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม ให้เรียกใช้ revokeToken()

    $client->revokeToken();

    Python

    หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม ให้ส่งคําขอไปยัง https://oauth2.googleapis.com/revoke ที่มีโทเค็นเป็นพารามิเตอร์ และตั้งค่าส่วนหัว Content-Type ดังต่อไปนี้

    requests.post('https://oauth2.googleapis.com/revoke',
        params={'token': credentials.token},
        headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม ให้ส่งคําขอ HTTP ไปยังปลายทาง oauth2.revoke โดยทําดังนี้

    uri = URI('https://oauth2.googleapis.com/revoke')
    response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)
    

    โดยโทเค็นอาจเป็นโทเค็นเพื่อการเข้าถึงหรือโทเค็นการรีเฟรชก็ได้ หากโทเค็นเป็นโทเค็นเพื่อการเข้าถึงและมีโทเค็นการรีเฟรชที่สอดคล้องกัน ระบบจะเพิกถอนโทเค็นการรีเฟรชด้วย

    หากดําเนินการเพิกถอนเรียบร้อยแล้ว รหัสสถานะของการตอบกลับจะเป็น 200 สําหรับเงื่อนไขข้อผิดพลาด ระบบจะแสดงรหัสสถานะ 400 พร้อมกับรหัสข้อผิดพลาด

    Node.js

    หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม ให้ส่งคําขอ HTTPS POST ไปยังปลายทาง /revoke ดังนี้

    const https = require('https');
    
    // Build the string for the POST request
    let postData = "token=" + userCredential.access_token;
    
    // Options for POST request to Google's OAuth 2.0 server to revoke a token
    let postOptions = {
      host: 'oauth2.googleapis.com',
      port: '443',
      path: '/revoke',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData)
      }
    };
    
    // Set up the request
    const postReq = https.request(postOptions, function (res) {
      res.setEncoding('utf8');
      res.on('data', d => {
        console.log('Response: ' + d);
      });
    });
    
    postReq.on('error', error => {
      console.log(error)
    });
    
    // Post the request with data
    postReq.write(postData);
    postReq.end();
    

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

    หากดําเนินการเพิกถอนเรียบร้อยแล้ว รหัสสถานะของการตอบกลับจะเป็น 200 สําหรับเงื่อนไขข้อผิดพลาด ระบบจะแสดงรหัสสถานะ 400 พร้อมกับรหัสข้อผิดพลาด

    HTTP/REST

    หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม แอปพลิเคชันจะส่งคําขอไปยัง https://oauth2.googleapis.com/revoke และมีโทเค็นเป็นพารามิเตอร์

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
            https://oauth2.googleapis.com/revoke?token={token}

    โดยโทเค็นอาจเป็นโทเค็นเพื่อการเข้าถึงหรือโทเค็นการรีเฟรชก็ได้ หากโทเค็นเป็นโทเค็นเพื่อการเข้าถึงและมีโทเค็นการรีเฟรชที่สอดคล้องกัน ระบบจะเพิกถอนโทเค็นการรีเฟรชด้วย

    หากการเพิกถอนประมวลผลสําเร็จ รหัสสถานะ HTTP ของการตอบกลับจะเป็น 200 สําหรับสถานะข้อผิดพลาด ระบบจะส่งรหัสสถานะ HTTP 400 ไปพร้อมกับรหัสข้อผิดพลาด