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 ตามที่อธิบายในเอกสารนี้

ข้อกำหนดเบื้องต้น

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

  1. Go to the Credentials page.
  2. คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth
  3. ส่วนต่อไปนี้อธิบายถึงประเภทไคลเอ็นต์และวิธีการเปลี่ยนเส้นทางที่เซิร์ฟเวอร์การให้สิทธิ์ของ Google รองรับ เลือกประเภทไคลเอ็นต์ที่แนะนำสำหรับแอปพลิเคชัน ตั้งชื่อไคลเอ็นต์ OAuth และตั้งค่าช่องอื่นๆ ในแบบฟอร์มตามความเหมาะสม
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
    • หากคุณจัดการคีย์สโตร์และคีย์การรับรองของคุณเอง ให้ใช้ยูทิลิตีkeytoolที่มากับ Java เพื่อพิมพ์ข้อมูลใบรับรองในรูปแบบที่มนุษย์อ่านได้ คัดลอกค่า SHA1 ในส่วน Certificate fingerprints ของเอาต์พุตkeytool ดูข้อมูลเพิ่มเติมที่การตรวจสอบสิทธิ์ไคลเอ็นต์ในเอกสารประกอบของ Google APIs สำหรับ Android
  5. (ไม่บังคับ) ยืนยันการเป็นเจ้าของแอปพลิเคชัน Android
  6. คลิกสร้าง
iOS
  1. เลือกประเภทแอปพลิเคชัน iOS
  2. ป้อนชื่อไคลเอ็นต์ OAuth ชื่อนี้จะแสดงใน Credentials page ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
  3. ป้อน Bundle ID สำหรับแอป รหัสชุดคือค่าของคีย์ CFBundleIdentifier ในไฟล์ทรัพยากรรายการพร็อพเพอร์ตี้ข้อมูลของแอป (info.plist) ค่าดังกล่าวมักจะแสดงในแผงทั่วไปหรือแผง Signing & Capabilities ของเครื่องมือแก้ไขโปรเจ็กต์ 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 ในหน้าข้อมูลประจําตัวของแอปในส่วนการจัดการแอป
  4. คลิกสร้าง

สําหรับแอป UWP รูปแบบ URI ที่กําหนดเองต้องมีความยาวไม่เกิน 39 อักขระ

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

รูปแบบ URI ที่กำหนดเองคือรูปแบบหนึ่งของ Deep Link ที่ใช้สคีมที่กำหนดเองเพื่อเปิดแอปของคุณ

ทางเลือกการใช้รูปแบบ URI ที่กำหนดเองใน Android

ใช้ SDK ของ Google Sign-In สำหรับ Android ที่ส่งการตอบสนอง OAuth 2.0 ไปยังแอปของคุณโดยตรง ทำให้ไม่จำเป็นต้องใช้ URI การเปลี่ยนเส้นทาง

วิธีย้ายข้อมูลไปยัง SDK ของ Google Sign-In สำหรับ Android

หากตอนนี้คุณใช้รูปแบบที่กำหนดเองสำหรับการผสานรวม OAuth ใน Android คุณจะต้องดำเนินการด้านล่างนี้ให้เสร็จสมบูรณ์เพื่อย้ายข้อมูลอย่างสมบูรณ์โดยใช้ SDK ของ Google Sign-In สำหรับ Android ที่แนะนํา

  1. โปรดอัปเดตโค้ดเพื่อใช้ Google Sign-In SDK
  2. ปิดใช้การสนับสนุนสคีมที่กำหนดเองในคอนโซล Google API

