วิธีตั้งค่า Keycloak ให้เป็น IDP สำหรับ ownCloud Infinite Scale

คู่มือนี้เชื่อมต่อ ownCloud Infinite Scale (oCIS) กับ Keycloak โดยใช้ OpenID Connect (OIDC) ซึ่งเป็นเลเยอร์การยืนยันตัวตนที่สร้างขึ้นบน OAuth 2.0 Keycloak ทำหน้าที่ยืนยันตัวตนผู้ใช้ ในขณะที่ oCIS เชื่อถือข้อมูลประจำตัวและข้อมูลการเข้าถึงที่ Keycloak ออกให้ การลงชื่อเข้าใช้ผ่านเบราว์เซอร์ใช้การเปลี่ยนเส้นทาง HTTPS ในขณะที่ oCIS ยังจำเป็นต้องเข้าถึงปลายทางการค้นหาและปลายทางคีย์ลงนามของ Keycloak ด้วย

ณ วันที่ 6 ตุลาคม 2026 เอกสารการดูแลระบบปัจจุบันของ ownCloud อธิบายการตั้งค่าเหล่านี้ภายใต้ Infinite Scale 9.0 ตัวอย่างการปรับใช้ Keycloak อย่างเป็นทางการเป็นจุดเริ่มต้นที่มีประโยชน์ แต่ไฟล์ Compose และการส่งออก Realm อาจมีการเปลี่ยนแปลงได้ ควรกำหนดเวอร์ชันของอิมเมจที่เข้ากันได้และตรวจสอบไฟล์ที่คุณปรับใช้แทนที่จะคัดลอกตัวอย่างที่ไม่มีการกำหนดเวอร์ชันโดยไม่ตรวจสอบให้ดี

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

เตรียมที่อยู่ HTTPS สาธารณะสำหรับ oCIS เช่นhttps://cloud.example.comและที่อยู่ HTTPS สาธารณะสำหรับ Keycloak เช่นhttps://sso.example.comทั้งสองชื่อต้องแสดงผลได้อย่างถูกต้องจากเบราว์เซอร์ของผู้ใช้ เซิร์ฟเวอร์ oCIS ต้องสามารถเข้าถึงเมตาเดต้า OIDC และคีย์ลงนามสาธารณะของ Keycloak ได้ด้วย หากมีการใช้พร็อกซีแบบย้อนกลับเพื่อจัดการบริการใดบริการหนึ่ง ให้กำหนดค่าชื่อโฮสต์สาธารณะและส่วนหัวที่ส่งต่อให้สอดคล้องกัน

• การติดตั้ง ownCloud Infinite Scale ที่ใช้งานได้ และสิทธิ์การเข้าถึงระดับผู้ดูแลระบบในการเข้าถึงสภาพแวดล้อมหรือการกำหนดค่า Compose
• ระบบ Keycloak ที่ใช้งานได้และสิทธิ์การเข้าถึงของผู้ดูแลระบบ Realm คือเนมสเปซของ Keycloak สำหรับผู้ใช้ ไคลเอนต์ บทบาท และการตั้งค่าข้อมูลประจำตัว
• ใบรับรอง TLS ที่ได้รับการยอมรับจากเบราว์เซอร์และเซิร์ฟเวอร์ที่ตรวจสอบความถูกต้องของใบรับรอง TLS ของ Keycloak ในการใช้งานจริงไม่ควรปิดใช้งานการตรวจสอบใบรับรอง
• การตัดสินใจเกี่ยวกับการจับคู่บัญชี: เชื่อมต่อผู้ใช้ oCIS ที่มีอยู่กับข้อมูลประจำตัวที่เสถียร หรือเปิดใช้งานการจัดเตรียมบัญชีเมื่อเข้าสู่ระบบครั้งแรกด้วยแบ็กเอนด์ผู้ใช้ที่อนุญาตให้เขียนได้ตามที่ต้องการ

1. ค้นหาผู้ออกบัตร Keycloak ที่ถูกต้อง

