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