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

<br class="ph-2-0] ภาพรวมจะสรุปกระบวนการ OAuth 2.0 ที่ Google รองรับ ซึ่งจะช่วยให้มั่นใจได้ว่าคุณเลือกกระบวนการที่ถูกต้องสําหรับแอปพลิเคชันของคุณ

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

  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 APIs ต้องมีข้อมูลเข้าสู่ระบบการให้สิทธิ์ที่ระบุแอปพลิเคชันไปยังเซิร์ฟเวอร์ 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
    • หากคุณจัดการคีย์สโตร์และคีย์การลงนามของคุณเอง ให้ใช้ยูทิลิตีคีย์เครื่องมือที่มาพร้อมกับ Java เพื่อพิมพ์ข้อมูลใบรับรองในรูปแบบที่มนุษย์อ่านได้ คัดลอกค่า SHA1 ในส่วน Certificate fingerprints ของเอาต์พุต keytool ดูข้อมูลเพิ่มเติมที่หัวข้อการตรวจสอบสิทธิ์ไคลเอ็นต์ของคุณในเอกสารประกอบของ Google APIs สําหรับ Android
  5. คลิกสร้าง
iOS
  1. เลือกประเภทแอปพลิเคชัน iOS
  2. ป้อนชื่อสําหรับไคลเอ็นต์ OAuth ชื่อนี้จะปรากฏในโปรเจ็กต์ Credentials page ของคุณเพื่อระบุไคลเอ็นต์
  3. ป้อนรหัสชุดของแอป รหัสชุดคือค่าของคีย์ CFBundleIdentifier ในไฟล์ทรัพยากรรายการข้อมูลของแอป (info.plist) ค่านี้แสดงบ่อยที่สุดในแผง "ทั่วไป" หรือแผง "การลงนามและศักยภาพ" ของเครื่องมือแก้ไขโปรเจ็กต์ Xcode นอกจากนี้ รหัสชุดรหัสยังแสดงในส่วนข้อมูลทั่วไปของหน้าข้อมูลแอปของแอปนั้นๆ ในเว็บไซต์ Apple 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 สําหรับ Code Exchange (PKCE) เพื่อทําให้ขั้นตอนของแอปที่ติดตั้งไว้มีความปลอดภัยมากขึ้น เครื่องมือยืนยันโค้ดที่ไม่ซ้ํากันจะสร้างขึ้นสําหรับ คําขอการให้สิทธิ์ทั้งหมด และค่าที่แปลงแล้ว ซึ่งก็คือ "code_challenge" จะส่งไปยังเซิร์ฟเวอร์การให้สิทธิ์เพื่อรับรหัสการให้สิทธิ์

สร้างเครื่องมือยืนยันโค้ด

code_verifier คือสตริงแบบสุ่มที่เข้ารหัสสูงซึ่งเน้นการใช้อักขระที่ไม่ได้สงวนไว้ [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" มีความยาวได้ต่ําสุด 83 อักขระและความยาวไม่เกิน 43 อักขระ

เครื่องมือยืนยันโค้ดควรมีเอนโทรปีมากพอที่จะทําให้คาดเดาค่าไม่ได้

สร้างภารกิจทดสอบโค้ด

เรารองรับการสร้างโจทย์รหัส 2 วิธีด้วยกัน

วิธีสร้างรหัสทดสอบ
S256 (แนะนํา) การทดสอบโค้ดคือแฮช SHA256 ที่เข้ารหัสแบบ Base64URL (ไม่มี Padding) ของเครื่องมือยืนยันโค้ด
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 ConsoleCredentials 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 แบบวนซ้ํา http://127.0.0.1:port หรือ http://[::1]:port

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

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

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

ตั้งค่าพารามิเตอร์เป็น 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 หลังจากที่ผู้ใช้ให้คํายินยอมหรือปฏิเสธคําขอเข้าถึงของแอปพลิเคชันของคุณ

คุณใช้พารามิเตอร์นี้เพื่อวัตถุประสงค์ต่างๆ ได้ เช่น การนําผู้ใช้ไปยังทรัพยากรที่ถูกต้องในแอปพลิเคชัน การส่ง nonces และการบรรเทาการปลอมแปลงคําขอแบบข้ามเว็บไซต์ เนื่องจาก 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=&
 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%3A//127.0.0.1%3A9004&
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 ได้กําหนดแนวทางปฏิบัติแนะนําไว้หลายข้อ