ใน Keycloak ตัวออก OIDC โดยปกติจะเป็น URL ของโดเมน ไม่ใช่ URL ของคอนโซลผู้ดูแลระบบ และไม่ใช่ URL ของเอกสารการค้นหา สำหรับโดเมนที่มีชื่อว่าteamอาจมีลักษณะเช่นนี้https://sso.example.com/realms/teamการติดตั้งหรือการใช้งานเวอร์ชันเก่าที่มีคำนำหน้าพาธอาจแตกต่างกัน ดังนั้นอย่าสร้างค่าจากความจำ เปิดเอกสารการค้นหาของโดเมนที่https://sso.example.com/realms/team/.well-known/openid-configurationและคัดลอกค่าของissuerคุณสมบัติอย่างถูกต้อง

จากเซิร์ฟเวอร์ที่สามารถเชื่อมต่อกับ Keycloak ได้ คุณสามารถตรวจสอบเอกสารได้ด้วยคำสั่ง:

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

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

2. ลงทะเบียนไคลเอ็นต์ OIDC สำหรับ ownCloud Web

ไคลเอ็นต์คือการลงทะเบียนแอปพลิเคชันที่ Keycloak ใช้ในการตัดสินใจว่าบริการใดสามารถร้องขอการเข้าสู่ระบบได้ สร้างหรือปรับแต่งไคลเอ็นต์ OpenID Connect ในโดเมนที่ใช้สำหรับ oCIS ใช้ไคลเอ็นต์ ID เช่นwebหรือค่าที่กำหนดเอง และตรวจสอบให้แน่ใจว่าตรงกับWEB_OIDC_CLIENT_IDค่าใน oCIS ตัวอย่างอย่างเป็นทางการของ ownCloud ใช้webเป็นค่าเริ่มต้น

สำหรับไคลเอ็นต์ที่ใช้งานผ่านเว็บเบราว์เซอร์ ให้ใช้ขั้นตอนการอนุญาตแบบมาตรฐานและการกำหนดค่าไคลเอ็นต์สาธารณะที่สอดคล้องกับตัวอย่างโดเมนอย่างเป็นทางการ ป้อนรูปแบบการเปลี่ยนเส้นทาง HTTPS และการเปลี่ยนเส้นทางหลังการออกจากระบบที่จำเป็นสำหรับการใช้งานของคุณ รูปแบบชื่อโฮสต์ที่แคบ เช่นhttps://cloud.example.com/*จะตรวจสอบได้ง่ายกว่ารูปแบบไวด์การ์ดที่กว้างครอบคลุมทุกโฮสต์ เพิ่มเฉพาะเว็บโอเรียนท์ที่การใช้งานของคุณต้องการเท่านั้น อย่าสร้างรหัสลับไคลเอ็นต์สำหรับไคลเอ็นต์เบราว์เซอร์สาธารณะแล้วฝังไว้ในการกำหนดค่าส่วนหน้า

3. ตรวจสอบข้อเรียกร้องและขอบเขตงาน

OIDC claims คือคุณลักษณะระบุตัวตนที่อยู่ในโทเค็นหรือส่งคืนโดยเอนด์พอยต์ข้อมูลผู้ใช้ อย่างน้อยที่สุด ควรเลือก username claim อย่างระมัดระวัง พร็อกซี ownCloud จะใช้ค่าเริ่มต้นpreferred_usernameสำหรับการแก้ไขผู้ใช้ และตัวอย่างของ Keycloak จะกำหนดค่าไคลเอ็นต์เว็บด้วยขอบเขตโปรไฟล์และอีเมลมาตรฐาน ตรวจสอบให้แน่ใจว่าโดเมนของคุณส่งคืน claims ที่คุณใช้จริง ความพร้อมใช้งานของ claim ขึ้นอยู่กับขอบเขตไคลเอ็นต์และตัวแมปโปรโตคอล

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

4. ชี้ Infinite Scale ไปที่ Keycloak

