OAuth 2.0 สำหรับทีวีและแอปพลิเคชันอุปกรณ์ที่มีอินพุตที่จำกัด

หมายเหตุสำคัญ: ขั้นตอน OAuth 2.0 นี้รองรับ ชุดขอบเขตที่จำกัด

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

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

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

ตัวเลือกอื่นๆ

หากคุณเขียนแอปสำหรับแพลตฟอร์ม เช่น Android, iOS, macOS, Linux หรือ Windows (รวมถึง Universal Windows Platform) ที่มีสิทธิ์เข้าถึงเบราว์เซอร์และการป้อนข้อมูลเต็มรูปแบบ ให้ใช้ขั้นตอน OAuth 2.0 สำหรับอุปกรณ์เคลื่อนที่ และแอปพลิเคชันบนเดสก์ท็อป (คุณควรใช้ขั้นตอนดังกล่าวแม้ว่าแอปของคุณจะเป็นบรรทัดคำสั่ง เครื่องมือที่ไม่มีอินเทอร์เฟซแบบกราฟิก)

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

ข้อกำหนดเบื้องต้น

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

แอปพลิเคชันใดๆ ที่เรียกใช้ Google APIs จำเป็นต้องเปิดใช้ 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. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
3. เลือกประเภทแอปพลิเคชันทีวีและอุปกรณ์อินพุตแบบจำกัด
4. ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิกสร้าง

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

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

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

หมายเหตุ: แอปที่ติดตั้งไม่รองรับหรือ อุปกรณ์

ดูรายการขอบเขตที่อนุญาตสำหรับแอปหรืออุปกรณ์ที่ติดตั้งไว้

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

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

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

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

รูปภาพด้านล่างแสดงขั้นตอนนี้

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

ขั้นตอนที่ 1: ขอรหัสอุปกรณ์และผู้ใช้

ในขั้นตอนนี้ อุปกรณ์ของคุณจะส่งคำขอ HTTP POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ https://oauth2.googleapis.com/device/code ที่ระบุแอปพลิเคชันของคุณ รวมทั้งขอบเขตการเข้าถึงที่แอปพลิเคชันของคุณต้องการเข้าถึงในนามของผู้ใช้ คุณควรดึงข้อมูล URL นี้จาก เอกสารการค้นพบโดยใช้พารามิเตอร์ ค่าข้อมูลเมตา device_authorization_endpoint รวมคำขอ HTTP ต่อไปนี้ ได้แก่

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

ตัวอย่าง

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

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

client_id=client_id&scope=email%20profile

ตัวอย่างนี้แสดงคำสั่ง curl เพื่อส่งคำขอเดียวกัน

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

ขั้นตอนที่ 2: จัดการการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์

เซิร์ฟเวอร์การให้สิทธิ์จะแสดงการตอบกลับอย่างใดอย่างหนึ่งต่อไปนี้

การตอบกลับว่าสำเร็จ

หากคำขอถูกต้อง การตอบกลับของคุณจะเป็นออบเจ็กต์ JSON ที่มีข้อมูลต่อไปนี้ พร็อพเพอร์ตี้:

พร็อพเพอร์ตี้
device_code	ค่าที่ Google กำหนดโดยไม่ซ้ำกันเพื่อระบุอุปกรณ์ที่เรียกใช้แอปที่ขอ การกันวงเงิน ผู้ใช้จะให้สิทธิ์อุปกรณ์นั้นจากอุปกรณ์อื่นที่มีความสมบูรณ์ยิ่งขึ้น ในการป้อนข้อมูล เช่น ผู้ใช้อาจใช้แล็ปท็อปหรือโทรศัพท์มือถือเพื่อให้สิทธิ์ ที่ทำงานบนทีวี ในกรณีนี้ device_code จะระบุทีวี โค้ดนี้ช่วยให้อุปกรณ์ที่เรียกใช้แอประบุได้อย่างปลอดภัยว่าผู้ใช้ได้ให้สิทธิ์ หรือปฏิเสธการเข้าถึง
expires_in	ระยะเวลาเป็นวินาทีที่ device_code และ user_code ถูกต้อง ในช่วงเวลาดังกล่าว หากผู้ใช้ไม่ได้ดำเนินการ ขั้นตอนการให้สิทธิ์และอุปกรณ์ของคุณไม่ได้ทำแบบสำรวจเพื่อดึงข้อมูลเกี่ยวกับ ที่ผู้ใช้ตัดสินใจ คุณอาจต้องเริ่มขั้นตอนนี้ใหม่ตั้งแต่ขั้นตอนที่ 1
interval	ระยะเวลาเป็นวินาทีที่อุปกรณ์ควรรอระหว่างคำขอแบบสำรวจ สำหรับ เช่น หากค่าคือ 5 อุปกรณ์ควรส่งคำขอแบบสำรวจไปยัง เซิร์ฟเวอร์การให้สิทธิ์ของ Google ทุก 5 วินาที โปรดดู ขั้นตอนที่ 3 เพื่อดูรายละเอียดเพิ่มเติม
user_code	ค่าที่พิจารณาตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ที่ระบุขอบเขตของแอปพลิเคชันให้ Google ทราบ ที่ขอสิทธิ์การเข้าถึง อินเทอร์เฟซผู้ใช้จะแจ้งให้ผู้ใช้ป้อนค่านี้ใน อุปกรณ์แยกกันที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้น จากนั้น Google จะใช้ค่านี้เพื่อแสดง ชุดขอบเขตที่ถูกต้องเมื่อแสดงข้อความแจ้งให้ผู้ใช้ให้สิทธิ์เข้าถึงแอปพลิเคชันของคุณ
verification_url	URL ที่ผู้ใช้ต้องเข้าไปในอุปกรณ์อีกเครื่องหนึ่งเพื่อป้อน user_code และให้สิทธิ์หรือปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ อินเทอร์เฟซผู้ใช้ของคุณ จะแสดงค่านี้ด้วย

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

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

