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

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

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

  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 และตั้งค่าช่องอื่นๆ ในแบบฟอร์มตามความเหมาะสม

รูปแบบ URI ที่กําหนดเอง (Android, iOS, UWP)

รูปแบบของ URI ที่กําหนดเองเหมาะสําหรับแอป Android, แอป iOS และแอป Universal Windows Platform (UWP)

Android
  1. เลือกประเภทแอปพลิเคชันเป็น Android
  2. ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
  3. ป้อนชื่อแพ็กเกจของแอป Android โดยค่านี้จะกําหนดใน แอตทริบิวต์ package ขององค์ประกอบ <manifest> ในไฟล์ Manifest ของแอป
  4. ป้อนลายนิ้วมือสําหรับใบรับรอง SHA-1 ของการเผยแพร่แอป
    • หากแอปใช้ App Signing โดย Google Play ให้คัดลอกลายนิ้วมือ SHA-1 จากหน้า App Signing ของ Play Console
    • หากคุณจัดการคีย์สโตร์และคีย์ Signing ของคุณเอง ให้ใช้ยูทิลิตีคีย์เครื่องมือที่มาพร้อมกับ Java เพื่อพิมพ์ข้อมูลใบรับรองในรูปแบบที่มนุษย์อ่านได้ คัดลอกค่า SHA1 ในส่วน Certificate fingerprints ของเอาต์พุต keytool ดูการตรวจสอบสิทธิ์ไคลเอ็นต์ของคุณในเอกสารประกอบของ Google APIs สําหรับ Android สําหรับข้อมูลเพิ่มเติม
  5. คลิกสร้าง
iOS
  1. เลือกประเภทแอปพลิเคชัน iOS
  2. ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
  3. ป้อนตัวระบุชุดแอป รหัสชุดคือค่าของคีย์ CFBundleIdentifier ในไฟล์ทรัพยากรของรายการข้อมูลของแอป (info.plist) ค่าจะแสดงบ่อยที่สุดในแผง "ทั่วไป" หรือแผง "การลงนามและความสามารถ" ของเครื่องมือแก้ไขโปรเจ็กต์ Xcode รหัสชุดจะแสดงในส่วนข้อมูลทั่วไปของหน้าข้อมูลแอปสําหรับแอปในเว็บไซต์ App Store Connect ของ Apple ด้วย
  4. (ไม่บังคับ)

    ป้อนรหัส App Store ของแอปหากแอปได้รับการเผยแพร่ใน App Store ของ Apple รหัสร้านค้าเป็นสตริงตัวเลขที่รวมอยู่ใน URL ของ Apple App Store ทุกรายการ

    1. เปิดแอป Apple App Store บนอุปกรณ์ iOS หรือ iPadOS
    2. ค้นหาแอปของคุณ
    3. เลือกปุ่มแชร์ (สัญลักษณ์สี่เหลี่ยมจัตุรัสและลูกศรขึ้น)
    4. เลือกคัดลอกลิงก์
    5. วางลิงก์ลงในเครื่องมือแก้ไขข้อความ รหัส App Store คือส่วนสุดท้ายของ URL

      เช่น https://apps.apple.com/app/google/id284815942

  5. (ไม่บังคับ)

    ป้อนรหัสทีม ดูข้อมูลเพิ่มเติมในค้นหารหัสทีมของคุณในเอกสารประกอบสําหรับนักพัฒนาซอฟต์แวร์ Apple

  6. คลิกสร้าง
UWP
  1. เลือกประเภทแอปพลิเคชัน Universal Windows Platform
  2. ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
  3. ป้อนรหัส Microsoft Store ที่มีอักขระ 12 ตัวของแอป คุณดูค่านี้ได้ใน Microsoft Partner Center ในหน้าข้อมูลประจําตัวของแอปในส่วนการจัดการแอป
  4. คลิกสร้าง

สําหรับแอป 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 ที่เข้ารหัสพื้นฐาน (ไม่มีระยะห่างจากขอบ) ของตัวตรวจสอบโค้ด
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)

