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 สําหรับแอป: ตัวอย่างสําหรับ 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 ที่ต้องการเปิดใช้ในรายการ ให้ใช้การค้นหาเพื่อค้นหา หรือคลิกดูทั้งหมดในตระกูลผลิตภัณฑ์ของ API นั้น
4. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

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

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

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

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

เอกสารขอบเขต OAuth 2.0 API มีรายการขอบเขตทั้งหมดที่คุณอาจใช้เพื่อเข้าถึง 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: เปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นรีเฟรชและโทเค็นการเข้าถึง

หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นการเข้าถึง ให้เรียกใช้ปลายทาง 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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

ขั้นตอนที่ 6: ตรวจสอบขอบเขตที่ผู้ใช้ให้สิทธิ์

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

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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

หลังจากแอปพลิเคชันได้รับโทเค็นการเข้าถึงแล้ว คุณจะใช้โทเค็นดังกล่าวเพื่อเรียกใช้ Google API ในนามของบัญชีผู้ใช้ที่ระบุได้ หากได้รับสิทธิ์เข้าถึงขอบเขตที่ API กำหนด โดยใส่โทเค็นการเข้าถึงในคำขอไปยัง API โดยใส่พารามิเตอร์การค้นหา access_token หรือค่าส่วนหัว HTTP Authorization Bearer หากเป็นไปได้ เราขอแนะนำให้ใช้ส่วนหัว HTTP เนื่องจากสตริงการค้นหามีแนวโน้มที่จะปรากฏในบันทึกของเซิร์ฟเวอร์ ในกรณีส่วนใหญ่ คุณสามารถใช้ไลบรารีของไคลเอ็นต์เพื่อตั้งค่าการเรียกใช้ Google API (เช่น เมื่อเรียกใช้ 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 https://www.googleapis.com/auth/calendar.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 สําหรับแอปเนทีฟได้ระบุแนวทางปฏิบัติแนะนําหลายประการไว้ที่นี่