เอกสารนี้อธิบายวิธีที่แอปพลิเคชันที่ติดตั้งในอุปกรณ์ เช่น โทรศัพท์ แท็บเล็ต และคอมพิวเตอร์ใช้ปลายทาง 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 สําหรับทีวีและ AMP, อุปกรณ์ หรือลงชื่อเข้าใช้ในทีวีและอุปกรณ์อินพุตที่จํากัด
ไลบรารีและตัวอย่าง
เราขอแนะนําให้ใช้ไลบรารีและตัวอย่างต่อไปนี้เพื่อช่วยคุณนําขั้นตอน OAuth 2.0 ที่อธิบายไว้ในเอกสารนี้ไปใช้
สิ่งที่ต้องมีก่อน
เปิดใช้ API สําหรับโปรเจ็กต์
แอปพลิเคชันใดก็ตามที่เรียกใช้ Google APIs จะต้องเปิดใช้ 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 APIs ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ 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
- หากคุณจัดการคีย์สโตร์และคีย์การลงนามของคุณเอง ให้ใช้ยูทิลิตีคีย์เครื่องมือที่มาพร้อมกับ Java เพื่อพิมพ์ข้อมูลใบรับรองในรูปแบบที่มนุษย์อ่านได้ คัดลอกค่า
SHA1
ในส่วนCertificate fingerprints
ของเอาต์พุต keytool ดูข้อมูลเพิ่มเติมที่หัวข้อการตรวจสอบสิทธิ์ไคลเอ็นต์ของคุณในเอกสารประกอบของ Google APIs สําหรับ Android
- คลิกสร้าง
iOS
- เลือกประเภทแอปพลิเคชัน iOS
- ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะปรากฏในโปรเจ็กต์ Credentials page ของคุณเพื่อระบุไคลเอ็นต์
- ป้อนรหัสชุดของแอป รหัสชุดคือค่าของคีย์ CFBundleIdentifier ในไฟล์ทรัพยากรรายการข้อมูลของแอป (info.plist) ค่านี้แสดงบ่อยที่สุดในแผง "ทั่วไป" หรือแผง "การลงนามและศักยภาพ" ของเครื่องมือแก้ไขโปรเจ็กต์ Xcode นอกจากนี้ รหัสชุดรหัสยังแสดงในส่วนข้อมูลทั่วไปของหน้าข้อมูลแอปของแอปนั้นๆ ในเว็บไซต์ Apple 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 สําหรับ Code Exchange (PKCE) เพื่อทําให้ขั้นตอนของแอปที่ติดตั้งไว้มีความปลอดภัยมากขึ้น เครื่องมือยืนยันโค้ดที่ไม่ซ้ํากันจะสร้างขึ้นสําหรับ คําขอการให้สิทธิ์ทั้งหมด และค่าที่แปลงแล้ว ซึ่งก็คือ "code_challenge" จะส่งไปยังเซิร์ฟเวอร์การให้สิทธิ์เพื่อรับรหัสการให้สิทธิ์
สร้างเครื่องมือยืนยันโค้ด
code_verifier
คือสตริงแบบสุ่มที่เข้ารหัสสูงซึ่งเน้นการใช้อักขระที่ไม่ได้สงวนไว้ [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" มีความยาวได้ต่ําสุด 83 อักขระและความยาวไม่เกิน 43 อักขระ
เครื่องมือยืนยันโค้ดควรมีเอนโทรปีมากพอที่จะทําให้คาดเดาค่าไม่ได้
สร้างภารกิจทดสอบโค้ด
เรารองรับการสร้างโจทย์รหัส 2 วิธีด้วยกัน
วิธีสร้างรหัสทดสอบ | |
---|---|
S256 (แนะนํา) | การทดสอบโค้ดคือแฮช SHA256 ที่เข้ารหัสแบบ Base64URL (ไม่มี Padding) ของเครื่องมือยืนยันโค้ด
|
ธรรมดา | การทดสอบโค้ดจะเป็นค่าเดียวกันกับโปรแกรมยืนยันโค้ดที่สร้างขึ้นข้างต้น
|
ขั้นตอนที่ 2: ส่งคําขอไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google
หากต้องการขอสิทธิ์ผู้ใช้ ให้ส่งคําขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ https://accounts.google.com/o/oauth2/v2/auth
ปลายทางนี้จะจัดการกับการค้นหาเซสชันที่ใช้งานอยู่ ตรวจสอบสิทธิ์ผู้ใช้ และได้รับคํายินยอมจากผู้ใช้ ปลายทางจะเข้าถึงได้ผ่านทาง SSL เท่านั้น และจะปฏิเสธการเชื่อมต่อ HTTP (ไม่ใช่ SSL)
เซิร์ฟเวอร์การให้สิทธิ์รองรับพารามิเตอร์สตริงการค้นหาต่อไปนี้สําหรับแอปพลิเคชันที่ติดตั้งไว้
พารามิเตอร์ | |||||||
---|---|---|---|---|---|---|---|
client_id |
จำเป็น
รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API ConsoleCredentials page |
||||||
redirect_uri |
จำเป็น
กําหนดวิธีที่เซิร์ฟเวอร์การให้สิทธิ์ของ Google ส่งการตอบกลับไปยังแอปของคุณ มีตัวเลือกเปลี่ยนเส้นทางมากมายสําหรับแอปที่ติดตั้ง และคุณจะตั้งค่าข้อมูลเข้าสู่ระบบสําหรับการให้สิทธิ์โดยคํานึงถึงการเปลี่ยนเส้นทางที่เจาะจง ค่านี้ต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าใน API Consoleของ Credentials pageไว้ทุกประการ หากค่านี้ไม่ตรงกับ URI ที่ได้รับอนุญาต คุณจะได้รับข้อผิดพลาด ตารางด้านล่างแสดงค่าพารามิเตอร์
|
||||||
response_type |
จำเป็น
กําหนดว่าปลายทาง OAuth 2.0 ของ Google แสดงรหัสการให้สิทธิ์หรือไม่ ตั้งค่าพารามิเตอร์เป็น |
||||||
scope |
จำเป็น
รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะบอกให้หน้าจอคํายินยอมที่ Google แสดงต่อผู้ใช้ ขอบเขตจะช่วยให้แอปพลิเคชันของคุณขอเข้าถึงเฉพาะทรัพยากรที่จําเป็นเท่านั้น ขณะเดียวกันก็ช่วยให้ผู้ใช้ควบคุมจํานวนสิทธิ์เข้าถึงที่ตนให้กับแอปพลิเคชันของคุณได้ ดังนั้น ความสัมพันธ์ระหว่างขอบเขตที่ขอกับความเป็นไปได้ที่จะได้รับความยินยอมจากผู้ใช้จึงมีความสัมพันธ์กัน |
||||||
code_challenge |
แนะนำ
ระบุ |
||||||
code_challenge_method |
แนะนำ
ระบุวิธีที่ใช้เข้ารหัส |
||||||
state |
แนะนำ
ระบุค่าสตริงที่แอปพลิเคชันจะใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์
เซิร์ฟเวอร์จะส่งคืนค่าที่แน่นอนที่คุณส่งเป็นคู่ของ คุณใช้พารามิเตอร์นี้เพื่อวัตถุประสงค์ต่างๆ ได้ เช่น การนําผู้ใช้ไปยังทรัพยากรที่ถูกต้องในแอปพลิเคชัน การส่ง nonces และการบรรเทาการปลอมแปลงคําขอแบบข้ามเว็บไซต์ เนื่องจาก |
||||||
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=& 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 ของ Loopback
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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 โปรดดูบทความช่วยเหลือของผู้ดูแลระบบ Google Workspace เพื่อควบคุมว่าจะให้แอปของบุคคลที่สามและแอปภายในรายการใดเข้าถึงข้อมูล Google Workspace ได้บ้างเพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ผู้ดูแลระบบอาจจํากัดการเข้าถึงขอบเขตทั้งหมดหรือขอบเขตที่มีความละเอียดอ่อนและถูกจํากัด จนกว่าจะได้รับสิทธิ์เข้าถึงรหัสไคลเอ็นต์ OAuth อย่างชัดแจ้ง
disallowed_useragent
ปลายทางการให้สิทธิ์จะแสดงใน User Agent แบบฝังที่นโยบาย OAuth 2.0 ของ Google ไม่อนุญาต
Android
นักพัฒนาแอป Android อาจพบข้อความแสดงข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน android.webkit.WebView
นักพัฒนาซอฟต์แวร์ควรใช้ไลบรารี Android เช่น Google Sign-In สําหรับ Android หรือ OpenID Foundation'AppAuth สําหรับ Android แทน
นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป Android เปิดลิงก์เว็บทั่วไปใน User Agent ที่ฝังอยู่ และผู้ใช้ไปที่ปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรอนุญาตให้ลิงก์ทั่วไปเปิดในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งรวมทั้งเครื่องจัดการ Android App Link หรือแอปเบราว์เซอร์เริ่มต้น นอกจากนี้ไลบรารีแท็บที่กําหนดเองของ Android ก็เป็นตัวเลือกที่รองรับด้วย
iOS
นักพัฒนา iOS และ macOS อาจพบข้อผิดพลาดนี้เมื่อเปิดคําขอการให้สิทธิ์ใน WKWebView
นักพัฒนาซอฟต์แวร์ควรใช้ไลบรารี iOS เช่น Google Sign-In สําหรับ iOS หรือ OpenID Foundation'AppAuth สําหรับ iOS แทน
นักพัฒนาเว็บอาจพบข้อผิดพลาดนี้เมื่อแอป iOS หรือ macOS เปิดลิงก์เว็บทั่วไปใน User Agent ที่ฝังอยู่และผู้ใช้ไปยังปลายทางการให้สิทธิ์ OAuth 2.0 ของ Google จากเว็บไซต์ของคุณ นักพัฒนาซอฟต์แวร์ควรอนุญาตให้ลิงก์ทั่วไปเปิดในเครื่องจัดการลิงก์เริ่มต้นของระบบปฏิบัติการ ซึ่งรวมทั้งเครื่องจัดการ Universal Link หรือแอปเบราว์เซอร์เริ่มต้น นอกจากนี้ไลบรารี SFSafariViewController
ก็เป็นตัวเลือกที่รองรับด้วย
org_internal
รหัสไคลเอ็นต์ OAuth ในคําขอเป็นส่วนหนึ่งของโปรเจ็กต์ที่จํากัดการเข้าถึงบัญชี Google ในองค์กร Google Cloud ที่เจาะจง ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกการกําหนดค่านี้ได้ในส่วนประเภทผู้ใช้ในบทความช่วยเหลือการตั้งค่าการตั้งค่าความยินยอมของ OAuth
redirect_uri_mismatch
redirect_uri
ที่ส่งผ่านในคําขอการให้สิทธิ์ไม่ตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสําหรับรหัสไคลเอ็นต์ OAuth ตรวจสอบ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตใน Google API Console Credentials page
redirect_uri
ที่ส่งผ่านอาจไม่ถูกต้องสําหรับประเภทไคลเอ็นต์
ขั้นตอนที่ 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 ConsoleCredentials 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 Web Token (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 APIs
หลังจากที่แอปพลิเคชันได้รับโทเค็นเพื่อการเข้าถึงแล้ว คุณจะใช้โทเค็นเพื่อเรียก 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 ที่เกี่ยวข้อง คุณรีเฟรชโทเค็นเพื่อการเข้าถึงได้โดยไม่ต้องแจ้งผู้ใช้เพื่อขอรับสิทธิ์ (รวมถึงเมื่อผู้ใช้ไม่แสดง) หากคุณขอสิทธิ์เข้าถึงแบบออฟไลน์ซึ่งเชื่อมโยงกับขอบเขตที่เกี่ยวข้องกับโทเค็น
ในการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันจะส่งคําขอ HTTPS POST
ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ 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 ต่อชุดค่าผสมของไคลเอ็นต์/ผู้ใช้ และจํานวนที่จํากัดต่อผู้ใช้ต่อไคลเอ็นต์ทั้งหมด คุณควรบันทึกโทเค็นการรีเฟรชในระยะยาว แล้วใช้โทเค็นต่อไปตราบใดที่โทเค็นนั้นยังคงใช้งานได้ หากแอปพลิเคชันของคุณขอโทเค็นการรีเฟรชมากเกินไป โทเค็นดังกล่าวอาจทํางานผิดพลาดได้ ซึ่งในกรณีนี้โทเค็นการรีเฟรชเวอร์ชันเก่าจะหยุดทํางาน
กําลังเพิกถอนโทเค็น
ในบางกรณีผู้ใช้อาจต้องการเพิกถอนสิทธิ์เข้าถึงแอปพลิเคชัน ผู้ใช้จะเพิกถอนสิทธิ์เข้าถึงได้โดยไปที่การตั้งค่าบัญชี ดูข้อมูลเพิ่มเติมได้จากเอกสารสนับสนุนในหัวข้อนําเว็บไซต์หรือแอปออกของเว็บไซต์ของบุคคลที่สามและแอปที่มีสิทธิ์เข้าถึงบัญชีของคุณ
นอกจากนี้ แอปพลิเคชันอาจเพิกถอนการเข้าถึงแบบเป็นโปรแกรมด้วยโปรแกรมได้ การเพิกถอนแบบเป็นโปรแกรมมีความสําคัญในกรณีที่ผู้ใช้ยกเลิกการสมัคร นําแอปพลิเคชันออก หรือทรัพยากร 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
พร้อมกับรหัสข้อผิดพลาด
อ่านเพิ่มเติม
แนวทางปฏิบัติแนะนําสําหรับ OAuth 2.0 สําหรับแอปที่มาพร้อมเครื่องจาก IETF ได้กําหนดแนวทางปฏิบัติแนะนําไว้หลายข้อ