คู่มือการติดตั้งใช้งาน OAuth 2.1

คู่มือนี้จะอธิบายวิธีให้สิทธิ์แพลตฟอร์มแอปที่เชื่อมต่อเพื่อเข้าถึงบริการของคุณอย่างปลอดภัย สำหรับการผสานรวม MCP ของแอปที่เชื่อมต่อ เราขอแนะนำอย่างยิ่งให้ใช้ OAuth 2.1 ซึ่งเป็นมาตรฐานอุตสาหกรรมสำหรับการให้สิทธิ์ที่ได้รับมอบสิทธิ์ พร้อมด้วย Proof Key for Code Exchange (PKCE) เพื่อให้มั่นใจว่าข้อมูลผู้ใช้มีความปลอดภัยสูงสุดและมีความน่าเชื่อถือในขั้นตอน "Agentic" แพลตฟอร์มแอปที่เชื่อมต่อรองรับประเภทการให้สิทธิ์รหัสการให้สิทธิ์ที่มีพารามิเตอร์ Proof Key for Code Exchange (PKCE)

PKCE เป็นข้อบังคับสำหรับ OAuth 2.1 ทั้งหมด และไม่บังคับสำหรับ OAuth2.0

หากต้องการเปิดใช้การค้นหาอัตโนมัติและปรับปรุงกระบวนการเริ่มต้นใช้งาน เซิร์ฟเวอร์การให้สิทธิ์ของคุณต้องรองรับส่วนขยายข้อมูลเมตาของเซิร์ฟเวอร์การให้สิทธิ์ หรือที่เรียกว่า OAuth Discovery

วิธีที่ Gemini MCP ดึงข้อมูล JSON การกำหนดค่า

คอนโซล Gemini MCP จะพยายามดึงข้อมูล JSON การกำหนดค่าจาก URL ต่อไปนี้ตามลำดับที่แสดงในส่วนนี้

