แก้ไขข้อผิดพลาด "โทเค็นไม่ถูกต้อง" ในการผสานรวม ONLYOFFICE กับ Nextcloud

ข้อความ“โทเค็นไม่ถูกต้อง” จาก ONLYOFFICE มักหมายความว่าทั้งสองฝั่งของการเชื่อมต่อไม่ได้ตรวจสอบความถูกต้องของ JSON Web Token (JWT) เดียวกัน ในการตั้งค่า Nextcloud จุดสำคัญคือมีเส้นทางโทเค็นหลายเส้นทาง ได้แก่ การกำหนดค่าตัวแก้ไขที่ส่งไปยังเบราว์เซอร์ คำขอขาเข้าไปยัง ONLYOFFICE Docs และคำขอขาออก เช่น การเรียกกลับไปยัง Nextcloud ความล้มเหลวในเส้นทางใดเส้นทางหนึ่งอาจแสดงผลคล้ายกันจากฝั่งผู้ใช้

มีรายละเอียดสำคัญอย่างหนึ่งก่อนที่คุณจะเริ่มเปลี่ยนแปลงการตั้งค่า: JWT ถูกเปิดใช้งานโดยค่าเริ่มต้นใน ONLYOFFICE Docs ตั้งแต่เวอร์ชัน 7.2และ Document Server สามารถสร้างรหัสลับได้โดยอัตโนมัติ ดังนั้นคำแนะนำเก่าๆ ที่บอกว่า “ปิดใช้งาน JWT ไว้” จึงไม่ใช่แนวทางที่เหมาะสมสำหรับการติดตั้งในปัจจุบัน คำแนะนำปัจจุบันของ ONLYOFFICE คือให้กำหนดค่ารหัสลับของคุณเองและใช้รหัสลับเดียวกันนั้นในตัวเชื่อมต่อ ดูคู่มือการกำหนดค่า JWT ของ ONLYOFFICE

คู่มือฉบับย่อ: สิ่งที่ควรตรวจสอบก่อนเป็นอันดับแรก

1. ยืนยันว่ารหัสลับที่ใช้ร่วมกันนั้นเหมือนกันจริง ๆ

การตรวจสอบความถูกต้องของ JWT ขึ้นอยู่กับรหัสลับที่ใช้ร่วมกัน ONLYOFFICE Docs จะลงนามโทเค็นด้วยรหัสลับนั้น และฝั่งผู้รับจะตรวจสอบลายเซ็นโดยใช้ค่าเดียวกัน ความแตกต่างเพียงตัวอักษรเดียว ช่องว่างท้าย การใช้ตัวแปรสภาพแวดล้อมเก่า หรือรหัสลับ Docker ที่สร้างขึ้นใหม่ ก็เพียงพอที่จะทำให้โทเค็นที่ดูเหมือนถูกต้องนั้นไม่ผ่านการตรวจสอบ

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

sudo -u www-data php occ config:app:get onlyoffice jwt_secret
sudo -u www-data php occ config:app:get onlyoffice jwt_header

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

สำหรับการติดตั้ง ONLYOFFICE Docs บนระบบ Linux โดยตรง ไฟล์การกำหนดค่าที่รองรับมีดังนี้:

/etc/onlyoffice/documentserver/local.json

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

หากคุณใช้งาน ONLYOFFICE Docs ใน Docker

ใช้ตัวแปรสภาพแวดล้อมของ Docker แทนการแก้ไขด้วยตนเองlocal.jsonภายในคอนเทนเนอร์ ONLYOFFICE ระบุว่า Docker สามารถสร้างการกำหนดค่า JWT ใหม่ได้ในระหว่างการเริ่มต้นระบบ อิมเมจอย่างเป็นทางการของ Docker รองรับJWT_ENABLED, JWT_SECRET, JWT_HEADER, และJWT_IN_BODYเอกสารประกอบอิมเมจ Docker ปัจจุบันระบุAuthorizationเป็นส่วนหัว JWT เริ่มต้น ดูได้จาก ที่เก็บ Docker DocumentServer อย่างเป็นทางการ

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=replace-with-a-long-random-secret
  - JWT_HEADER=Authorization

หลังจากเปลี่ยนตัวแปรสภาพแวดล้อมของ Docker แล้ว ให้สร้างคอนเทนเนอร์ใหม่เพื่อให้บริการที่กำลังทำงานอยู่ได้รับค่าเหล่านั้น การแก้ไขไฟล์ Compose โดยไม่สร้างคอนเทนเนอร์ใหม่จะไม่เปลี่ยนแปลงสภาพแวดล้อมที่มีอยู่เดิม

2. ตรวจสอบให้แน่ใจว่าส่วนหัวของ JWT ตรงกันทุกประการ

ความเข้าใจผิดที่พบบ่อยคือ ชื่อส่วนหัวเป็นเพียงแค่การตกแต่งเท่านั้น แต่ไม่ใช่ ONLYOFFICE Docs มีส่วนหัวโทเค็นขาเข้าและขาออกที่สามารถกำหนดค่าได้ และตัวเชื่อมต่อ Nextcloud ก็มีjwt_headerการตั้งค่าเช่นกัน ส่วนหัวทั้งสองต้องอธิบายเส้นทางการร้องขอเดียวกัน