เซิร์ฟเวอร์การให้สิทธิ์รองรับพารามิเตอร์สตริงการค้นหาต่อไปนี้สําหรับแอปพลิเคชันที่ติดตั้ง

พารามิเตอร์
client_id จำเป็น

รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน API Console Credentials page

redirect_uri จำเป็น

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

ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสําหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกําหนดค่าไว้ใน API Console Credentials pageของไคลเอ็นต์ หากค่านี้ไม่ตรงกับ URI ที่ได้รับอนุญาต คุณจะได้รับข้อผิดพลาด redirect_uri_mismatch

ตารางด้านล่างแสดงค่าพารามิเตอร์ redirect_uri ที่เหมาะสมสําหรับแต่ละเมธอด

ค่า redirect_uri
รูปแบบ URI ที่กําหนดเอง com.example.app:redirect_uri_path

หรือ

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app คือรูปแบบ DNS แบบย้อนกลับของโดเมนภายใต้การควบคุมของคุณ ชุดรูปแบบที่กําหนดเองต้องมีเครื่องหมายจุดจึงจะใช้งานได้
  • com.googleusercontent.apps.123 คือรูปแบบ DNS แบบย้อนกลับของรหัสไคลเอ็นต์
  • redirect_uri_path เป็นคอมโพเนนต์เส้นทางที่ไม่บังคับ เช่น /oauth2redirect โปรดทราบว่าเส้นทางควรเริ่มต้นด้วยเครื่องหมายทับเดี่ยวซึ่งแตกต่างจาก HTTP URL ปกติ
ที่อยู่ IP ของ Loopback http://127.0.0.1:port หรือ http://[::1]:port

ค้นหาแพลตฟอร์มสําหรับที่อยู่ IP ของ Loopback ที่เกี่ยวข้องและเริ่ม Listener ของ HTTP บนพอร์ตที่พร้อมใช้งานแบบสุ่ม แทนที่ port ด้วยหมายเลขพอร์ตจริงที่แอปฟังอยู่

โปรดทราบว่าการรองรับตัวเลือกการเปลี่ยนเส้นทางที่อยู่ IP แบบวนซ้ําในแอปบนอุปกรณ์เคลื่อนที่นั้น เลิกใช้งานแล้ว

response_type จำเป็น

กําหนดว่าปลายทาง Google OAuth 2.0 จะแสดงรหัสการให้สิทธิ์หรือไม่

ตั้งค่าพารามิเตอร์เป็น code สําหรับแอปพลิเคชันที่ติดตั้งไว้

scope จำเป็น

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

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

code_challenge แนะนำ

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

code_challenge_method แนะนำ

ระบุวิธีที่ใช้เข้ารหัส code_verifier ที่จะใช้ระหว่างการแลกเปลี่ยนรหัสการให้สิทธิ์ ต้องใช้พารามิเตอร์นี้กับพารามิเตอร์ code_challenge ที่อธิบายข้างต้น ค่าของ code_challenge_method จะมีค่าเริ่มต้นเป็น plain หากไม่อยู่ในคําขอที่มี code_challenge ค่าเดียวที่รองรับสําหรับพารามิเตอร์นี้คือ S256 หรือ plain

state แนะนำ

ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคําขอการให้สิทธิ์กับการตอบสนองของเซิร์ฟเวอร์การให้สิทธิ์ เซิร์ฟเวอร์จะแสดงค่าที่แน่นอนที่คุณส่งเป็นคู่ของ name=value ในตัวระบุส่วนย่อยของ URL (#) ของ redirect_uri หลังจากที่ผู้ใช้ให้ความยินยอมหรือปฏิเสธคําขอการเข้าถึงของแอปพลิเคชัน

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

login_hint ไม่บังคับ

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

กําหนดค่าพารามิเตอร์เป็นอีเมลหรือตัวระบุ sub ซึ่งเทียบเท่ากับรหัส 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 สําหรับแอปที่มาพร้อมเครื่องมีแนวทางปฏิบัติแนะนํามากมายที่บันทึกไว้ในส่วนนี้