กำหนดค่าต่อไปนี้ในสภาพแวดล้อมสำหรับการปรับใช้ oCIS ตัวอย่างนี้สมมติว่าใช้ HTTPS และ Keycloak realm ที่/realms/team. ใช้ URL ของคุณเอง บล็อกแบบ YAML นี้เป็นเพียงตัวอย่างเท่านั้น Docker Compose, Kubernetes, systemd และวิธีการปรับใช้แบบอื่นๆ แสดงตัวแปรสภาพแวดล้อมแตกต่างกัน

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERเลือกผู้ให้บริการยืนยันตัวตนภายนอกPROXY_OIDC_REWRITE_WELLKNOWN=trueทำให้พร็อกซีเขียนทับปลายทางการค้นหา OpenID Connect ไปยังผู้ออกที่กำหนดค่าไว้ ownCloud ระบุในเอกสารว่าสิ่งนี้จำเป็นสำหรับไคลเอนต์เดสก์ท็อปและมือถือในการค้นหาผู้ให้บริการWEB_OIDC_CLIENT_IDต้องตรงกับไคลเอนต์ Keycloak การยกเว้นเป็นไปidpตามตัวอย่าง Keycloak ของ ownCloud เพื่อไม่ให้ผู้ให้บริการแบบฝังตัวเริ่มต้นเป็นผู้ให้บริการเข้าสู่ระบบที่ใช้งานอยู่

หากคุณต้องการให้ oCIS สร้างบัญชีเมื่อเข้าสู่ระบบสำเร็จครั้งแรก ให้ตั้งค่าPROXY_AUTOPROVISION_ACCOUNTS=trueและกำหนดค่าบริการ Graph ด้วยแบ็กเอนด์ผู้ใช้ที่อนุญาตให้เขียนได้ ตั้งค่าPROXY_USER_OIDC_CLAIMและPROXY_AUTOPROVISION_CLAIM_USERNAMEเป็น claim เดียวกัน สำหรับแอตทริบิวต์ชื่อผู้ใช้ เอกสาร ownCloud อธิบายPROXY_USER_CS3_CLAIM=usernameขั้นตอนการทำงานนี้ไว้ การจัดเตรียมอัตโนมัติเป็นทางเลือกและควรทดสอบแยกต่างหากจากการตรวจสอบสิทธิ์ อย่าเปิดใช้งานเว้นแต่ claim ที่เข้ามาจะไม่ซ้ำกันและแมปตามที่ต้องการ

5. อนุญาตให้ผู้ให้บริการยืนยันตัวตนเข้าถึงข้อมูลในนโยบายความปลอดภัยของเนื้อหา

Infinite Scale ใช้ Content Security Policy (CSP) เพื่อควบคุมว่าเว็บไคลเอ็นต์สามารถติดต่อกับแหล่งที่มาภายนอกใดได้บ้าง เอกสารของ ownCloud ระบุว่าผู้ให้บริการยืนยันตัวตนภายนอก เช่น Keycloak จำเป็นต้องมีคำจำกัดความ CSP ที่เหมาะสม หากปุ่มเข้าสู่ระบบปรากฏขึ้น แต่เบราว์เซอร์บล็อกคำขอ ให้ตรวจสอบคอนโซลของเบราว์เซอร์เพื่อหาข้อผิดพลาด CSP กำหนดค่านโยบายผ่านPROXY_CSP_CONFIG_FILE_LOCATIONและอนุญาตเฉพาะแหล่งที่มา Keycloak และคำสั่งที่การปรับใช้ของคุณต้องการเท่านั้น รีสตาร์ทพร็อกซีหรือการปรับใช้หลังจากเปลี่ยนไฟล์ อย่าแก้ปัญหาการเชื่อมต่อโดยการอนุญาตทุกแหล่งที่มา

6. เริ่มการทำงานใหม่และตรวจสอบการทำงานทั้งหมดอีกครั้ง

