วิธีการตั้งค่า Single Sign-On (SSO) ด้วย Keycloak ใน Element Web

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

คู่มือนี้ใช้ตัวให้บริการ OIDC ในตัวของ Synapse ซึ่งเป็นเส้นทางการติดตั้งใช้งานทั่วไป หากโฮมเซิร์ฟเวอร์ของคุณมอบหมายการตรวจสอบสิทธิ์ให้กับ Matrix Authentication Service (MAS) ให้ใช้การเรียกกลับของ MAS และการกำหนดค่าตัวให้บริการที่อธิบายไว้ด้านล่างแทน URL การเรียกกลับทั้งสองแตกต่างกัน คำแนะนำได้รับการตรวจสอบกับเอกสารการกำหนดค่า Element Web, คู่มือ OIDC ของ Synapse v1.144, คู่มือ SSO ของ MAS เวอร์ชันปัจจุบัน และคู่มือการดูแลระบบ Keycloak 26.8.0 เมื่อวันที่ 6 ตุลาคม 2026; การจัดแพ็กเกจการติดตั้งใช้งานและป้ายกำกับ UI อาจแตกต่างกันไปในแต่ละเวอร์ชัน

ขั้นแรก ให้ระบุว่าคุณใช้เส้นทางการตรวจสอบสิทธิ์แบบใด

ตรวจสอบเอกสารการตั้งค่าและการใช้งาน Synapse ก่อนสร้างไคลเอ็นต์ ฟังก์ชันเรียกกลับต้องเป็นของคอมโพเนนต์ที่สื่อสารกับ Keycloak ห้ามลงทะเบียน URL เว็บไซต์ของ Element เป็นฟังก์ชันเรียกกลับ

สิ่งที่คุณต้องการ

• URL HTTPS สาธารณะสำหรับ Synapse เช่นhttps://matrix.example.comและผู้ให้บริการโดเมน Keycloak ที่สามารถเข้าถึงได้https://sso.example.com/realms/companyเช่น
• สิทธิ์การเข้าถึงระดับผู้ดูแลระบบไปยังโดเมน Keycloak และการกำหนดค่าและบริการ Synapse
• การสำรองข้อมูลการตั้งค่าปัจจุบัน และวิธีการใช้บันทึกของ Synapse หรือคอนโซลเซิร์ฟเวอร์หากการเข้าสู่ระบบล้มเหลว
• การตัดสินใจเกี่ยวกับการจัดเตรียมบัญชี: ผู้ใช้ Keycloak รายใดบ้างที่สามารถเข้าสู่ระบบได้ รหัสยืนยันตัวตนใดที่ใช้ระบุตัวตนพวกเขา และจำเป็นต้องเก็บรักษาบัญชี Matrix ที่มีอยู่เดิมหรือไม่

กำหนดค่า Keycloak สำหรับ Synapse OIDC

1. สร้างไคลเอ็นต์ OIDC ที่เป็นความลับ

ในโดเมนที่ใช้สำหรับบัญชี Matrix ให้สร้างไคลเอ็นต์สำหรับ Synapse โดยใช้โปรโตคอล OpenID Connect เปิดใช้งานรหัสการอนุญาตหรือขั้นตอนมาตรฐานและการตรวจสอบสิทธิ์ไคลเอ็นต์ เพื่อให้ Synapse สามารถใช้รหัสลับไคลเอ็นต์ที่ปลายทางโทเค็นได้ ตั้งค่าไคลเอ็นต์เป็นค่าที่คุณจะใช้ใน Synapse ด้วย เช่นsynapse.

ตั้งค่า URI การเปลี่ยนเส้นทางที่ถูกต้องให้ตรงกับฟังก์ชันเรียกกลับของ Synapse:

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

แทนที่ชื่อโฮสต์ตัวอย่างด้วย URL พื้นฐานสาธารณะที่กำหนดค่าไว้จริงสำหรับ Synapse อย่าใช้สัญลักษณ์ตัวแทนแบบกว้างๆ เหมือนที่ใช้*ในสภาพแวดล้อมการใช้งานจริง Keycloak จะตรวจสอบ URI การเปลี่ยนเส้นทาง ดังนั้นหากโฮสต์ รูปแบบ เส้นทาง หรือเครื่องหมายทับท้ายไม่ตรงกัน อาจทำให้เกิดข้อผิดพลาด “ไม่อนุญาตให้ใช้ URI การเปลี่ยนเส้นทาง”

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

