OAuth 2.0 สำหรับแอปบนอุปกรณ์เคลื่อนที่และเดสก์ท็อป

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

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

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

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

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

สำหรับแอปบนอุปกรณ์เคลื่อนที่ คุณอาจต้องการใช้ Google Sign-In สำหรับ Android หรือ iOS ไลบรารีของไคลเอ็นต์ Google Sign-In จะจัดการการตรวจสอบสิทธิ์และการให้สิทธิ์ผู้ใช้ และอาจนำไปใช้ได้ง่ายกว่าโปรโตคอลระดับต่ำกว่าที่อธิบายไว้ ณ ที่นี้

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

ห้องสมุดและตัวอย่าง

ขอแนะนำให้ใช้ไลบรารีและตัวอย่างต่อไปนี้เพื่อช่วยคุณใช้งานขั้นตอน OAuth 2.0 ที่อธิบายไว้ในเอกสารนี้

• ไลบรารี AppAuth สำหรับ Android
• ไลบรารี AppAuth สำหรับ iOS
• OAuth สำหรับแอป: ตัวอย่าง Windows

สิ่งที่ต้องดำเนินการก่อน

เปิดใช้ 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. ใช้หน้าคลังเพื่อค้นหาและเปิดใช้ YouTube Data API ค้นหา API อื่นๆ ที่แอปพลิเคชันจะใช้และเปิดใช้ API เหล่านั้นด้วย

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

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

1. Go to the Credentials page.
2. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
3. ส่วนด้านล่างจะอธิบายประเภทไคลเอ็นต์และวิธีการเปลี่ยนเส้นทางที่เซิร์ฟเวอร์การให้สิทธิ์ของ Google รองรับ เลือกประเภทไคลเอ็นต์ที่แนะนำสำหรับแอปพลิเคชัน ตั้งชื่อไคลเอ็นต์ OAuth และตั้งค่าช่องอื่นๆ ในแบบฟอร์มตามความเหมาะสม

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

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

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

YouTube Data API v3 ใช้ขอบเขตต่อไปนี้

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

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

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

ขั้นตอนที่ 1: สร้างตัวตรวจสอบโค้ดและการยืนยันตัวตน

Google รองรับโปรโตคอล Proof Key for Code Exchange (PKCE) เพื่อให้โฟลว์แอปที่ติดตั้งมีความปลอดภัยยิ่งขึ้น ระบบจะสร้างตัวตรวจสอบโค้ดที่ไม่ซ้ำกันขึ้นสำหรับคำขอการให้สิทธิ์ทั้งหมด และจะมีการส่งค่าที่เปลี่ยนรูปแบบแล้วซึ่งเรียกว่า "code_challenge" ไปยังเซิร์ฟเวอร์การให้สิทธิ์เพื่อรับรหัสการให้สิทธิ์

สร้างตัวตรวจสอบโค้ด

code_verifier เป็นสตริงแบบสุ่มการเข้ารหัสที่มีเอนโทรปีสูงโดยใช้อักขระที่ไม่ได้สงวนไว้ [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" โดยมีความยาวขั้นต่ำ 43 อักขระและมีความยาวได้สูงสุด 128 อักขระ

ตัวตรวจสอบโค้ดควรมีเอนโทรปีเพียงพอที่จะทำให้ไม่สามารถคาดเดาค่าได้จริง

สร้างระบบทดสอบโค้ด

ระบบรองรับการทดสอบโค้ด 2 วิธีด้วยกัน

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

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

ในการรับการให้สิทธิ์จากผู้ใช้ ให้ส่งคำขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ https://accounts.google.com/o/oauth2/v2/auth ปลายทางนี้จัดการการค้นหาเซสชันที่ใช้งานอยู่ ตรวจสอบสิทธิ์ผู้ใช้ และขอความยินยอมจากผู้ใช้ ปลายทางจะเข้าถึงได้ผ่าน SSL เท่านั้น และปฏิเสธการเชื่อมต่อ HTTP (ไม่ใช่ SSL)

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

ตัวอย่าง URL การให้สิทธิ์

แท็บด้านล่างแสดงตัวอย่าง URL การให้สิทธิ์สำหรับตัวเลือก URI การเปลี่ยนเส้นทางต่างๆ

URL จะเหมือนกันยกเว้นค่าของพารามิเตอร์ redirect_uri URL ยังมีพารามิเตอร์ response_type และ client_id ที่จำเป็น รวมถึงพารามิเตอร์ state ที่ไม่บังคับด้วย โดย URL แต่ละรายการจะมีตัวแบ่งบรรทัดและการเว้นวรรคเพื่อให้อ่านง่ายขึ้น

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

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

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

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

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

ลักษณะที่แอปพลิเคชันของคุณได้รับการตอบกลับการให้สิทธิ์จะขึ้นอยู่กับรูปแบบ URI การเปลี่ยนเส้นทางที่แอปพลิเคชันใช้ ไม่ว่าจะเป็นรูปแบบใดก็ตาม การตอบกลับจะมีรหัสการให้สิทธิ์ (code) หรือข้อผิดพลาด (error) เช่น error=access_denied ระบุว่าผู้ใช้ปฏิเสธคำขอ

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

ขั้นตอนที่ 5: รหัสการให้สิทธิ์ของ Exchange สำหรับการรีเฟรชและโทเค็นเพื่อการเข้าถึง

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

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

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=http://127.0.0.1:9004&
grant_type=authorization_code

Google ตอบสนองต่อคำขอนี้โดยแสดงผลออบเจ็กต์ JSON ที่มีโทเค็นเพื่อการเข้าถึงที่มีอายุสั้นและโทเค็นการรีเฟรช

คำตอบจะมีช่องต่อไปนี้

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

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

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

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

โปรดทราบว่า YouTube Data API รองรับบัญชีบริการสำหรับเจ้าของเนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่องเท่านั้น เช่น ค่ายเพลงและสตูดิโอภาพยนตร์

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

ตัวอย่าง HTTP GET

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

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

หรือใช้ตัวเลือกพารามิเตอร์สตริงคำค้นหาดังนี้

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

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

หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันจะส่งคำขอ HTTPS POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google (https://oauth2.googleapis.com/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 เพื่อให้แน่ใจว่าสิทธิ์ที่เคยมอบให้แก่แอปพลิเคชันได้ถูกนำออกไปแล้ว

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

อ่านเพิ่มเติม

แนวทางปฏิบัติแนะนำในปัจจุบันของ IETF OAuth 2.0 สำหรับแอปที่มาพร้อมเครื่อง ได้กำหนดแนวทางปฏิบัติที่ดีที่สุดหลายข้อตามที่ระบุไว้ที่นี่