ทําตามขั้นตอนด้านล่างเพื่อย้ายข้อมูลไปยัง Android SDK ของ Google Sign-In

  1. อัปเดตโค้ดเพื่อใช้ Android SDK ของ Google Sign-In โดยทำดังนี้
    1. ตรวจสอบโค้ดเพื่อระบุตำแหน่งที่คุณส่งคำขอไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google หากใช้รูปแบบที่กำหนดเอง คำขอของคุณจะมีลักษณะดังต่อไปนี้
        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        
      com.example.app:/oauth2redirect คือ URI การเปลี่ยนเส้นทางรูปแบบที่กำหนดเองในตัวอย่างข้างต้น ดูคำจำกัดความพารามิเตอร์ redirect_uri สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับรูปแบบของค่ารูปแบบ URI ที่กำหนดเอง
    2. จดบันทึกพารามิเตอร์คำขอ scope และ client_id ซึ่งคุณจะต้องกำหนดค่า SDK Google Sign-In
    3. ทำตามวิธีการ เริ่มผสานรวม Google Sign-In เข้ากับแอป Android เพื่อตั้งค่า SDK คุณสามารถข้ามขั้นตอนรับรหัสไคลเอ็นต์ OAuth 2.0 ของเซิร์ฟเวอร์แบ็กเอนด์ได้เหมือนกับการนำ client_id ที่ได้จากขั้นตอนก่อนหน้ามาใช้ซ้ำ
    4. ทำตามวิธีการ การเปิดใช้การเข้าถึง API ฝั่งเซิร์ฟเวอร์ ซึ่งประกอบด้วยขั้นตอนต่อไปนี้
      1. ใช้เมธอด getServerAuthCode เพื่อเรียกข้อมูลรหัสการให้สิทธิ์สำหรับขอบเขตที่คุณกำลังขอสิทธิ์
      2. ส่งรหัสการตรวจสอบสิทธิ์ไปยังแบ็กเอนด์ของแอปเพื่อแลกเปลี่ยนกับโทเค็นเพื่อการเข้าถึงและรีเฟรช
      3. ใช้โทเค็นเพื่อการเข้าถึงที่ดึงมาเพื่อเรียกใช้ Google APIs ในนามของผู้ใช้
  2. ปิดใช้การรองรับรูปแบบที่กําหนดเองในคอนโซล Google API โดยทำดังนี้
    1. ไปที่รายการข้อมูลเข้าสู่ระบบ OAuth 2.0 แล้วเลือกไคลเอ็นต์ Android
    2. ไปที่ส่วนการตั้งค่าขั้นสูง ยกเลิกการเลือกช่องทำเครื่องหมายเปิดใช้สคีม URI ที่กำหนดเอง แล้วคลิกบันทึกเพื่อปิดใช้การรองรับรูปแบบ URI ที่กำหนดเอง
การเปิดใช้รูปแบบ URI ที่กำหนดเอง
หากทางเลือกที่แนะนำไม่ได้ผลสำหรับคุณ คุณจะเปิดใช้รูปแบบ URI ที่กำหนดเองสำหรับไคลเอ็นต์ Android ได้โดยทำตามวิธีการด้านล่าง
  1. ไปที่รายการข้อมูลเข้าสู่ระบบ OAuth 2.0 แล้วเลือกไคลเอ็นต์ Android
  2. ไปที่ส่วนการตั้งค่าขั้นสูง เลือกช่องทำเครื่องหมายเปิดใช้สคีม URI ที่กำหนดเอง แล้วคลิกบันทึกเพื่อเปิดใช้การสนับสนุนรูปแบบ URI ที่กำหนดเอง
ทางเลือกสำหรับการใช้รูปแบบ URI ที่กำหนดเองในแอป Chrome

ใช้ Chrome Identity API ซึ่งส่งการตอบสนองของ OAuth 2.0 ไปยังแอปของคุณโดยตรง ทำให้ไม่จำเป็นต้องใช้ URI การเปลี่ยนเส้นทาง

ยืนยันการเป็นเจ้าของแอป (Android, Chrome)

คุณยืนยันการเป็นเจ้าของแอปพลิเคชันเพื่อลดความเสี่ยงจากการถูกแอบอ้างเป็นแอปได้

Android