เอกสารประกอบการใช้งาน API ของ ONLYOFFICE ในปัจจุบันระบุAuthorizationว่า Document Server เป็นค่าเริ่มต้นสำหรับคำขอ JWT ขาเข้า และเอกสารประกอบการผสานรวม Nextcloud อย่างเป็นทางการก็ระบุเช่นเดียวกันAuthorizationว่าเป็นค่าเริ่มต้นของตัวเชื่อมต่อปกติ ตัวอย่างเก่าและการติดตั้งที่มีอยู่แล้วอาจใช้AuthorizationJWTหรือค่าอื่นที่กำหนดค่าไว้อย่างชัดเจน ดังนั้นกฎที่ปลอดภัยจึงไม่ใช่ “ใช้สตริงเฉพาะเจาะจงเพียงสตริงเดียวเสมอ” แต่เป็นการทำให้การกำหนดค่าที่ใช้งานอยู่ตรงกันทั้งสองฝั่ง

รูปแบบการร้องขอก็มีความสำคัญเช่นกัน เอกสาร API ของ ONLYOFFICE แสดงโทเค็นส่วนหัวที่ส่งโดยใช้รูปแบบ Bearer สำหรับรายละเอียดโปรโตคอลพื้นฐาน โปรดดูเอกสารโทเค็นในส่วนหัวของ ONLYOFFICE

หากคุณตั้งใจใช้ส่วนหัวแบบกำหนดเอง ให้กำหนดค่าเดียวกันในทั้งสองผลิตภัณฑ์ หากคุณไม่มีเหตุผลที่จะปรับแต่ง การใช้ค่าเริ่มต้นปัจจุบันAuthorizationจะช่วยลดขั้นตอนการทำงานลงได้

3. ตรวจสอบว่ารีเวิร์สพร็อกซีเปลี่ยนแปลงเส้นทางโทเค็นหรือไม่

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

ใช้ลำดับการทดสอบเชิงปฏิบัติต่อไปนี้:

• ตรวจสอบว่าสามารถเข้าถึง URL ของเซิร์ฟเวอร์เอกสารสาธารณะได้จากโฮสต์ Nextcloud หรือไม่
• ตรวจสอบว่า URL ของเซิร์ฟเวอร์เอกสารภายใน (หากมีการกำหนดค่าไว้) สามารถระบุแหล่งที่มาได้จากเซิร์ฟเวอร์หรือคอนเทนเนอร์ของ Nextcloud
• ตรวจสอบว่า URL ภายในของ Nextcloud/พื้นที่จัดเก็บข้อมูล สามารถเข้าถึงได้จากโฮสต์หรือคอนเทนเนอร์ ONLYOFFICE Docs
• ตรวจสอบบันทึกการเข้าถึง/ข้อผิดพลาดของพร็อกซีขณะทำการตรวจสอบตัวเชื่อมต่อ
• หากพร็อกซีของคุณมีกฎเฉพาะสำหรับส่วนหัวนี้Authorizationโปรดตรวจสอบให้แน่ใจว่าได้ส่งต่อส่วนหัวนั้นไปแทนที่จะแทนที่หรือลบส่วนหัวนั้นออก

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

4. ใช้ฟังก์ชันตรวจสอบสถานะการทำงานของตัวเชื่อมต่อเอง

ตัวเชื่อมต่อ ONLYOFFICE อย่างเป็นทางการมีคำสั่งวินิจฉัยเฉพาะทาง:

sudo -u www-data php occ onlyoffice:documentserver --check

เอกสารประกอบการใช้งานตัวเชื่อมต่อระบุว่า การตรวจสอบนี้จะรายงานผลการเชื่อมต่อที่สำเร็จหรือสาเหตุของข้อผิดพลาด การตรวจสอบนี้มีประโยชน์มากกว่าการทดสอบเฉพาะหน้า Landing Page ของ Document Server เพราะเป็นการทดสอบการทำงานร่วมกันจากมุมมองของ Nextcloud ด้วย

หากการตรวจสอบระบุว่าสามารถเข้าถึง Document Server ได้ แต่การตรวจสอบโทเค็นล้มเหลว ให้กลับไปที่การตรวจสอบรหัสลับและส่วนหัว หากไม่สามารถเข้าถึงเซิร์ฟเวอร์ได้เลย ให้แก้ไขปัญหา DNS, การกำหนดเส้นทาง, ไฟร์วอลล์, TLS หรือ URL ภายในก่อนที่จะเสียเวลาไปกับการตรวจสอบ JWT เพิ่มเติม

5. ตรวจสอบเวลาเฉพาะเมื่อมีหลักฐานชี้ไปในทิศทางนั้น