2. ยืนยันผู้ออกและรายการเรียกร้อง

ผู้ออกบัตรประจำตัวจะระบุโดเมน ไม่ใช่รูทของเซิร์ฟเวอร์ Keycloak สำหรับตัวอย่างนี้ ให้ใช้https://sso.example.com/realms/companyตรวจสอบให้แน่ใจว่าสามารถเข้าถึงการกำหนดค่า OpenID ของโดเมนได้ที่<issuer>/.well-known/openid-configurationและผู้ออกบัตรประจำตัวที่ประกาศไว้ตรงกับค่าที่คุณจะให้ Synapse อย่างถูกต้อง

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

ตั้งค่า Synapse

3. เพิ่มผู้ให้บริการ OIDC

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

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

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

4. สามารถกำหนดค่าการออกจากระบบผ่านช่องทางสำรองได้ (ถ้าต้องการ)

โดยค่าเริ่มต้น การออกจากระบบของบริการหนึ่งจะไม่ทำให้เซสชันเบราว์เซอร์ของบริการอื่นๆ สิ้นสุดลงด้วย หากคุณต้องการให้การแจ้งเตือนการออกจากระบบของ Keycloak สิ้นสุดเซสชัน Synapse ด้วย ให้เปิดใช้งานbackchannel_logout_enabled: trueภายใต้ผู้ให้บริการ Keycloak ใน Synapse และตั้งค่า URL การออกจากระบบ Backchannel ของ Keycloak เป็น:

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

ขั้นตอนนี้เป็นทางเลือกและขึ้นอยู่กับนโยบายการออกจากระบบและการตั้งค่าไคลเอ็นต์ของคุณ ทดสอบการออกจากระบบทั้งสองทิศทาง: การออกจากระบบ Synapse และการออกจากระบบ Keycloak อย่าคิดว่าการออกจากระบบ Element เพียงอย่างเดียวจะยุติเซสชัน Keycloak ได้

5. รีสตาร์ทและทดสอบ Synapse

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

กำหนดค่า Element Web

6. ตั้งค่า SSO ให้เป็นตัวเลือกเสริม หรือเปลี่ยนเส้นทางอัตโนมัติ

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

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

สำหรับการใช้งานที่ต้องการการเข้าสู่ระบบด้วย SSO เท่านั้น ให้ตั้งค่า"immediate": trueให้เริ่ม SSO สำหรับผู้ใช้ที่ยังไม่ได้ยืนยันตัวตนทั้งหมด วิธีนี้อาจทำให้การเข้าถึงรหัสผ่านหรือตัวเลือกการเข้าสู่ระบบอื่นๆ ทำได้ยากขึ้น ดังนั้นควรทดสอบการกู้คืนและการเข้าถึงของผู้ดูแลระบบก่อนที่จะบังคับใช้ หากผู้ใช้ต้องเลือกระหว่าง SSO กับวิธีการอื่น ให้ปิดใช้งานการเปลี่ยนเส้นทางอัตโนมัติและทดสอบว่าตัวเลือก SSO ปรากฏในขั้นตอนการเข้าสู่ระบบหรือไม่

หาก Synapse ใช้บริการตรวจสอบสิทธิ์แบบ Matrix Authentication Service

MAS เป็นบริการตรวจสอบสิทธิ์แยกต่างหากและสามารถทำหน้าที่เป็นไคลเอ็นต์ OIDC สำหรับ Keycloak ได้ ในสถาปัตยกรรมนั้น ให้กำหนดค่า URI การเปลี่ยนเส้นทางของ Keycloak เป็น โดยhttps://auth.example.com/upstream/callback/<provider-id>ที่รหัสผู้ให้บริการตรงกับการกำหนดค่า MAS กำหนดค่าผู้ให้บริการภายใต้ ของ MAS upstream_oauth2.providersจากนั้น Element จะใช้ขั้นตอนการตรวจสอบสิทธิ์แบบ MAS ของโฮมเซิร์ฟเวอร์ อย่าใช้ ของ Synapse /_synapse/client/oidc/callbackสำหรับการเชื่อมต่ออัปสตรีมนี้ MAS ต้องการผู้ให้บริการ OIDC ที่รองรับขั้นตอนรหัสการอนุญาต รูปแบบการกำหนดค่า รหัสผู้ให้บริการที่จำเป็น และขั้นตอนการย้ายข้อมูลจะแตกต่างจาก ในตัวของoidc_providersSynapse

