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

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

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

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

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

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

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

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

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

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

• ไลบรารี AppAuth สำหรับ Android
• ไลบรารี AppAuth สำหรับ iOS
• OAuth สำหรับ Apps: Windows ฟีดลองฟัง

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

เปิดใช้ 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. ส่วนด้านล่างนี้อธิบายประเภทไคลเอ็นต์และวิธีการเปลี่ยนเส้นทางที่ รองรับเซิร์ฟเวอร์การให้สิทธิ์ เลือกประเภทไคลเอ็นต์ที่แนะนำสำหรับ แอปพลิเคชัน ให้ตั้งชื่อไคลเอ็นต์ OAuth และตั้งค่าช่องอื่นๆ ในแบบฟอร์มเป็น เหมาะสม

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

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

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

เอกสารขอบเขต API ของ OAuth 2.0 จะมีข้อมูลแบบเต็ม รายการขอบเขตที่คุณอาจใช้เพื่อเข้าถึง Google APIs

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

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

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

Google รองรับคีย์พิสูจน์สำหรับการแลกเปลี่ยนโค้ด (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=email%20profile&
 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=email%20profile&
 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/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

การเรียกใช้ 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) ซึ่ง ประกอบด้วยพารามิเตอร์ต่อไปนี้

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

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 กลับมา ที่มีรหัสข้อผิดพลาด

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

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