ปรับใช้การเปลี่ยนแปลงสภาพแวดล้อมและรีสตาร์ทการใช้งาน oCIS โดยใช้วิธีที่คุณใช้จัดการอยู่แล้ว ไม่มีคำสั่งรีสตาร์ทแบบครอบคลุมทุกกรณี: โปรเจกต์ Compose, เวิร์กโหลด Kubernetes และบริการ systemd มีการควบคุมที่แตกต่างกัน จากนั้นตรวจสอบแต่ละส่วนในห่วงโซ่:

1. เปิด URL การค้นหาของ Keycloak และยืนยันว่าได้ส่งคืนข้อมูล JSON ที่มีissuer, authorization_endpoint, token_endpoint, และjwks_uri.
2. เปิด URL เว็บ ownCloud ในหน้าต่างเบราว์เซอร์แบบส่วนตัว ตรวจสอบให้แน่ใจว่าเบราว์เซอร์เปลี่ยนเส้นทางไปยังโดเมน Keycloak ที่คาดไว้แล้ว
3. ลงชื่อเข้าใช้ด้วยบัญชีทดสอบและตรวจสอบว่าเบราว์เซอร์กลับไปยังชื่อโฮสต์ ownCloud เดิมโดยไม่เกิดการวนลูปการเปลี่ยนเส้นทางหรือไม่
4. ตรวจสอบให้แน่ใจว่าผู้ใช้ที่ต้องการใช้งาน (ไม่ใช่ผู้ใช้ที่สร้างซ้ำขึ้นมาใหม่) ปรากฏอยู่ใน Infinite Scale และสามารถเข้าถึงได้เฉพาะทรัพยากรที่คาดหวังไว้เท่านั้น
5. ทดสอบการออกจากระบบ จากนั้นทำซ้ำกับบัญชีที่สอง หากใช้งานกับโปรแกรมบนเดสก์ท็อปหรือมือถือ ให้ทดสอบการค้นหาและการเข้าสู่ระบบแยกต่างหาก

ข้อผิดพลาดที่พบบ่อยและความหมายโดยทั่วไปของข้อผิดพลาดเหล่านั้น

รายการตรวจสอบการผลิต

• ใช้ Pin ทดสอบเวอร์ชัน ownCloud และ Keycloak แทนการใช้latestแท็ก แบบลอยตัว
• ใช้ HTTPS สำหรับบริการสาธารณะทั้งสองอย่างและรักษาการตรวจสอบใบรับรองไว้ ownCloud ระบุว่าการแทนที่ TLS ที่ไม่ปลอดภัยนั้นไม่เหมาะสมสำหรับการใช้งานจริง
• ปกป้องข้อมูลประจำตัวผู้ดูแลระบบ Keycloak สำรองข้อมูลฐานข้อมูล Keycloak และการกำหนดค่าโดเมน และจำกัดการเข้าถึงการดูแลระบบ Keycloak
• ควรจำกัด URI การเปลี่ยนเส้นทางและต้นทางเว็บให้เฉพาะชื่อโฮสต์ ownCloud จริงเท่านั้น
• บันทึกรายละเอียดของตัวระบุที่เลือกไว้ และผลที่ตามมาจากการเปลี่ยนแปลงชื่อผู้ใช้ ชื่อโดเมน URL ของผู้ออกบัตร หรือรหัสไคลเอ็นต์
• ทดสอบการเข้าถึงการกู้คืนก่อนที่จะเปลี่ยนไปใช้ระบบใช้งานจริง และรักษาแผนการย้อนกลับไปยังการกำหนดค่าก่อนหน้าไว้ด้วย

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

• การกำหนดค่าบริการพร็อกซี ownCloud Infinite Scale 9.0
• คู่มือตัวอย่างการใช้งาน keycloak บน ownCloud
• ไฟล์การติดตั้ง ocis_keycloak อย่างเป็นทางการของ ownCloud
• คู่มือการดูแลระบบเซิร์ฟเวอร์ Keycloak 26.8
• แง่มุมด้านความปลอดภัยของ ownCloud Infinite Scale