logo
การพัฒนา
ภาพรวมพื้นที่นักพัฒนาพื้นที่ทำงานเอกสาร APIแนวปฏิบัติที่ดีบันทึกการเปลี่ยนแปลง
ค้นหา
ภาษาไทย
เอกสาร API / การเข้าสู่ระบบแอปส่วนขยาย / คำถามที่พบบ่อยและการแก้ปัญหา
07 · คำถามที่พบบ่อยและการแก้ปัญหา
อัปเดตล่าสุด：13 วันที่ผ่านมา

07 · คำถามที่พบบ่อยและการแก้ปัญหา

ตารางรวมรหัสข้อผิดพลาด

WsaVerificationError.code ที่ verifyWsa โยน

code สาเหตุที่พบบ่อย วิธีตรวจสอบ
InvalidSignature คีย์ลับผิด, โทเค็นถูกดัดแปลง, ใช้คีย์ลับ Tier1/Tier2 ผิด ยืนยันว่าคีย์ลับที่แบ็กเอนด์ใช้ตรงกับที่ลงทะเบียน/แจกจ่าย; คีย์ลับ per-app ให้ส่งเข้าเป็นสตริงตามเดิม อย่า hex decode
WrongAudience audience ไม่ตรงกับ aud ในโทเค็น audience ต้องเท่ากับ host ของ URL ลงทะเบียนอย่างแม่นยำ（เช่น app.example.com）ไม่รวมพอร์ต/โปรโตคอล
WrongIssuer คอนฟิก issuer ถูกแก้ คงค่าเริ่มต้น gptbots-workspace ไว้
Expired โทเค็นเกิน 5 นาที, นาฬิกาเซิร์ฟเวอร์คลาดเคลื่อน ซิงค์ NTP นาฬิกาเซิร์ฟเวอร์; wsa เป็นโทเค็นนำทางใช้ครั้งเดียว อย่าแคชแล้วใช้ซ้ำ
NotYetValid iat/nbf อยู่ในอนาคต มักเกิดจากนาฬิกาฝั่งออกโทเค็น/ฝั่งตรวจสอบไม่ซิงค์กันอย่างรุนแรง
MissingClaim ขาด exp/sub/role/workspace_id โทเค็นปกติของแพลตฟอร์มจะไม่ขาด; หากปรากฏแสดงว่าที่มาของโทเค็นน่าสงสัย
UnsupportedAlgorithm alg ไม่อยู่ใน whitelist ค่าเริ่มต้นเฉพาะ HS256; RS256 ต้อง algorithms:['RS256'] + publicKey อย่างชัดเจน
InvalidToken โทเค็นว่าง/โครงสร้างไม่ถูกต้อง/ถูกตัด ตรวจสอบว่าฟรอนต์เอนด์ดึง wsa ครบถ้วน, URL ถูกเลเยอร์กลางเขียนทับหรือไม่

ขั้นแลก /token（แบบ Pull）

code ความหมาย เงื่อนไขที่ทำให้เกิด
403209 Invalid grant code ขาดหาย, หมดอายุ หรือถูกใช้ไปแล้ว（replay）code ใช้ได้ครั้งเดียว
403210 Invalid verifier PKCE codeVerifier ไม่ตรงกับ code_challenge ตอนเริ่ม

sign-token แบบ Push（ฟรอนต์เอนด์ของพื้นที่ทำงานเรียกใช้ ทราบไว้เฉย ๆ ）

code ความหมาย เงื่อนไขที่ทำให้เกิด
40000 Parameter error URL ไม่ได้ลงทะเบียน, auth_mode ไม่ใช่ workspace_account
40100 Permission deny ยังไม่ล็อกอินหรือเซสชันหมดอายุ
40105 Require member of project ผู้คลิกไม่ใช่สมาชิกของพื้นที่ทำงานนี้
40320 Member not found บัญชีถูกยกเลิก/ลบ

FAQ

Q: ฉันควรเลือกแบบ Push หรือ Pull?
A: ทางเข้าอยู่ในหน้า「ส่วนขยาย」ของพื้นที่ทำงาน อยากทำ「แอปฝังตัว」→ Push（ง่ายที่สุด）หากแอปของคุณเป็นเว็บไซต์อิสระ อยากวางปุ่ม「ล็อกอินด้วย GPTBots」→ Pull（M-Auth, ปลอดภัยกว่า, wsa ไม่เข้าเบราว์เซอร์）ดู 02

Q: สามารถถอด JWT ที่ฟรอนต์เอนด์โดยตรงเพื่อดึงข้อมูลผู้ใช้ได้ไหม?
A: ถอดดูได้ แต่เชื่อถือเป็นตัวตนไม่ได้ — ไม่มีคีย์ลับก็ตรวจลายเซ็นไม่ได้ payload ปลอมได้ การตัดสินสิทธิ์ใด ๆ ต้องยึดผลของ verifyWsa ที่แบ็กเอนด์เป็นหลัก ดู 05 §5

