เอกสารนี้อธิบายวิธีที่แอปพลิเคชันที่ติดตั้งในอุปกรณ์ เช่น โทรศัพท์ แท็บเล็ต และคอมพิวเตอร์ใช้ปลายทาง 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 ตามที่อธิบายไว้ในเอกสารนี้
สิ่งที่ต้องดำเนินการก่อน
เปิดใช้ API สําหรับโปรเจ็กต์ของคุณ
แอปพลิเคชันที่เรียกใช้ Google API จะต้องเปิดใช้ 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
- ส่วนด้านล่างจะอธิบายประเภทไคลเอ็นต์และวิธีเปลี่ยนเส้นทางที่เซิร์ฟเวอร์การให้สิทธิ์ของ Google รองรับ เลือกประเภทไคลเอ็นต์ที่แนะนําสําหรับแอปพลิเคชัน ตั้งชื่อไคลเอ็นต์ OAuth และตั้งค่าช่องอื่นๆ ในแบบฟอร์มตามความเหมาะสม
รูปแบบ URI ที่กําหนดเอง (Android, iOS, UWP)
รูปแบบของ URI ที่กําหนดเองเหมาะสําหรับแอป Android, แอป iOS และแอป Universal Windows Platform (UWP)
Android
- เลือกประเภทแอปพลิเคชันเป็น Android
- ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
- ป้อนชื่อแพ็กเกจของแอป Android โดยค่านี้จะกําหนดใน
แอตทริบิวต์
package
ขององค์ประกอบ<manifest>
ในไฟล์ Manifest ของแอป - ป้อนลายนิ้วมือสําหรับใบรับรอง SHA-1 ของการเผยแพร่แอป
- หากแอปใช้ App Signing โดย Google Play ให้คัดลอกลายนิ้วมือ SHA-1 จากหน้า App Signing ของ Play Console
- หากคุณจัดการคีย์สโตร์และคีย์ Signing ของคุณเอง ให้ใช้ยูทิลิตีคีย์เครื่องมือที่มาพร้อมกับ Java เพื่อพิมพ์ข้อมูลใบรับรองในรูปแบบที่มนุษย์อ่านได้ คัดลอกค่า
SHA1
ในส่วนCertificate fingerprints
ของเอาต์พุต keytool ดูการตรวจสอบสิทธิ์ไคลเอ็นต์ของคุณในเอกสารประกอบของ Google APIs สําหรับ Android สําหรับข้อมูลเพิ่มเติม
- คลิกสร้าง
iOS
- เลือกประเภทแอปพลิเคชัน iOS
- ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
- ป้อนตัวระบุชุดแอป รหัสชุดคือค่าของคีย์ CFBundleIdentifier ในไฟล์ทรัพยากรของรายการข้อมูลของแอป (info.plist) ค่าจะแสดงบ่อยที่สุดในแผง "ทั่วไป" หรือแผง "การลงนามและความสามารถ" ของเครื่องมือแก้ไขโปรเจ็กต์ Xcode รหัสชุดจะแสดงในส่วนข้อมูลทั่วไปของหน้าข้อมูลแอปสําหรับแอปในเว็บไซต์ App Store Connect ของ Apple ด้วย
- (ไม่บังคับ)
ป้อนรหัส App Store ของแอปหากแอปได้รับการเผยแพร่ใน App Store ของ Apple รหัสร้านค้าเป็นสตริงตัวเลขที่รวมอยู่ใน URL ของ Apple App Store ทุกรายการ
- เปิดแอป Apple App Store บนอุปกรณ์ iOS หรือ iPadOS
- ค้นหาแอปของคุณ
- เลือกปุ่มแชร์ (สัญลักษณ์สี่เหลี่ยมจัตุรัสและลูกศรขึ้น)
- เลือกคัดลอกลิงก์
- วางลิงก์ลงในเครื่องมือแก้ไขข้อความ รหัส App Store คือส่วนสุดท้ายของ URL
เช่น
https://apps.apple.com/app/google/id284815942
- (ไม่บังคับ)
ป้อนรหัสทีม ดูข้อมูลเพิ่มเติมในค้นหารหัสทีมของคุณในเอกสารประกอบสําหรับนักพัฒนาซอฟต์แวร์ Apple
- คลิกสร้าง
UWP
- เลือกประเภทแอปพลิเคชัน Universal Windows Platform
- ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
- ป้อนรหัส Microsoft Store ที่มีอักขระ 12 ตัวของแอป คุณดูค่านี้ได้ใน Microsoft Partner Center ในหน้าข้อมูลประจําตัวของแอปในส่วนการจัดการแอป
- คลิกสร้าง
สําหรับแอป UWP รูปแบบ URI ที่กําหนดเองต้องมีความยาวไม่เกิน 39 อักขระ
ที่อยู่ IP ของ Loopback (MacOS, Linux, Windows Desktop)
แอปพลิเคชันจะต้องฟังในเว็บเซิร์ฟเวอร์ในเครื่องเพื่อรับรหัสการให้สิทธิ์โดยใช้ URL นี้ ซึ่งอาจเกิดขึ้นได้ในหลายแพลตฟอร์ม แต่ไม่ใช่ทุกแพลตฟอร์ม อย่างไรก็ตาม หากแพลตฟอร์มของคุณรองรับ นี่คือกลไกที่แนะนําสําหรับการรับรหัสการให้สิทธิ์
เมื่อแอปได้รับการตอบกลับการให้สิทธิ์ เพื่อให้ใช้งานได้ดีที่สุด คุณควรตอบสนองด้วยการแสดงหน้า HTML ที่แจ้งให้ผู้ใช้ปิดเบราว์เซอร์และกลับมาที่แอป
การใช้งานที่แนะนํา | แอป macOS, Linux และ Windows Desktop (แต่ไม่ใช่ Universal Windows Platform) |
ค่าในแบบฟอร์ม | ตั้งค่าประเภทแอปพลิเคชันเป็นแอปบนเดสก์ท็อป |
คัดลอก/วางด้วยตนเอง
ระบุขอบเขตการเข้าถึง
ขอบเขตจะช่วยให้แอปพลิเคชันขอเข้าถึงเฉพาะทรัพยากรที่จําเป็นต้องใช้เท่านั้น ขณะเดียวกันก็ทําให้ผู้ใช้ควบคุมสิทธิ์เข้าถึงที่ให้กับแอปพลิเคชันของคุณได้ ด้วยเหตุนี้ จึงอาจมีความสัมพันธ์แบบผกผันระหว่างจํานวนขอบเขตที่ขอกับแนวโน้มการขอความยินยอมจากผู้ใช้
ก่อนที่จะเริ่มใช้การให้สิทธิ์ 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 | |
---|---|
S256 (แนะนํา) | ความท้าทายของโค้ดคือแฮช SHA256 ที่เข้ารหัสพื้นฐาน (ไม่มีระยะห่างจากขอบ) ของตัวตรวจสอบโค้ด
|
ธรรมดา | โจทย์โค้ดเป็นค่าเดียวกับตัวตรวจสอบโค้ดที่สร้างขึ้นข้างต้น
|
ขั้นตอนที่ 2: ส่งคําขอไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google
หากต้องการการให้สิทธิ์ผู้ใช้ ให้ส่งคําขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่
https://accounts.google.com/o/oauth2/v2/auth
ปลายทางนี้จัดการการค้นหาเซสชันที่ใช้งานอยู่ ตรวจสอบสิทธิ์ผู้ใช้ และขอความยินยอมจากผู้ใช้ ปลายทางเข้าถึงผ่าน SSL ได้เท่านั้น และปฏิเสธการเชื่อมต่อ HTTP (ไม่ใช่ SSL)
เซิร์ฟเวอร์การให้สิทธิ์รองรับพารามิเตอร์สตริงการค้นหาต่อไปนี้สําหรับแอปพลิเคชันที่ติดตั้ง
พารามิเตอร์ | |||||||
---|---|---|---|---|---|---|---|
client_id |
จำเป็น
รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API Console Credentials page |
||||||
redirect_uri |
จำเป็น
กําหนดวิธีที่เซิร์ฟเวอร์การให้สิทธิ์ของ Google ส่งการตอบกลับไปยังแอปของคุณ ตัวเลือกการเปลี่ยนเส้นทางที่มีให้เลือกหลายรายการสําหรับแอปที่ติดตั้งไว้ และคุณจะตั้งค่าข้อมูลเข้าสู่ระบบการให้สิทธิ์โดยคํานึงถึงวิธีเปลี่ยนเส้นทางโดยเฉพาะ ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกําหนดค่าไว้ใน API Console
Credentials pageของไคลเอ็นต์ หากค่านี้ไม่ตรงกับ URI ที่ได้รับอนุญาต คุณจะได้รับข้อผิดพลาด ตารางด้านล่างแสดงค่าพารามิเตอร์
|
||||||
response_type |
จำเป็น
กําหนดว่าปลายทาง Google OAuth 2.0 จะแสดงรหัสการให้สิทธิ์หรือไม่ ตั้งค่าพารามิเตอร์เป็น |
||||||
scope |
จำเป็น
รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกให้หน้าจอขอความยินยอมที่ Google แสดงต่อผู้ใช้ ขอบเขตจะช่วยให้แอปพลิเคชันขอเข้าถึงเฉพาะทรัพยากรที่จําเป็นต้องใช้เท่านั้น และในขณะเดียวกันก็ทําให้ผู้ใช้ควบคุมสิทธิ์เข้าถึงที่ตนเองมีให้กับแอปพลิเคชันได้ด้วย ดังนั้นจึงมีความสัมพันธ์แบบผกผันระหว่างจํานวนขอบเขตที่ขอกับแนวโน้มการขอความยินยอมจากผู้ใช้ |
||||||
code_challenge |
แนะนำ
ระบุ |
||||||
code_challenge_method |
แนะนำ
ระบุวิธีที่ใช้เข้ารหัส |
||||||
state |
แนะนำ
ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบสนองของเซิร์ฟเวอร์การให้สิทธิ์
เซิร์ฟเวอร์จะแสดงค่าที่แน่นอนที่คุณส่งเป็นคู่ของ คุณสามารถใช้พารามิเตอร์นี้เพื่อวัตถุประสงค์ต่างๆ เช่น การนําผู้ใช้ไปยังทรัพยากรที่ถูกต้องในแอปพลิเคชัน การส่งCECE และการปลอมแปลงการปลอมแปลงคําขอข้ามเว็บไซต์ เนื่องจากระบบเดา |
||||||
login_hint |
ไม่บังคับ
หากแอปพลิเคชันทราบว่าผู้ใช้รายใดพยายามตรวจสอบสิทธิ์ แอปก็จะใช้พารามิเตอร์นี้เพื่อให้คําแนะนําแก่เซิร์ฟเวอร์การตรวจสอบสิทธิ์ของ Google เซิร์ฟเวอร์จะใช้คําแนะนําเพื่อลดความซับซ้อนของขั้นตอนการเข้าสู่ระบบโดยกรอกช่องอีเมลในแบบฟอร์มลงชื่อเข้าใช้ หรือจะเลือกเซสชันการเข้าสู่ระบบหลายบัญชีที่เหมาะสมก็ได้ กําหนดค่าพารามิเตอร์เป็นอีเมลหรือตัวระบุ |
ตัวอย่าง URL การให้สิทธิ์
แท็บด้านล่างแสดงตัวอย่าง URL การให้สิทธิ์สําหรับตัวเลือก URI การเปลี่ยนเส้นทางต่างๆ
URL เหมือนกันทุกประการ ยกเว้นค่าของพารามิเตอร์ redirect_uri
URL มีพารามิเตอร์ response_type
และ client_id
ที่จําเป็น รวมถึงพารามิเตอร์ state
ที่ไม่บังคับด้วย URL แต่ละรายการมีตัวแบ่งบรรทัดและการเว้นวรรคเพื่อให้อ่านได้
รูปแบบ URI ที่กําหนดเอง
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
ที่อยู่ IP การวนกลับ
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 ซึ่งระบุว่ามีสิทธิ์เข้าถึงแล้วหรือไม่ โดยคําตอบดังกล่าวจะอธิบายในขั้นตอนต่อไปนี้
ข้อผิดพลาด
คําขอที่ส่งไปยังปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google อาจแสดงข้อความแสดงข้อผิดพลาดที่ผู้ใช้มองเห็น แทนที่จะเป็นขั้นตอนการตรวจสอบสิทธิ์และการให้สิทธิ์ที่คาดไว้ รหัสข้อผิดพลาดทั่วไปและการแก้ปัญหาที่แนะนํามีดังนี้
admin_policy_enforced
บัญชี Google ไม่สามารถให้สิทธิ์ขอบเขตอย่างน้อย 1 คําขอได้เนื่องจากนโยบายของผู้ดูแลระบบ Google Workspace ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ผู้ดูแลระบบอาจจํากัดการเข้าถึงขอบเขตทั้งหมดหรือขอบเขตที่จํากัดและละเอียดอ่อนได้จนกว่าผู้ใช้จะมีสิทธิ์เข้าถึงรหัสไคลเอ็นต์ OAuth อย่างชัดแจ้ง ทั้งนี้ขึ้นอยู่กับบทความช่วยเหลือผู้ดูแลระบบ Google Workspace ควบคุมว่าจะให้แอปของบุคคลที่สามและแอปภายในรายการใดเข้าถึงข้อมูล Google Workspace ได้บ้าง
disallowed_useragent
ปลายทางการให้สิทธิ์จะแสดงภายใน User Agent ที่ฝังซึ่งนโยบาย OAuth 2.0 ของ Google ไม่อนุญาต
Android
นักพัฒนาแอป Android อาจพบข้อความแสดงข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน
android.webkit.WebView
นักพัฒนาซอฟต์แวร์ควรใช้ไลบรารี Android เช่น Google Sign-In สําหรับ Android หรือ AppAuth สําหรับ Android ของ OpenID Foundation
นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป Android เปิดลิงก์เว็บทั่วไปใน User Agent แบบฝัง และผู้ใช้ไปยังปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรเปิดลิงก์ทั่วไปในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งมีทั้งเครื่องจัดการ Android App Link หรือแอปเบราว์เซอร์เริ่มต้น ไลบรารีแท็บที่กําหนดเองของ Android ก็เป็นตัวเลือกที่รองรับเช่นกัน
iOS
นักพัฒนาแอป iOS และ macOS อาจพบข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน WKWebView
นักพัฒนาซอฟต์แวร์ควรใช้ไลบรารี iOS เช่น Google Sign-In สําหรับ iOS หรือ AppAuth สําหรับ iOS ของ OpenID Foundation
นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป iOS หรือ macOS เปิดลิงก์เว็บทั่วไปใน User Agent ที่ฝัง และผู้ใช้ไปยังปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรอนุญาตให้ลิงก์ทั่วไปเปิดในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งมีทั้งเครื่องจัดการ Universal Link หรือแอปเบราว์เซอร์เริ่มต้น และไลบรารี SFSafariViewController
ก็เป็นตัวเลือกที่รองรับเช่นกัน
org_internal
รหัสไคลเอ็นต์ OAuth ในคําขอเป็นส่วนหนึ่งของโปรเจ็กต์ที่จํากัดการเข้าถึงบัญชี Google ใน องค์กร Google Cloud ที่เฉพาะเจาะจง ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกการกําหนดค่านี้ได้ที่ส่วนประเภทผู้ใช้ในบทความช่วยเหลือเกี่ยวกับการตั้งค่าหน้าจอขอความยินยอม OAuth
invalid_grant
หากคุณใช้ตัวตรวจสอบโค้ดและโจทย์ พารามิเตอร์ code_callenge
ไม่ถูกต้องหรือขาดหายไป ตรวจสอบว่าได้ตั้งค่าพารามิเตอร์ code_challenge
ไว้อย่างถูกต้อง
เมื่อรีเฟรชโทเค็นเพื่อการเข้าถึง โทเค็นอาจหมดอายุหรือใช้งานไม่ได้ ตรวจสอบสิทธิ์ผู้ใช้อีกครั้งและขอความยินยอมจากผู้ใช้เพื่อรับโทเค็นใหม่ หากยังคงพบข้อผิดพลาดนี้ โปรดตรวจสอบว่าได้กําหนดค่าแอปพลิเคชันอย่างถูกต้องแล้ว และได้ใช้โทเค็นและพารามิเตอร์ที่ถูกต้องในคําขอ มิเช่นนั้น บัญชีผู้ใช้อาจถูกลบหรือปิดใช้แล้ว
redirect_uri_mismatch
redirect_uri
ที่ส่งผ่านในคําขอการให้สิทธิ์ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับรหัสไคลเอ็นต์ OAuth ตรวจสอบ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตใน Google API Console Credentials page
redirect_uri
ที่ส่งอาจไม่ถูกต้องสําหรับประเภทไคลเอ็นต์
พารามิเตอร์ redirect_uri
อาจอ้างถึงโฟลว์ OAuth นอกย่านความถี่ (OOB) ที่เลิกใช้งานแล้วและไม่รองรับแล้ว โปรดดูคําแนะนําในการย้ายข้อมูลเพื่ออัปเดตการผสานรวม
ขั้นตอนที่ 4: จัดการการตอบกลับของเซิร์ฟเวอร์ OAuth 2.0
วิธีที่แอปพลิเคชันได้รับการตอบกลับการให้สิทธิ์จะขึ้นอยู่กับรูปแบบ URI การเปลี่ยนเส้นทางที่แอปใช้ ไม่ว่าคําตอบจะเป็นรูปแบบใด การตอบกลับจะมีรหัสการให้สิทธิ์ (code
) หรือข้อผิดพลาด (error
) เช่น error=access_denied
บ่งชี้ว่าผู้ใช้ปฏิเสธคําขอ
หากผู้ใช้ให้สิทธิ์เข้าถึงแอปพลิเคชัน คุณอาจแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรชได้ตามที่อธิบายไว้ในขั้นตอนถัดไป
ขั้นตอนที่ 5: รหัสการให้สิทธิ์ของ Exchange สําหรับโทเค็นการรีเฟรชและการเข้าถึง
หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึง ให้เรียกใช้ปลายทาง https://oauth2.googleapis.com/token
และตั้งค่าพารามิเตอร์ต่อไปนี้
ช่อง | |
---|---|
client_id |
รหัสไคลเอ็นต์ที่ได้รับจาก API Console Credentials page |
client_secret |
รหัสลับไคลเอ็นต์ที่ได้รับจาก API Console Credentials page |
code |
รหัสการให้สิทธิ์ที่ส่งกลับมาจากคําขอเริ่มต้น |
code_verifier |
เครื่องมือตรวจสอบโค้ดที่คุณสร้างในขั้นตอนที่ 1 |
grant_type |
ตามที่กําหนดไว้ในข้อกําหนด OAuth 2.0 ค่าของช่องนี้ต้องเป็น authorization_code |
redirect_uri |
หนึ่งใน URI การเปลี่ยนเส้นทางที่แสดงสําหรับโปรเจ็กต์ของคุณใน API Console
Credentials page สําหรับ client_id ที่ระบุ |
ข้อมูลโค้ดต่อไปนี้จะแสดงคําขอตัวอย่าง
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 |
โทเค็นที่แอปพลิเคชันของคุณส่งเพื่อให้สิทธิ์คําขอ Google API |
expires_in |
อายุการใช้งานที่เหลือของโทเค็นเพื่อการเข้าถึงเป็นวินาที |
id_token |
หมายเหตุ: ระบบจะส่งพร็อพเพอร์ตี้นี้กลับมาหากคําขอมีขอบเขตข้อมูลระบุตัวตนเท่านั้น เช่น openid , profile หรือ email ค่าคือโทเค็นเว็บ JSON (JWT) ที่มีข้อมูลระบุตัวตนลายเซ็นดิจิทัลเกี่ยวกับผู้ใช้ |
refresh_token |
โทเค็นที่คุณใช้เพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ได้ โทเค็นการรีเฟรชจะใช้ได้จนกว่าผู้ใช้จะเพิกถอนสิทธิ์เข้าถึง โปรดทราบว่าระบบจะรีเฟรชโทเค็นการรีเฟรชเสมอสําหรับแอปพลิเคชันที่ติดตั้งไว้ |
scope |
ขอบเขตของการเข้าถึงที่ได้มาจาก access_token ซึ่งแสดงเป็นรายการสตริงที่คั่นด้วยช่องว่างและคํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ |
token_type |
ประเภทของโทเค็นที่ส่งคืน ปัจจุบันค่าในช่องนี้ตั้งไว้เป็น Bearer เสมอ |
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการตอบกลับ
{ "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
) ซึ่งมีพารามิเตอร์ต่อไปนี้
ช่อง | |
---|---|
client_id |
รหัสไคลเอ็นต์ที่ได้รับจาก API Console |
client_secret |
รหัสลับไคลเอ็นต์ที่ได้รับจาก API Console
(client_secret ใช้ไม่ได้กับคําขอจากลูกค้าที่ลงทะเบียนเป็นแอปพลิเคชัน Android, iOS หรือ Chrome)
|
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 รายการต่อไคลเอ็นต์/ผู้ใช้ และ 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 สําหรับแอปที่มาพร้อมเครื่องมีแนวทางปฏิบัติแนะนํามากมายที่บันทึกไว้ในส่วนนี้