ความเข้าใจผิดทั่วไปและวิธีแก้ไข

• “ฉันแค่ต้องเปลี่ยนการตั้งค่าของ Element เท่านั้น” Element ควบคุมการไหลของเบราว์เซอร์ ในขณะที่ Synapse หรือ MAS จัดการ OIDC ก่อนอื่นต้องกำหนดค่าผู้ให้บริการฝั่งโฮมเซิร์ฟเวอร์ให้ถูกต้องก่อน
• “การเข้าสู่ระบบ Keycloak สำเร็จแสดงว่าการแมปบัญชีถูกต้อง”การตรวจสอบสิทธิ์อาจสำเร็จได้แม้ว่าจะเลือก localpart หรือ profile claim ที่ไม่ถูกต้องก็ตาม ทดสอบกับผู้ใช้ที่ไม่ใช่ผู้ใช้จริงและตรวจสอบ Matrix ID ที่ได้
• “SSO จะปิดใช้งานรหัสผ่านและการลงทะเบียนโดยอัตโนมัติ”นโยบายเหล่านี้ถูกควบคุมโดยโฮมเซิร์ฟเวอร์และการใช้งาน โปรดตรวจสอบการตั้งค่าการเข้าสู่ระบบและการลงทะเบียนของ Synapse แยกต่างหาก และยืนยันนโยบายที่ได้รับการอนุมัติ
• “การออกจากระบบ Element จะทำให้ฉันออกจากระบบทุกที่”เซสชันของเบราว์เซอร์อาจยังคงใช้งานได้ใน Keycloak กำหนดค่าและทดสอบการออกจากระบบผ่านช่องทางสำรองหากจำเป็นต้องยุติเซสชันจากส่วนกลาง

รายการตรวจสอบการยืนยัน

• ไคลเอ็นต์ Keycloak ใช้กระบวนการตรวจสอบสิทธิ์ด้วยรหัส การตรวจสอบสิทธิ์ไคลเอ็นต์ และการเรียกกลับที่แม่นยำสำหรับ Synapse หรือ MAS
• URL ของผู้ออกใบรับรองตรงกับเมตาเดตาการค้นหาของโดเมน และรหัสลับไคลเอ็นต์จะถูกจัดเก็บไว้ที่ฝั่งเซิร์ฟเวอร์
• Synapse หรือ MAS จะเริ่มต้นทำงานโดยไม่มีข้อผิดพลาดในการกำหนดค่า OIDC และแสดงวิธีการเข้าสู่ระบบที่ต้องการ
• ผู้ใช้ทดสอบสามารถลงชื่อเข้าใช้จากเซสชันเบราว์เซอร์ใหม่ เข้าสู่บัญชี Matrix ที่คาดหวัง และสามารถดำเนินการเซสชัน Element ได้ตามปกติ
• พฤติกรรมการออกจากระบบ บัญชีที่มีอยู่ ข้อจำกัดในการลงทะเบียน และสิทธิ์การเข้าถึงของผู้ดูแลระบบในกรณีฉุกเฉิน ต้องเป็นไปตามนโยบายของคุณ

เอกสารอ้างอิงอย่างเป็นทางการ

• คู่มือการใช้งาน Synapse v1.144 OpenID Connect รวมถึงการตั้งค่าไคลเอ็นต์ Keycloak และฟังก์ชันเรียกกลับ (callback)
• การตั้งค่า Element Web: ตัวเลือกการเปลี่ยนเส้นทาง SSO
• บริการตรวจสอบสิทธิ์เมทริกซ์: การกำหนดค่าผู้ให้บริการ SSO ต้นทาง
• คู่มือการดูแลระบบเซิร์ฟเวอร์ Keycloak เวอร์ชัน 26.8.0