โทเค็น JWT อาจมีข้อมูลที่เกี่ยวข้องกับเวลา และตัวเชื่อมต่อ Nextcloud จะเปิดเผยjwt_leewayและjwt_expirationตั้งค่าข้อมูลเหล่านั้น นั่นไม่ได้หมายความว่าคุณควรเพิ่มค่าความคลาดเคลื่อนก่อน นาฬิกาที่ผิดพลาดอย่างมีนัยสำคัญอาจทำให้โทเค็นที่ถูกต้องอื่นๆ ล้มเหลวได้ การเพิ่มค่าความคลาดเคลื่อนอาจซ่อนปัญหาด้านโครงสร้างพื้นฐานไว้ได้

เปรียบเทียบเวลา UTC บนโฮสต์หรือคอนเทนเนอร์ Nextcloud และ ONLYOFFICE:

date -u
timedatectl status

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

วิธีการตรวจสอบ JWT ในการทำงานของระบบนี้

ONLYOFFICE Docs ใช้ JWT เพื่อปกป้องการเริ่มต้นใช้งานตัวแก้ไขและคำขอระหว่างเซิร์ฟเวอร์ API ของมันแยกโทเค็นของเบราว์เซอร์ออกจากโทเค็นคำขอ HTTP ขาเข้าและขาออก สำหรับคำขอขาเข้า โทเค็นสามารถส่งมาในส่วนหัวหรือในส่วนเนื้อหาของคำขอสำหรับคำขอ POST ที่รองรับ สำหรับคำขอ GET ONLYOFFICE ได้อธิบายการจัดการโทเค็นตามส่วนหัวไว้ในเอกสาร โปรดดูเอกสารลายเซ็นคำขออย่างเป็นทางการ

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

ความเข้าใจผิดทั่วไป

“หาก /healthcheck ส่งค่ากลับเป็น true แสดงว่า JWT ต้องถูกต้อง”

ไม่ การตรวจสอบสถานะสุขภาพ (health endpoint) แสดงให้เห็นว่าบริการกำลังตอบสนอง แต่ไม่ได้พิสูจน์ว่าตัวเชื่อมต่อ Nextcloud และเซิร์ฟเวอร์เอกสารใช้รหัสลับ JWT และส่วนหัวเดียวกันการดำเนินการ:เรียกใช้occ onlyoffice:documentserver --checkและตรวจสอบการตั้งค่าตัวเชื่อมต่อที่มีผล

“ฉันสามารถแก้ไขไฟล์ local.json ภายในคอนเทนเนอร์ Docker แล้วก็เสร็จเรียบร้อย”

วิธีการนี้ค่อนข้างเปราะบางสำหรับการใช้งาน Docker ONLYOFFICE แนะนำให้ตั้งค่า JWT ผ่านตัวแปรสภาพแวดล้อมของ Docker เนื่องจากกระบวนการเริ่มต้นระบบอาจสร้างการกำหนดค่าใหม่วิธีแก้ไข:กำหนดค่าJWT_ENABLED, JWT_SECRET, และ เมื่อจำเป็นJWT_HEADERในการกำหนดค่าคอนเทนเนอร์ของคุณ แล้วสร้างคอนเทนเนอร์ใหม่

“AuthorizationJWT เป็นส่วนหัวที่จำเป็นเสมอ”

ไม่ การกำหนดค่า Document Server อย่างเป็นทางการในปัจจุบันระบุAuthorizationส่วนหัวเริ่มต้นไว้แล้ว แม้ว่าการใช้งานที่มีอยู่และตัวอย่างเก่าๆ อาจใช้ส่วนหัวอื่นที่กำหนดค่าไว้อย่างชัดเจนก็ตามการดำเนินการ:อ่านการกำหนดค่าที่ใช้งานอยู่ทั้งสองแบบและทำให้เหมือนกัน

“การปิดใช้งาน JWT คือวิธีแก้ปัญหาที่เร็วที่สุด”

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

รายการตรวจสอบการตรวจสอบขั้นสุดท้าย

• มีการตั้งค่ารหัสลับ JWT เดียวกันทั้งใน Nextcloud และ ONLYOFFICE Docs
• ชื่อส่วนหัวของ JWT ตรงกันทั้งสองฝั่ง
• การใช้งาน Docker นั้นใช้ตัวแปรสภาพแวดล้อมแบบถาวร ไม่ใช่การแก้ไขแบบเฉพาะหน้าภายในคอนเทนเนอร์
• สามารถเข้าถึง URL ของเซิร์ฟเวอร์สาธารณะและเซิร์ฟเวอร์ภายในได้ในทิศทางที่ใช้งาน
• ไม่มีกฎพร็อกซีใดที่ลบหรือเขียนทับส่วนหัว JWT โดยไม่คาดคิด
• ระบบ Nextcloud และ ONLYOFFICE มีนาฬิกาที่ซิงโครไนซ์กันแล้ว
• occ onlyoffice:documentserver --checkประสบความสำเร็จ
• เอกสารจริงสามารถเปิด แก้ไข บันทึกอัตโนมัติ ปิด และเปิดใหม่พร้อมกับการเปลี่ยนแปลงที่บันทึกไว้ได้

เมื่อข้อผิดพลาดเกี่ยวกับโทเค็นยังคงเกิดขึ้น

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

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