หากต้องการดำเนินการยืนยันให้เสร็จสมบูรณ์ คุณสามารถใช้บัญชีนักพัฒนาแอป Google Play ได้ (หากมี) และแอปได้รับการลงทะเบียนใน Google Play Console แล้ว แอปต้องมีคุณสมบัติตามข้อกำหนดต่อไปนี้จึงจะยืนยันได้สำเร็จ

  • คุณต้องมีแอปพลิเคชันที่ลงทะเบียนไว้ใน Google Play Console ที่มีชื่อแพ็กเกจและลายนิ้วมือใบรับรองการลงนาม SHA-1 เดียวกันกับไคลเอ็นต์ OAuth ของ Android ที่คุณกำลังทำการยืนยันให้เสร็จสมบูรณ์
  • คุณต้องมีสิทธิ์ผู้ดูแลระบบสําหรับแอปใน Google Play Console ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการการเข้าถึงใน Google Play Console

ในส่วนยืนยันการเป็นเจ้าของแอปของไคลเอ็นต์ Android ให้คลิกปุ่มยืนยันการเป็นเจ้าของเพื่อดำเนินการยืนยันให้เสร็จสมบูรณ์

หากการยืนยันสำเร็จ ระบบจะแสดงการแจ้งเตือนเพื่อยืนยันว่าขั้นตอนการยืนยันเสร็จสมบูรณ์แล้ว มิฉะนั้น ระบบจะแสดงข้อความแจ้งข้อผิดพลาด

หากต้องการแก้ไขการยืนยันที่ไม่สำเร็จ โปรดลองทำตามขั้นตอนต่อไปนี้

  • ตรวจสอบว่าแอปที่จะยืนยันเป็นแอปที่ลงทะเบียนไว้ใน Google Play Console
  • ตรวจสอบว่าคุณมีสิทธิ์ระดับผู้ดูแลระบบสำหรับแอปใน Google Play Console
Chrome

คุณจะใช้บัญชีนักพัฒนาแอป Chrome เว็บสโตร์เพื่อทำการยืนยันให้เสร็จสมบูรณ์ การยืนยันจะต้องเป็นไปตามข้อกำหนดต่อไปนี้

ในส่วนยืนยันการเป็นเจ้าของแอปของไคลเอ็นต์ส่วนขยาย Chrome ให้คลิกปุ่มยืนยันการเป็นเจ้าของเพื่อดำเนินการยืนยันให้เสร็จสมบูรณ์

หมายเหตุ: โปรดรอสักครู่ก่อนที่จะเสร็จสิ้นกระบวนการยืนยันหลังจากให้สิทธิ์เข้าถึงบัญชี

หากการยืนยันสำเร็จ ระบบจะแสดงการแจ้งเตือนเพื่อยืนยันว่าขั้นตอนการยืนยันเสร็จสมบูรณ์แล้ว มิฉะนั้น ระบบจะแสดงข้อความแจ้งข้อผิดพลาด

หากต้องการแก้ไขการยืนยันที่ไม่สำเร็จ โปรดลองทำตามขั้นตอนต่อไปนี้

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

ที่อยู่ IP ของ Loopback (macOS, Linux, Windows บนเดสก์ท็อป)

หากต้องการรับรหัสการให้สิทธิ์โดยใช้ URL นี้ แอปพลิเคชันของคุณต้องฟังในเว็บเซิร์ฟเวอร์ภายใน เรื่องนี้เป็นไปได้ในหลายๆ แพลตฟอร์ม แต่ไม่ใช่ทั้งหมด อย่างไรก็ตาม นี่คือกลไกที่แนะนำเพื่อรับรหัสการให้สิทธิ์หากแพลตฟอร์มของคุณรองรับ

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

การใช้งานที่แนะนำ แอป macOS, Linux และ Windows บนเดสก์ท็อป (แต่ไม่ใช่ Universal Windows Platform)
ค่าแบบฟอร์ม ตั้งค่าประเภทแอปพลิเคชันเป็นแอปบนเดสก์ท็อป

คัดลอก/วางด้วยตนเอง

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

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

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