การตอบกลับเกินโควต้า

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

{
  "error_code": "rate_limit_exceeded"
}

ในกรณีดังกล่าว ให้ใช้กลยุทธ์ Backoff เพื่อลดอัตราคำขอ

ขั้นตอนที่ 3: แสดงรหัสผู้ใช้

แสดง verification_url และ user_code ที่ได้รับจากขั้นตอนที่ 2 ไปยัง ผู้ใช้ ทั้งสองค่าสามารถมีอักขระที่พิมพ์ได้จากชุดอักขระ US-ASCII เนื้อหา ที่คุณแสดงต่อผู้ใช้ควรแนะนำให้ผู้ใช้ไปที่ verification_url ในอุปกรณ์แยกต่างหาก แล้วป้อนuser_code

ออกแบบอินเทอร์เฟซผู้ใช้ (UI) โดยคำนึงถึงกฎต่อไปนี้

• user_code
  • user_code ต้องแสดงในช่องที่รับ 15 "W" ได้ ขนาด อักขระ กล่าวคือ หากคุณแสดงรหัส WWWWWWWWWWWWWWW ได้ UI ของคุณใช้งานได้ และเราขอแนะนำให้ใช้ค่าสตริงนั้นเมื่อทดสอบวิธีการ user_code จะแสดงใน UI ของคุณ
  • user_code จะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ และไม่ควรแก้ไขไม่ว่าในลักษณะใดก็ตาม เช่น เช่น การเปลี่ยนตัวพิมพ์เล็กใหญ่ หรือการแทรกอักขระการจัดรูปแบบอื่นๆ
