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

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

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

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

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

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

เอกสารขอบเขต 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=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 API

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

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

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

หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันจะส่งคําขอ POST แบบ HTTPS ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ 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 สําหรับแอปที่มาพร้อมเครื่องมีแนวทางปฏิบัติแนะนํามากมายที่บันทึกไว้ในส่วนนี้