Q: wsa หมดอายุแล้วทำอย่างไร?
A: wsa เป็นเพียงโทเค็นนำทางใช้ครั้งเดียว（5 นาที）ตอน Landing ตรวจสอบครั้งหนึ่ง แลกเป็นเซสชันของคุณเอง หลังจากนั้นใช้เซสชันของคุณทั้งหมด อย่าพึ่ง wsa อีก ครั้งถัดไปที่ผู้ใช้คลิกเปิดจากหน้าส่วนขยายจะได้ wsa ใบใหม่

Q: หน้า Landing consumeHandoff โยน「no handoff token present」?
A: แสดงว่า URL ปัจจุบันไม่มี ?wsa= — อาจเป็นผู้ใช้เข้าถึงโดยตรง หรือ wsa ถูกลบไปแล้วจากการแลกสำเร็จครั้งก่อน แยก「Landing ครั้งแรกที่พกโทเค็น」กับ「การเข้าถึงธรรมดา」ออกจากกัน กรณีหลังให้ไปที่การล็อกอิน/แบบไม่ระบุตัวตนของคุณเอง

Q: callback ของการเข้าสู่ระบบแบบ Pull รายงาน StateMismatch / MissingRequest?
A: MissingRequest = ไม่ได้เรียก startWorkspaceLogin ในเซสชันเบราว์เซอร์เดียวกันก่อน（PKCE verifier เก็บใน sessionStorage เปลี่ยนแท็บ/ล้าง storage ก็หาย）StateMismatch = state ของ callback ไม่ตรงกับที่เก็บไว้（การป้องกัน CSRF）ยืนยันว่าไม่ได้ข้ามอุปกรณ์/ข้ามเซสชัน

Q: การเข้าสู่ระบบแบบ Pull รายงาน CryptoUnavailable?
A: PKCE ต้องใช้ Web Crypto ซึ่งใช้ได้เฉพาะในบริบทที่ปลอดภัย（HTTPS หรือ localhost）ใช้ HTTPS หรือ localhost ในเครื่องเพื่อ debug

Q: redirect_uri รายงาน invalid_request / กลับไปหน้าเลือกองค์กร?
A: scheme + host ของ redirect_uri ต้องเท่ากับ client_id（URL ลงทะเบียน）อย่างแม่นยำ แอป https ตั้ง callback เป็น http ไม่ได้; host ต้องตรงกัน แพลตฟอร์มไม่มีวันเปลี่ยนเส้นทางไปยังที่อยู่ที่ไม่ผ่านการตรวจสอบ จึงกลับไปหน้าเลือกองค์กรพร้อม ?error=invalid_request

Q: คีย์ลับ per-app ใช้เป็น HMAC key อย่างไร? ต้อง base64/hex decode ไหม?
A: ส่งเข้าเป็นสตริงตามเดิม（ทั้ง SDK และแพลตฟอร์มใช้ไบต์ UTF-8 เป็น HMAC key โดยตรง）คีย์ลับ Tier 2 มีรูปแบบ wext_+64 hex ทั้งสตริงคือคีย์ลับ อย่า decode อีก

Q: โปรเจกต์ CommonJS ใช้ SDK ได้ไหม?
A: SDK เป็น ESM โปรเจกต์ CJS ใช้ import() แบบไดนามิก หรือเปลี่ยนโมดูลที่เกี่ยวข้องเป็น ESM

Q: เปลี่ยนไอคอน/ชื่ออย่างไร?
A: Tier 2 แก้ไขในการจัดการพื้นที่; Tier 1 ติดต่อฝ่ายปฏิบัติการของแพลตฟอร์มเพื่อแก้รายการในพจนานุกรม

Q: ถ้าผู้ดูแลปิดใช้งานแอปของฉันจะเป็นอย่างไร?
A: ผู้ดูแลองค์กรสามารถปิดใช้งานแอปในการจัดการพื้นที่（รวมถึงการมองเห็นแอปสาธารณะของแพลตฟอร์มในองค์กรนี้）หลังปิดใช้งาน สมาชิกขององค์กรนั้นจะไม่เห็นทางเข้าในหน้าส่วนขยาย และแพลตฟอร์มก็จะไม่ออก wsa ให้องค์กรนั้นอีก（ปฏิเสธทั้งแบบ Push และ Pull）

รายการเชื่อมต่อทดสอบ

  • audience == host ของ URL ลงทะเบียน（ที่มาของ WrongAudience ที่พบบ่อยที่สุด）
  • คีย์ลับของแบ็กเอนด์ตรงกับที่ลงทะเบียน/แจกจ่าย และอยู่ที่แบ็กเอนด์เท่านั้น
  • นาฬิกาเซิร์ฟเวอร์ซิงค์ NTP（Expired / NotYetValid ส่วนใหญ่มาจากนาฬิกา）
  • หลัง Landing history.replaceState ลบ wsa / code
  • แลกเป็นเซสชันของตัวเอง คำขอถัดไปไม่ส่งผ่าน wsa
  • แบบ Pull: บริบทที่ปลอดภัย HTTPS/localhost; redirect_uri อยู่โดเมนเดียวกับ client_id
  • แยกผู้เช่าหลายรายตาม workspace_id

อ้างอิง