• verification_url
  • พื้นที่ที่คุณแสดง verification_url ต้องกว้างพอที่จะ จัดการสตริง URL ที่มีความยาว 40 อักขระ
  • คุณไม่ควรแก้ไข verification_url ไม่ว่าด้วยวิธีใด เว้นแต่จะเลือกได้ นำรูปแบบในการแสดงออก หากคุณวางแผนที่จะยกเลิกแผนการ (เช่น https://) จาก URL ด้วยเหตุผลในการแสดง โปรดตรวจสอบว่าแอปของคุณสามารถจัดการได้ ทั้งตัวแปร http และ https

คำเตือน: ทั้ง 2 ค่านี้อาจมีการเปลี่ยนแปลง และคุณควร ไม่ใช่ฮาร์ดโค้ดค่าใดค่าหนึ่งในโค้ดของคุณ ในทำนองเดียวกัน คุณไม่ควรแก้ไขค่าไม่ว่าในลักษณะใด นอกเหนือจากการเลือกนำรูปแบบออกจาก verification_url

ขั้นตอนที่ 4: สำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google

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

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

URL ของปลายทางสำหรับแบบสำรวจคือ https://oauth2.googleapis.com/token คำขอในแบบสำรวจ มีพารามิเตอร์ต่อไปนี้

พารามิเตอร์
client_id	รหัสไคลเอ็นต์สำหรับแอปพลิเคชันของคุณ คุณสามารถค้นหาค่านี้ใน API Console Credentials page
client_secret	รหัสลับไคลเอ็นต์สำหรับ client_id ที่ระบุ คุณสามารถค้นหาค่านี้ใน API Console Credentials page
device_code	device_code แสดงผลโดยเซิร์ฟเวอร์การให้สิทธิ์ใน ขั้นตอนที่ 2
grant_type	ตั้งค่านี้เป็น urn:ietf:params:oauth:grant-type:device_code

ตัวอย่าง

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

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

ตัวอย่างนี้แสดงคำสั่ง curl เพื่อส่งคำขอเดียวกัน

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

ขั้นตอนที่ 5: ผู้ใช้ตอบกลับคำขอสิทธิ์เข้าถึง

หมายเหตุ: การสมัครคุณไม่จำเป็นต้องดำเนินการใดๆ ในขั้นตอนนี้ สอบถามเซิร์ฟเวอร์การให้สิทธิ์ตามที่อธิบายไว้ในขั้นตอนก่อนหน้า

รูปภาพต่อไปนี้แสดงหน้าเว็บที่คล้ายกับสิ่งที่ผู้ใช้เห็นเมื่อไปยัง verification_urlที่แสดงในขั้นตอนที่ 3:

หลังจากป้อน user_code และหากยังไม่ได้เข้าสู่ระบบ ให้เข้าสู่ระบบ Google ผู้ใช้เห็นหน้าจอขอความยินยอมดังที่แสดงด้านล่าง

ขั้นตอนที่ 6: จัดการการตอบกลับคำขอแบบสำรวจ

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

ให้สิทธิ์เข้าถึงแล้ว

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

ในกรณีนี้ การตอบกลับ API จะมีช่องต่อไปนี้

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

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

การเข้าถึงถูกปฏิเสธ

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

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

รอการให้สิทธิ์

ถ้าผู้ใช้ยังดำเนินการให้สิทธิ์ไม่เสร็จ เซิร์ฟเวอร์จะส่งกลับ รหัสสถานะการตอบกลับ HTTP 428 (Precondition Required) คำตอบ มีข้อผิดพลาดต่อไปนี้

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

ทำแบบสำรวจบ่อยเกินไป

หากอุปกรณ์ส่งคำขอแบบสำรวจบ่อยเกินไป เซิร์ฟเวอร์จะแสดงผล 403 รหัสสถานะการตอบกลับ HTTP (Forbidden) คำตอบจะมีข้อมูลต่อไปนี้ ข้อผิดพลาด:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

ข้อผิดพลาดอื่นๆ

เซิร์ฟเวอร์การให้สิทธิ์จะแสดงข้อผิดพลาดด้วย หากคำขอในการหยั่งสัญญาณขาดหายไป หรือมีค่าพารามิเตอร์ไม่ถูกต้อง ตามปกติคำขอเหล่านี้จะมี 400 (Bad Request) หรือสถานะการตอบกลับ HTTP ของ 401 (Unauthorized) โค้ด ข้อผิดพลาดดังกล่าว ได้แก่

ข้อผิดพลาด	รหัสสถานะ HTTP	คำอธิบาย
admin_policy_enforced	400	บัญชี Google ให้สิทธิ์ขอบเขตที่ขออย่างน้อย 1 ขอบเขตไม่ได้เนื่องจาก นโยบายของผู้ดูแลระบบ Google Workspace ดูความช่วยเหลือสำหรับผู้ดูแลระบบ Google Workspace บทความควบคุมว่าจะให้บุคคลที่สาม แอปภายในเข้าถึงข้อมูล Google Workspace เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ ผู้ดูแลระบบอาจจำกัดสิทธิ์เข้าถึงขอบเขตจนกว่าจะมีการให้สิทธิ์เข้าถึง OAuth ของคุณอย่างชัดเจน รหัสไคลเอ็นต์
invalid_client	401	ไม่พบไคลเอ็นต์ OAuth ตัวอย่างเช่น ข้อผิดพลาดนี้เกิดขึ้นหาก ค่าพารามิเตอร์ client_id ไม่ถูกต้อง ประเภทไคลเอ็นต์ OAuth ไม่ถูกต้อง ตรวจสอบว่า ประเภทแอปพลิเคชัน สำหรับรหัสไคลเอ็นต์จะมีการตั้งค่าเป็นทีวีและอุปกรณ์อินพุตที่จำกัด
invalid_grant	400	ค่าพารามิเตอร์ code ไม่ถูกต้อง มีการอ้างสิทธิ์แล้ว หรือไม่สามารถอ้างสิทธิ์ได้ แยกวิเคราะห์แล้ว
unsupported_grant_type	400	ค่าพารามิเตอร์ grant_type ไม่ถูกต้อง
org_internal	403	รหัสไคลเอ็นต์ OAuth ในคำขอเป็นส่วนหนึ่งของโปรเจ็กต์ที่จำกัดการเข้าถึงบัญชี Google ใน Google Cloud Organization ยืนยัน ประเภทผู้ใช้ สำหรับแอปพลิเคชัน OAuth

การเรียกใช้ Google APIs

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

คุณสามารถทดลองใช้ Google API ทั้งหมดและดูขอบเขตของ 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

การรีเฟรชโทเค็นเพื่อการเข้าถึง

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

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

การเพิกถอนโทเค็น

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

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

หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม แอปพลิเคชันของคุณจะส่งคำขอไปยัง 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 กลับมา ที่มีรหัสข้อผิดพลาด

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

ขอบเขตที่อนุญาต

ขั้นตอน OAuth 2.0 สำหรับอุปกรณ์รองรับเฉพาะขอบเขตต่อไปนี้

OpenID Connect, Google Sign-In

• email
• openid
• profile

API ไดรฟ์

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

API ของ YouTube

• https://www.googleapis.com/auth/youtube
• https://www.googleapis.com/auth/youtube.readonly

การใช้การป้องกันแบบครอบคลุมหลายบริการ

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

ตัวอย่างประเภทเหตุการณ์ที่บริการการป้องกันแบบครอบคลุมหลายบริการของ Google ส่งไปยังแอปของคุณ ได้แก่

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

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