เชื่อมต่อ Element Web กับ Keycloak ผ่าน Synapse OIDC

ในการเพิ่มการเข้าสู่ระบบ Keycloak ลงใน Element Web ให้กำหนดค่า Keycloak เป็นผู้ให้บริการ OpenID Connect (OIDC) ใน Synapse จากนั้นตรวจสอบให้แน่ใจว่า Element Web ใช้โฮมเซิร์ฟเวอร์ Synapse นั้นอยู่ Synapse จะจัดการการเปลี่ยนเส้นทางการตรวจสอบสิทธิ์และการเรียกกลับ Element Web ไม่จำเป็นต้องใช้รหัสลับไคลเอ็นต์ของ Keycloak

ตัวอย่างสถานการณ์ (สมมติ):องค์กรขนาดเล็กแห่งหนึ่งใช้งาน Element Web ที่chat.example.org, Synapse ที่matrix.example.orgและ Keycloak ที่login.example.orgลำดับเดียวกันนี้ใช้ได้กับชื่อโฮสต์อื่นๆ แต่ URL ทุกตัวต้องตรงกับการกำหนดค่าสาธารณะจริงของคุณ ตัวอย่างนี้เป็นเพียงตัวอย่างประกอบ ไม่ใช่รายงานการตั้งค่าจริง

สิ่งที่คุณต้องมีก่อนเปลี่ยนการตั้งค่า

ใช้ URL HTTPS สาธารณะสำหรับ Keycloak และ Synapse เอกสาร OIDC ของ Synapse กำหนดให้ต้องมีต้นทางที่ปลอดภัยสำหรับผู้ให้บริการข้อมูลประจำตัว และต้องสามารถเข้าถึงฟังก์ชันเรียกกลับได้ผ่าน URL สาธารณะของ Synapse ยืนยันชื่อโดเมนใน Keycloak, Synapse public_baseurlและ URL ของโฮมเซิร์ฟเวอร์ที่ให้บริการแก่ Element Web หากมีพร็อกซีแบบย้อนกลับอยู่ด้านหน้าบริการใดบริการหนึ่ง พร็อกซีนั้นจะต้องส่งคำขอไปยังแบ็กเอนด์ที่ถูกต้องและรักษาโฮสต์และรูปแบบ HTTPS ภายนอกไว้

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

1. ลงทะเบียน Synapse เป็นไคลเอ็นต์ใน Keycloak

ในโดเมน Keycloak ที่ผู้ใช้ในองค์กรของคุณอาศัยอยู่ ให้สร้างไคลเอ็นต์ OpenID Connect สำหรับ Synapse ตัวอย่าง Keycloak อย่างเป็นทางการของ Synapse ใช้ไคลเอ็นต์แบบลับที่มี Client ID synapseตั้งค่า URI การเปลี่ยนเส้นทางที่ถูกต้องให้เป็น Callback นี้ โดยแทนที่ด้วยชื่อโฮสต์ Synapse ของคุณ:

https://matrix.example.org/_synapse/client/oidc/callback

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

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

2. เพิ่มผู้ให้บริการ Keycloak ลงใน Synapse

แก้ไขข้อมูลที่ใช้งานhomeserver.yamlอยู่ แทนที่ realm และ secret ด้านล่างด้วยค่าของคุณ และยืนยัน URL ของผู้ออกรหัสจากเอกสารการค้นหา OpenID ของ realm นั้น ตัวออกรหัส realm มาตรฐานของ Keycloak มีรูปแบบดังนี้:

https://login.example.org/realms/your-realm

สำหรับการใช้งานโดยใช้เอนด์พอยต์การค้นหามาตรฐานและข้อมูลยืนยันตามที่แสดงในตัวอย่าง Keycloak ของ Synapse รายการผู้ให้บริการจะเป็นดังนี้:

oidc_providers:
  - idp_id: keycloak
    idp_name: "Company Login"
    issuer: "https://login.example.org/realms/your-realm"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
    scopes: ["openid", "profile"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

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

หากมีการกำหนดค่าผู้ให้บริการข้อมูลประจำตัวอื่นๆ ไว้ ให้คงรายการเดิมไว้oidc_providersเพิ่มรายการนี้แทนที่จะแทนที่ผู้ให้บริการที่ไม่เกี่ยวข้อง ปกป้องรหัสลับไคลเอ็นต์เป็นความลับ และตั้งค่าสิทธิ์การเข้าถึงไฟล์ตามการใช้งานของคุณ ตรวจสอบความถูกต้องของการเยื้อง YAML จากนั้นรีสตาร์ท Synapse โดยใช้ขั้นตอนบริการหรือคอนเทนเนอร์สำหรับการติดตั้งของคุณ การติดตั้งแบบแพ็กเกจอาจมีส่วนประกอบ OIDC อยู่แล้ว สำหรับการติดตั้งใน virtualenv เอกสารของ Synapse จะอธิบายวิธีการติดตั้งmatrix-synapse[oidc]ปฏิบัติตามคำแนะนำของผู้ดูแลแพ็กเกจสำหรับวิธีการติดตั้งอื่นๆ

3. ตั้งค่า Point Element Web ให้อยู่ที่โฮมเซิร์ฟเวอร์เดียวกัน

Element Web config.jsonควรระบุเซิร์ฟเวอร์ Synapse เป็นโฮมเซิร์ฟเวอร์ ตัวอย่างเช่น ผ่านทาง < default_server_config.mHomeserver.base_urlhomeserver.h> ให้ใช้ URL ของโฮมเซิร์ฟเวอร์จริง ไม่ใช่ URL ของผู้ออกคีย์ของ Keycloak Element Web เป็นไคลเอ็นต์แบบคงที่: หลังจากเปลี่ยน URL ของโฮมเซิร์ฟเวอร์แล้ว ให้ปรับใช้ใหม่หรือโหลดการกำหนดค่าใหม่โดยใช้วิธีการโฮสติ้งของคุณ อย่าใส่รหัสลับไคลเอ็นต์ของ Keycloak ในไฟล์นี้ เพราะเบราว์เซอร์สามารถอ่านได้

ในตัวอย่างสมมุติ Element Web โฮสต์อยู่ที่https://chat.example.orgและเชื่อมต่อกับhttps://matrix.example.orgเมื่อผู้ใช้เลือกตัวเลือก SSO บนหน้าจอเข้าสู่ระบบของ Element เบราว์เซอร์ควรดำเนินการผ่านขั้นตอนการเข้าสู่ระบบของ Synapse ไปยังโดเมน Keycloak และกลับไปยังหน้าเรียกกลับของ Synapse ข้อความบนปุ่มและเค้าโครงหน้าจอเข้าสู่ระบบอาจแตกต่างกันไปตามเวอร์ชันของ Element Web และการกำหนดค่าเซิร์ฟเวอร์ ควรทดสอบพฤติกรรมมากกว่าที่จะยึดติดกับป้ายกำกับเฉพาะ

4. ทดสอบด้วยบัญชีเดียวก่อนบังคับใช้ SSO

เปิด Element Web ในหน้าต่างเบราว์เซอร์แบบส่วนตัว แล้วเลือกตัวเลือกการเข้าสู่ระบบ SSO ลงชื่อเข้าใช้ด้วยผู้ใช้ Keycloak สำหรับทดสอบ อนุมัติการเข้าถึงที่ร้องขอหากมีข้อความแจ้ง และยืนยันว่าเบราว์เซอร์กลับไปยังโฮมเซิร์ฟเวอร์ที่ต้องการและเปิดบัญชี Matrix ที่คาดหวัง ตรวจสอบว่า Matrix ID ที่ได้มีส่วน localpart ที่ถูกต้อง ตรวจสอบบันทึกของ Synapse และ Keycloak หากเบราว์เซอร์แสดงข้อผิดพลาด

หากการเปลี่ยนเส้นทางล้มเหลว ให้เปรียบเทียบ URL การเรียกกลับใน Keycloak กับ URL การเรียกกลับสาธารณะของ Synapse แบบตัวอักษรต่อตัวอักษร ข้อความ “issuer mismatch” ชี้ไปยังผู้ออกใบรับรองโดเมนที่ไม่ถูกต้องหรือชื่อโฮสต์พร็อกซีแบบย้อนกลับ ชื่อผู้ใช้ที่หายไปหรือข้อผิดพลาดในการแมปหมายความว่าข้อมูลการอ้างสิทธิ์ที่กำหนดค่าไว้หายไปหรือไม่เหมาะสม ตรวจสอบข้อมูลการอ้างสิทธิ์ของผู้ใช้ทดสอบและปรับการแมปอย่างรอบคอบ หากเบราว์เซอร์เข้าถึง Keycloak ได้แต่ไม่ส่งกลับ ให้ตรวจสอบใบรับรอง TLS และการกำหนดเส้นทางพร็อกซีสำหรับการเรียกกลับของ Synapse

การออกจากระบบ (ไม่บังคับ): Synapse รองรับการออกจากระบบผ่านช่องทาง OIDC หากต้องการใช้งาน ให้ตั้งค่าbackchannel_logout_enabled: trueภายใต้ผู้ให้บริการนี้ และกำหนดค่า URL การออกจากระบบผ่านช่องทางของ Keycloak เป็นhttps://matrix.example.org/_synapse/client/oidc/backchannel_logoutSynapse ยังได้จัดทำเอกสารเกี่ยวกับการเปิดใช้งานตัวเลือก "ต้องใช้เซสชัน" ใน Keycloak ซึ่งจะจัดการการแจ้งเตือนการออกจากระบบที่เริ่มต้นโดยผู้ให้บริการ ไม่จำเป็นสำหรับการใช้งานการเข้าสู่ระบบ SSO ครั้งแรก

ก่อนเริ่มใช้งาน:ตัดสินใจว่า SSO ควรสร้างผู้ใช้ Matrix ใหม่หรือตรวจสอบสิทธิ์เฉพาะบัญชีที่คุณจัดเตรียมไว้แยกต่างหาก จากนั้นตรวจสอบตัวเลือก OIDC ของ Synapse สำหรับเวอร์ชันที่ติดตั้งของคุณ ป้ายกำกับการกำหนดค่าและ UI การจัดการของ Keycloak อาจเปลี่ยนแปลงไปในแต่ละเวอร์ชัน ขั้นตอนในที่นี้เป็นไปตามเอกสาร OIDC ของ Synapse ที่เผยแพร่เมื่อวันที่ 10 ตุลาคม 2026 และสมมติว่าใช้โดเมน Keycloak มาตรฐานและการใช้งาน Synapse โดยใช้รูปแบบผู้ให้บริการที่ระบุไว้ในเอกสาร โปรดศึกษาคู่มือ Synapse OpenID Connect และ Keycloakคู่มืออ้างอิงการกำหนดค่า Synapseและเอกสารอย่างเป็นทางการของ Keycloakก่อนที่จะใช้การตั้งค่าเฉพาะเวอร์ชัน เมื่อบัญชีทดสอบลงชื่อเข้าใช้ได้อย่างถูกต้องและคุณมีเส้นทางการกู้คืนแล้ว ให้บันทึกการเรียกกลับขั้นสุดท้าย ผู้ออกบัตร และการแมปการอ้างสิทธิ์สำหรับผู้ดูแลระบบ

ฝากความเห็น

แก้ไขข้อผิดพลาดเกี่ยวกับสิทธิ์การดูแลระบบห้อง Matrix โดยการดำเนินการ

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

ทำให้เซิร์ฟเวอร์ Matrix Synapse ของคุณสามารถเชื่อมต่อกับ Federation ได้

ทำให้เซิร์ฟเวอร์ Matrix Synapse ของคุณสามารถเชื่อมต่อกับ Federation ได้

ตั้งค่าการค้นหา Synapse, HTTPS และการกำหนดเส้นทางพร็อกซี เพื่อให้โฮมเซิร์ฟเวอร์ Matrix อื่นๆ สามารถค้นหาและติดต่อเซิร์ฟเวอร์ของคุณได้

เชื่อมต่อ Element Web กับ Keycloak ผ่าน Synapse OIDC

กำหนดค่าไคลเอ็นต์ Keycloak OIDC และผู้ให้บริการ Synapse เพื่อให้ผู้ใช้ Element Web สามารถลงชื่อเข้าใช้ผ่านเซิร์ฟเวอร์ยืนยันตัวตนของคุณได้โดยไม่ต้องเปิดเผยรหัสลับไคลเอ็นต์

ตั้งค่าการสำรองข้อมูลคีย์ Element และการลงนามไขว้ให้ปลอดภัย

ตั้งค่าการสำรองข้อมูลคีย์ Element และการลงนามไขว้ให้ปลอดภัย

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

หยุดปัญหาหน่วยความจำ Synapse Matrix ล่มระหว่างการซิงค์ข้อมูลไคลเอ็นต์

วินิจฉัยปัญหาหน่วยความจำไม่เพียงพอของ Synapse ระหว่างการซิงค์ ปรับการแคชอย่างปลอดภัย ระบุคำขอที่ค้างอยู่ และตรวจสอบการใช้งานหน่วยความจำที่เสถียร

แก้ไขข้อผิดพลาดเกี่ยวกับใบรับรอง TLS ของ Synapse Federation

ตรวจสอบความล้มเหลวของใบรับรองการรวมระบบ Trace Matrix ไปยังเซิร์ฟเวอร์ที่ถูกต้อง ซ่อมแซมห่วงโซ่ TLS หรือความเชื่อถือ CA และตรวจสอบการแก้ไขโดยไม่ต้องปิดใช้งานการตรวจสอบความปลอดภัย

วางเซิร์ฟเวอร์ Synapse Matrix ไว้หลัง Cloudflare อย่างปลอดภัย

วางเซิร์ฟเวอร์ Synapse Matrix ไว้หลัง Cloudflare อย่างปลอดภัย

กำหนดเส้นทางไคลเอ็นต์และเฟเดอเรชันของ Matrix ผ่าน Cloudflare บน HTTPS 443 เพื่อรักษาการค้นหา Synapse และหลีกเลี่ยงการแคชการรับส่งข้อมูล API หรือการทำให้การอัปโหลดสื่อหยุดชะงัก

กู้คืน Matrix Synapse อย่างปลอดภัยด้วยการสำรองข้อมูล PostgreSQL

สำรองข้อมูล Synapse ด้วย pg_dump ป้องกันคีย์ลงนามและสื่อบันทึกข้อมูล และกู้คืนลงในฐานข้อมูล PostgreSQL ที่สะอาดโดยไม่ใช้คีย์แบบใช้ครั้งเดียวที่หมดอายุแล้ว

เรียกใช้ Mjölnir เป็นบอทควบคุมห้องสนทนาใน Matrix ด้วย Docker

เรียกใช้ Mjölnir เป็นบอทควบคุมห้องสนทนาใน Matrix ด้วย Docker

ตั้งค่า Mjölnir ด้วยบัญชี Matrix เฉพาะ, ห้องจัดการที่เข้ารหัส, Docker Compose, รายการนโยบาย และการตรวจสอบสิทธิ์

เปิดใช้งาน Native Matrix Sliding Sync เพื่อการโหลดบนมือถือที่เร็วขึ้น

เปิดใช้งาน Native Matrix Sliding Sync เพื่อการโหลดบนมือถือที่เร็วขึ้น

ข้ามขั้นตอนการใช้พร็อกซีที่เลิกใช้งานแล้ว และกำหนดค่า Sliding Sync ที่มีอยู่ใน Synapse ตรวจสอบการค้นหาไคลเอ็นต์ จากนั้นวัดการโหลดรายการห้องและพฤติกรรมการเชื่อมต่อใหม่บนโทรศัพท์ที่ใช้งานร่วมกันได้