หาก URL ของเซิร์ฟเวอร์การให้สิทธิ์อยู่ที่ระดับบนสุดของโดเมน (เช่น https://auth.example.com) Gemini จะเพิ่มไดเรกทอรี "well-known" มาตรฐานต่อท้ายโดเมนของคุณและค้นหาเซิร์ฟเวอร์ตามลำดับต่อไปนี้

  1. https://auth.example.com/.well-known/oauth-authorization-server
  2. https://auth.example.com/.well-known/openid-configuration

หาก URL ของเซิร์ฟเวอร์การให้สิทธิ์อยู่ในไดเรกทอรีย่อยหรือเส้นทางที่เฉพาะเจาะจงในโดเมนของคุณ เช่น https://auth.example.com/realms/master Gemini จะเพิ่มเส้นทาง "well-known" เดียวกันต่อท้ายไดเรกทอรีย่อยนั้นโดยตรงตามลำดับต่อไปนี้

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration (รองรับเส้นทางที่ฝัง)

ความสามารถ JSON ที่จำเป็น

การตอบกลับข้อมูลเมตาต้องมีช่องต่อไปนี้ การผสานรวมจะล้มเหลวหากไม่มีช่องที่ต้องกรอกหรือไม่พบประเภทที่ถูกต้อง

authorization_endpoint
ต้องเป็นสตริง URL ที่ถูกต้อง
token_endpoint
ต้องเป็นสตริง URL ที่ถูกต้อง
response_types_supported
ต้องมีสตริง code
registration_endpoint

ในตอนนี้ Play Console อาศัยไคลเอ็นต์แบบไดนามิก

การลงทะเบียน (RFC 7591) คุณต้องระบุปลายทางการลงทะเบียนในข้อมูลเมตา หรือป้อนรหัสไคลเอ็นต์/รหัสลับไคลเอ็นต์โดยตรงใน UI ของ Play Console

หากเซิร์ฟเวอร์การให้สิทธิ์ไม่รองรับการจดทะเบียนไคลเอ็นต์ไดนามิก (DCR) คุณต้องใช้และป้อนข้อมูลในช่องรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์ด้วยตนเองภายใน UI ของ Play Console เพื่อผสานรวมให้เสร็จสมบูรณ์

หากการติดตั้งใช้งานรองรับ Proof Key for Code Exchange (PKCE) หรือเซสชันแบบถาวร คุณต้องใส่ช่องความสามารถที่เกี่ยวข้อง (เช่น Challenge Methods และ ประเภทการให้สิทธิ์) ใน JSON การค้นพบ ซึ่งจะช่วยให้มั่นใจได้ว่าอุปกรณ์จะเข้ากันได้กับมาตรฐานความปลอดภัยและการเชื่อมต่อของ Gemini หากรองรับขอบเขต คุณต้องใส่ฟิลด์ scopes_supported

ตัวอย่างการกำหนดค่า

ต่อไปนี้คือการตอบกลับ JSON ที่ถูกต้องซึ่งตรงตามข้อกำหนดของลูกค้า

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

ในกรณีที่คุณรวม PKCE ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างสิ่งที่อาจรวมอยู่ในบล็อก JSON

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

ในกรณีที่คุณรวมช่อง scopes_supported ข้อมูลโค้ดต่อไปนี้จะแสดงตัวอย่างสิ่งที่อาจรวมอยู่ในบล็อก JSON

"scopes_supported": ["mcp", "cart.order"],

ขั้นตอนรหัสการให้สิทธิ์ (เวอร์ชันที่เข้าใจง่าย)

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

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

    คำขอนี้ประกอบด้วยรหัสไคลเอ็นต์ (หรือสร้างขึ้นโดยอัตโนมัติด้วย DCR), URI เปลี่ยนเส้นทางของ Gemini และพารามิเตอร์ PKCE ที่สำคัญ (code_challenge และ code_challenge_method)

    เพิ่ม URL ต่อไปนี้ลงในรายการที่อนุญาตสำหรับการตั้งค่า OAuth

    • https://oauth-redirect.googleusercontent.com/r/*
    • https://oauth-redirect-sandbox.googleusercontent.com/r/*
    • https://oauth-redirect-test.googleusercontent.com/r/*
    • https://oauth-redirect.googleusercontent.com/a/*
    • https://oauth-redirect-sandbox.googleusercontent.com/a/*
    • https://oauth-redirect-test.googleusercontent.com/a/*

  2. ความยินยอมของผู้ใช้: เซิร์ฟเวอร์การให้สิทธิ์จะตรวจสอบคำขอ ตรวจสอบสิทธิ์ผู้ใช้ (เข้าสู่ระบบ) และขอให้ผู้ใช้ให้สิทธิ์แพลตฟอร์มของ Google ในการเข้าถึงข้อมูลหรือบริการของผู้ใช้

  3. การให้สิทธิ์รหัส: หลังจากผู้ใช้ให้ความยินยอม เซิร์ฟเวอร์ของคุณจะเปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้กลับไปยัง RedirectURI ของ Gemini โดยเพิ่มรหัสการให้สิทธิ์ชั่วคราวต่อท้าย URL

  4. การแลกเปลี่ยนโทเค็น: แบ็กเอนด์ที่อยู่เบื้องหลัง Gemini จะส่งคำขอ POST ไปยังปลายทางโทเค็นของคุณเพื่อแลกเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึง

  5. ได้รับสิทธิ์เข้าถึง: ปลายทางโทเค็นจะยืนยันรหัสและพารามิเตอร์ PKCE ออกโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช (ไม่บังคับ) แล้วส่งกลับไปยัง Gemini

ข้อกำหนดที่สำคัญของ PKCE

PKCE เพิ่มชั้นการรักษาความปลอดภัยเพื่อป้องกันการสกัดกั้นรหัสการให้สิทธิ์โดยไม่ได้รับอนุญาต

  • code_verifier: สตริงแบบสุ่มที่เข้ารหัสซึ่ง Gemini สร้างขึ้นเมื่อเริ่มขั้นตอน ข้อมูลนี้จะเก็บไว้เป็นส่วนตัว
  • code_challenge: การเปลี่ยนรูปแบบของ code_verifier ซึ่งมักจะเป็นการแฮช SHA256 ซึ่งจะส่งแบบสาธารณะตามที่อธิบายไว้ในขั้นตอนที่ 1 ของขั้นตอนรหัสการให้สิทธิ์
  • การตรวจสอบความถูกต้อง: ปลายทางโทเค็น (อธิบายไว้ในขั้นตอนที่ 4 ของขั้นตอนรหัสการให้สิทธิ์) ต้องตรวจสอบว่า code_verifier ที่ได้รับเมื่อเปลี่ยนรูปแบบแล้วตรงกับ code_challenge เดิม

การแก้ไขข้อบกพร่อง

ดูข้อมูลข้อผิดพลาดในการลิงก์โดยละเอียดได้ใน Logs Explorer หากต้องการเปิดใช้และดูข้อผิดพลาด ให้ทำตามวิธีการในหัวข้อตรวจสอบข้อผิดพลาดในการลิงก์บัญชีในโปรเจ็กต์ Google Console

ข้อกำหนดในการกำหนดค่าการลิงก์บัญชี Google

อ่านคำแนะนำเกี่ยวกับ API ต่อไปนี้เพื่อดูข้อมูลเกี่ยวกับการกำหนดค่าการลิงก์บัญชี Google

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

ฟิลด์กำหนดค่า

คำอธิบาย

ความรับผิดชอบของนักพัฒนาแอป

รหัสไคลเอ็นต์และข้อมูลลับ

ข้อมูลเข้าสู่ระบบที่ไม่ซ้ำกันซึ่งเซิร์ฟเวอร์การให้สิทธิ์สร้างขึ้นสำหรับแพลตฟอร์มแอปที่เชื่อมต่อโดยเฉพาะ รหัสลับไคลเอ็นต์คือข้อมูลเข้าสู่ระบบเพื่อรักษาความปลอดภัย (รหัสผ่าน) ที่เชื่อมโยงกับรหัสไคลเอ็นต์

หมายเหตุ: หากนักพัฒนาแอปเป็นผู้ออกรหัสไคลเอ็นต์ นักพัฒนาแอปต้องระบุรหัสดังกล่าว หาก Google เป็นผู้ออกรหัสไคลเอ็นต์ นักพัฒนาแอปอาจต้องลงทะเบียนหรือยืนยันรหัสลับ

ใช้รหัสที่แพลตฟอร์มระบุในคำขอการให้สิทธิ์ทั้งหมด

ปลายทางการให้สิทธิ์

URL สำหรับเปลี่ยนเส้นทางผู้ใช้เพื่อตรวจสอบสิทธิ์และให้ความยินยอม

โฮสต์ปลายทาง เช่น https://yourdomain.com/oauth/authorize

ปลายทางของโทเค็น

ปลายทางแบ็กเอนด์เพื่อแลกเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึง/โทเค็นการรีเฟรช และเพื่อรีเฟรชโทเค็นที่หมดอายุ

โฮสต์ปลายทางนี้ เช่น https://yourdomain.com/oauth/token

ปลายทางการเพิกถอน
ไม่บังคับ

URL สำหรับแจ้งเตือนระบบของคุณให้ยกเลิกโทเค็นเมื่อผู้ใช้ยกเลิกการเชื่อมต่อ

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

ดูข้อมูลเพิ่มเติมได้ที่การยกเลิกการลิงก์บัญชี

โฮสต์ปลายทาง เช่น https://yourdomain.com/oauth/revoke

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

URI การเปลี่ยนเส้นทาง

URL Callback ที่เฉพาะเจาะจงซึ่งแพลตฟอร์มระบุไว้ โดยเซิร์ฟเวอร์การให้สิทธิ์จะส่งรหัสกลับมาหลังจากได้รับความยินยอม

กำหนดค่าเซิร์ฟเวอร์การให้สิทธิ์ให้ยอมรับเฉพาะ URI การเปลี่ยนเส้นทางที่ลงทะเบียนอย่างเป็นทางการจากแพลตฟอร์ม

รีเฟรช

/token กับ grant_type=refresh_token

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

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

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

ประเภทการตอบกลับ

โดยต้องกำหนดค่าเป็น CODE เพื่อรองรับขั้นตอนรหัสการให้สิทธิ์

ขอบเขต

ชุดสิทธิ์และระดับการเข้าถึงที่เฉพาะเจาะจงซึ่งกำหนดสิ่งที่โทเค็นได้รับอนุญาตให้ทำ โดยต้องกำหนดไว้ล่วงหน้าในการกำหนดค่าเพื่อให้ Google ขอโทเค็นเหล่านี้ได้ในระหว่างแฮนด์เชคการให้สิทธิ์ครั้งแรก

คุณจะต้องระบุรายการขอบเขตเริ่มต้น (เช่น openid, profile, email) ที่แพลตฟอร์มแอปที่เชื่อมต่อควรขอเมื่อเริ่มขั้นตอน

ขอบเขตที่ขอควรลดลงให้มากที่สุด (หลักการให้สิทธิ์ขั้นต่ำที่สุด) แต่เพียงพอสำหรับเส้นทางของผู้ใช้ที่สำคัญ (CUJ) ที่การผสานรวม MCP ของคุณรองรับ

ชิ้นงาน UI: โลโก้

โลโก้นักพัฒนาแอปที่จะแสดงในหน้าจอการลิงก์บัญชีและหน้าจอขอความยินยอม

ต้องเป็นรูปภาพเวกเตอร์สี่เหลี่ยมจัตุรัส (SVG) ที่มีลักษณะเป็นวงกลมและมีขนาดอย่างน้อย 500 x 500 พิกเซล เช่น ดู https://[partner-domain]/assets/logo.svg หรือไฟล์ SVG แบบดิบ

การลิงก์แอปที่มาพร้อมเครื่อง (App Flip)

เราไม่แนะนำให้ใช้ WebView มาตรฐานเพื่อรองรับการลิงก์บัญชีจากแอปพลิเคชัน Android หรือ iOS แบบเนทีฟโดยตรง แต่เราขอแนะนำอย่างยิ่งให้ใช้ App Flip เพื่อประสบการณ์ของผู้ใช้ที่ราบรื่น

ดูข้อมูลเพิ่มเติมได้ที่การลิงก์บัญชี Google กับ App Flip ที่ใช้ OAuth

ดำเนินการยืนยัน Play Store และ App Store ให้เสร็จสมบูรณ์ และฝัง URI การเปลี่ยนเส้นทางของ Google ลงในแอปพลิเคชันแบบเนทีฟโดยตรงเพื่อให้การเปลี่ยนเส้นทางการให้สิทธิ์แบบแอปต่อแอปมีความปลอดภัย

อายุการใช้งานโทเค็น

(ไม่บังคับ) ระยะเวลาที่โทเค็นเพื่อการเข้าถึงจะใช้งานได้ก่อนที่จะต้องรีเฟรช มีประโยชน์สำหรับการกำหนดค่านโยบายการหมดเวลาใน GAL

เวลาหมดอายุที่พบบ่อยมีตั้งแต่เป็นนาที ชั่วโมง วัน ขึ้นอยู่กับความต้องการด้านความปลอดภัย เช่น 30 days)

ข้อผิดพลาดในการผสานรวมที่พบบ่อย

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

  • ไม่มีสิทธิ์ "code": ระบบอัตโนมัติของแพลตฟอร์ม Gemini จะตรวจสอบ response_types_supported เพื่อหาค่า "code" อย่างชัดเจน
  • ไม่มีปลายทางการลงทะเบียน: แม้ว่าเซิร์ฟเวอร์จะรองรับเอกสารข้อมูลเมตาของรหัสไคลเอ็นต์ แต่ปัจจุบันแอป Gemini (ซึ่งทำหน้าที่เป็นไคลเอ็นต์ OAuth ที่เชื่อมต่อกับเซิร์ฟเวอร์) กำหนดให้ต้องมี registration_endpoint เฉพาะใน JSON การค้นหา
  • ข้อผิดพลาดที่ไม่ใช่ 200: หากกลไกการค้นพบข้อมูลเมตาอัตโนมัติของ Gemini เข้าถึง well-known URL ของคุณและได้รับข้อผิดพลาด 404 หรือ 500 ระบบจะไม่พยายามคาดเดา URL อื่นๆ โปรดตรวจสอบว่า Discovery URL สามารถเข้าถึงได้แบบสาธารณะ