เอกสารขอบเขต API ของ OAuth 2.0 มีรายการขอบเขตทั้งหมดที่คุณอาจใช้เพื่อเข้าถึง Google APIs

การรับโทเค็นเพื่อการเข้าถึง 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 (แนะนำ) การพิสูจน์โค้ดคือ Base64URL (ไม่มีระยะห่างจากขอบ) แฮช 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 จำเป็น

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

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 แบบ Loopback ที่เกี่ยวข้อง และเริ่ม Listener ของ HTTP บนพอร์ตที่พร้อมใช้งานแบบสุ่ม แทนที่ port ด้วยหมายเลขพอร์ตจริงที่แอปใช้ตรวจจับ

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

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

คุณใช้พารามิเตอร์นี้เพื่อวัตถุประสงค์หลายประการได้ เช่น การนำผู้ใช้ไปยังทรัพยากรที่ถูกต้องในแอปพลิเคชัน การส่ง nonces และการลดการปลอมแปลงคำขอข้ามเว็บไซต์ การใช้ค่า state จะช่วยให้มั่นใจได้ว่าการเชื่อมต่อขาเข้าเป็นผลมาจากคำขอการตรวจสอบสิทธิ์ เนื่องจาก redirect_uri มีการคาดเดาได้ หากคุณสร้างสตริงแบบสุ่มหรือเข้ารหัสแฮชของคุกกี้หรือค่าอื่นที่บันทึกสถานะของไคลเอ็นต์ คุณสามารถตรวจสอบการตอบสนองเพื่อให้แน่ใจว่าคำขอและคำตอบสร้างขึ้นในเบราว์เซอร์เดียวกัน ซึ่งช่วยป้องกันการโจมตีต่างๆ เช่น การปลอมแปลงคำขอข้ามเว็บไซต์ได้ ดูตัวอย่างวิธีสร้างและยืนยันโทเค็น 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 ของ Loopback

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 ดูบทความช่วยเหลือสำหรับผู้ดูแลระบบ Google Workspace ควบคุมว่าจะให้แอปของบุคคลที่สามและแอปภายในรายการใดเข้าถึงข้อมูล Google Workspace ได้บ้าง รับข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ผู้ดูแลระบบจำกัดการเข้าถึงขอบเขตทั้งหมดหรือขอบเขตที่จำกัดและละเอียดอ่อนได้จนกว่าจะมีการให้สิทธิ์เข้าถึงรหัสไคลเอ็นต์ OAuth อย่างชัดเจน

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) ที่เลิกใช้งานไปแล้วและไม่รองรับอีกต่อไป โปรดดูคำแนะนำในการย้ายข้อมูลเพื่ออัปเดตการผสานรวม

invalid_request

เกิดข้อผิดพลาดบางอย่างกับคำขอที่คุณส่ง ซึ่งอาจเกิดจากสาเหตุหลายประการดังนี้

  • คำขอมีรูปแบบไม่ถูกต้อง
  • คำขอไม่มีพารามิเตอร์ที่จำเป็น
  • คำขอใช้วิธีการให้สิทธิ์ที่ Google ไม่รองรับ ยืนยันว่าการผสานรวม OAuth ใช้วิธีการผสานรวมที่แนะนำ
  • รูปแบบที่กำหนดเองใช้สำหรับ URI การเปลี่ยนเส้นทาง : หากคุณเห็นข้อความแสดงข้อผิดพลาดแอป Chrome ไม่รองรับรูปแบบ URI ที่กำหนดเองหรือไม่ได้เปิดใช้รูปแบบ URI ที่กำหนดเองสำหรับไคลเอ็นต์ Android ของคุณ แสดงว่าคุณใช้รูปแบบ URI ที่กำหนดเองซึ่งไม่รองรับในแอป Chrome และปิดใช้อยู่โดยค่าเริ่มต้นบน Android ดูข้อมูลเพิ่มเติมเกี่ยวกับทางเลือกของรูปแบบ 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 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 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 API

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