เอกสารนี้อธิบายวิธีใช้การให้สิทธิ์ 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 สำหรับโปรเจ็กต์
- Open the API Library ใน Google API Console
- If prompted, select a project, or create a new one.
- API Library แสดงรายการ API ที่ใช้ได้ทั้งหมดโดยจัดกลุ่มตามผลิตภัณฑ์ ครอบครัว และความนิยม หากไม่เห็น API ที่ต้องการเปิดใช้ในรายการ ให้ใช้การค้นหาเพื่อ หากต้องการค้นหารหัสดังกล่าว หรือคลิกดูทั้งหมดในกลุ่มผลิตภัณฑ์นั้น
- เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
สร้างข้อมูลเข้าสู่ระบบการให้สิทธิ์
แอปพลิเคชันที่ใช้ OAuth 2.0 เพื่อเข้าถึง Google API จะต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google ขั้นตอนต่อไปนี้จะอธิบายถึงวิธีการ สร้างข้อมูลเข้าสู่ระบบสำหรับโปรเจ็กต์ จากนั้นแอปพลิเคชันของคุณสามารถใช้ข้อมูลรับรองเพื่อเข้าถึง API ที่คุณเปิดใช้สำหรับโปรเจ็กต์นั้น
- Go to the Credentials page.
- คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
- เลือกประเภทแอปพลิเคชันทีวีและอุปกรณ์อินพุตแบบจำกัด
- ตั้งชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิกสร้าง
ระบุขอบเขตการเข้าถึง
ขอบเขตช่วยให้แอปพลิเคชันสามารถขอเข้าถึงเฉพาะทรัพยากรที่จำเป็นต้องใช้ และ ทำให้ผู้ใช้สามารถควบคุมปริมาณการเข้าถึงที่จะมอบให้กับแอปพลิเคชันของคุณได้ ดังนั้นจึงมี อาจเป็นความสัมพันธ์แบบผกผันระหว่างจำนวนขอบเขตที่ขอกับแนวโน้ม การขอความยินยอมจากผู้ใช้
ก่อนที่จะเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนำให้คุณระบุขอบเขต ที่แอปของคุณจะต้องมีสิทธิ์เข้าถึง
ดูรายการขอบเขตที่อนุญาตสำหรับแอปหรืออุปกรณ์ที่ติดตั้งไว้
การได้รับโทเค็นเพื่อการเข้าถึง OAuth 2.0
แม้ว่าแอปพลิเคชันของคุณจะทำงานบนอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่จำกัด แต่ผู้ใช้ต้องมี การเข้าถึงแยกต่างหากสำหรับอุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ยิ่งขึ้นเพื่อให้ขั้นตอนการให้สิทธิ์นี้เสร็จสมบูรณ์ ขั้นตอนนี้มีขั้นตอนดังนี้
- แอปพลิเคชันของคุณจะส่งคำขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ระบุขอบเขต ที่แอปพลิเคชันจะขอสิทธิ์ในการเข้าถึง
- เซิร์ฟเวอร์จะตอบกลับด้วยข้อมูลหลายอย่างที่ใช้ในขั้นตอนถัดไป เช่น รหัสอุปกรณ์และรหัสผู้ใช้
- คุณสามารถแสดงข้อมูลที่ผู้ใช้สามารถป้อนในอุปกรณ์อีกเครื่องหนึ่งเพื่อให้สิทธิ์ แอป
- แอปพลิเคชันของคุณจะเริ่มสำรวจเซิร์ฟเวอร์การให้สิทธิ์ของ Google เพื่อดูว่าผู้ใช้ ให้สิทธิ์แอปของคุณแล้ว
- ผู้ใช้จะเปลี่ยนไปใช้อุปกรณ์ที่มีความสามารถในการป้อนข้อมูลที่สมบูรณ์ขึ้น เปิดใช้เว็บเบราว์เซอร์ ไปที่ URL ที่แสดงในขั้นตอนที่ 3 และป้อนรหัสที่แสดงในขั้นตอนที่ 3 ด้วย จากนั้นผู้ใช้สามารถให้ (หรือปฏิเสธ) สิทธิ์การเข้าถึงแอปพลิเคชันของคุณได้
- การตอบกลับถัดไปสำหรับคำขอแบบสำรวจจะมีโทเค็นที่แอปของคุณต้องให้สิทธิ์ ในนามของผู้ใช้ (หากผู้ใช้ปฏิเสธการเข้าถึงแอปพลิเคชันของคุณ การตอบกลับ ไม่มีโทเค็น)
รูปภาพด้านล่างแสดงขั้นตอนนี้
![ผู้ใช้เข้าสู่ระบบในอุปกรณ์อีกเครื่องหนึ่งที่มีเบราว์เซอร์](https://developers.google.cn/static/identity/protocols/images/oauth2/device/flow.png?authuser=9&hl=th)
ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้โดยละเอียด เมื่อพิจารณาถึงความสามารถและรันไทม์ที่หลากหลาย
สภาพแวดล้อมที่อุปกรณ์อาจมี ตัวอย่างที่แสดงในเอกสารนี้ใช้ 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
- พื้นที่ที่คุณแสดง
ขั้นตอนที่ 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:
![เชื่อมต่ออุปกรณ์ด้วยการป้อนรหัส](https://developers.google.cn/static/identity/protocols/images/oauth2/device/user-code.png?authuser=9&hl=th)
หลังจากป้อน user_code
และหากยังไม่ได้เข้าสู่ระบบ ให้เข้าสู่ระบบ Google
ผู้ใช้เห็นหน้าจอขอความยินยอมดังที่แสดงด้านล่าง
![ตัวอย่างหน้าจอขอความยินยอมสำหรับไคลเอ็นต์อุปกรณ์](https://developers.google.cn/static/identity/protocols/images/oauth2/device/approval.png?authuser=9&hl=th)
ขั้นตอนที่ 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 ตัวอย่างเช่น ข้อผิดพลาดนี้เกิดขึ้นหาก
ค่าพารามิเตอร์ ประเภทไคลเอ็นต์ 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
โปรดดู ปกป้องบัญชีผู้ใช้ด้วยหน้าการป้องกันแบบครอบคลุมหลายบริการ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้การป้องกันแบบครอบคลุมหลายบริการและรายการเหตุการณ์ทั้งหมดที่มี