LDAP User Federation

User federation คืออะไร?

User federation ช่วยให้ Keycloak อ่าน (และอาจเขียน) บัญชีผู้ใช้จาก external store แทน database ภายในของตัวเอง Store ที่พบบ่อยที่สุดคือ LDAP (Lightweight Directory Access Protocol) ที่เป็น protocol ที่ใช้โดย:

• OpenLDAP — LDAP server แบบ open-source
• Microsoft Active Directory (AD) — enterprise directory service ที่พบในเครือข่ายองค์กรส่วนใหญ่
• Apache Directory Server, 389 Directory Server และอื่น ๆ

เมื่อผู้ใช้พยายาม login Keycloak จะค้นหาพวกเขาใน LDAP directory และมอบหมายการตรวจสอบรหัสผ่านให้กับ LDAP bind จากมุมมองผู้ใช้ พวกเขาแค่ login ด้วย credentials directory ที่ใช้ปกติ

ขั้นตอนที่ 1 — เพิ่ม LDAP provider

1. ใน admin console ตรวจสอบว่าอยู่ในรีล์มที่ถูกต้อง
2. คลิก User federation ใน left sidebar
3. คลิก Add provider และเลือก LDAP
4. Keycloak แสดงฟอร์มตั้งค่า LDAP

ขั้นตอนที่ 2 — Connection settings

กรอกรายละเอียดการเชื่อมต่อ:

ช่อง	สิ่งที่ต้องกรอก
Vendor	เลือก Active Directory สำหรับ AD หรือ Other สำหรับ OpenLDAP ซึ่งจะกรอกค่าเริ่มต้น DN structures และ attributes ที่เหมาะสม
Connection URL	URI ของ LDAP server เช่น ldap://ldap.example.com:389 หรือ ldaps://ldap.example.com:636 (LDAPS สำหรับการเข้ารหัส)
Enable StartTLS	ทางเลือกที่นิยมแทน LDAPS สำหรับเข้ารหัสการเชื่อมต่อบน port 389
Connection pooling	เปิดใช้ใน production เพื่อนำ LDAP connections กลับมาใช้

คลิก Test connection เพื่อยืนยันว่า Keycloak เข้าถึง server ได้ก่อนทำต่อ

ขั้นตอนที่ 3 — Bind settings

Keycloak ต้องใช้ service account เพื่อค้นหา directory เรียกว่า bind DN

ช่อง	สิ่งที่ต้องกรอก
Bind type	simple สำหรับ username/password bind
Bind DN	Distinguished name ของ service account เช่น cn=keycloak-svc,ou=service-accounts,dc=example,dc=com
Bind credentials	รหัสผ่าน service account เก็บใน Keycloak vault หรือ environment variable — ห้าม hardcode

คลิก Test authentication เพื่อยืนยันว่า bind credentials ทำงานได้

ขั้นตอนที่ 4 — LDAP searching และ user DN

ช่อง	สิ่งที่ต้องกรอก
Users DN	Base DN สำหรับค้นหาผู้ใช้ เช่น ou=users,dc=example,dc=com
Username LDAP attribute	LDAP attribute ที่ map กับ Keycloak username สำหรับ AD ใช้ sAMAccountName สำหรับ OpenLDAP ใช้ uid
RDN LDAP attribute	โดยทั่วไปคือ cn หรือเหมือนกับ username attribute
UUID LDAP attribute	สำหรับ AD: objectGUID สำหรับ OpenLDAP: entryUUID ใช้เป็น internal user ID ของ Keycloak
User object classes	สำหรับ AD: person, organizationalPerson, user สำหรับ OpenLDAP: inetOrgPerson, organizationalPerson

ขั้นตอนที่ 5 — Edit mode และ import

สองการตั้งค่านี้กำหนดวิธีที่ Keycloak sync ผู้ใช้และจะเขียนกลับไปยัง LDAP หรือไม่

Edit mode

READ_ONLY   — Keycloak ไม่สามารถแก้ไข LDAP attributes ใด ๆ การเปลี่ยนรหัสผ่านถูกปฏิเสธ ใช้สำหรับ corporate AD ที่ Keycloak ไม่ควรแตะต้อง directory
WRITABLE    — Keycloak สามารถอัปเดต LDAP attributes และ sync การเปลี่ยนรหัสผ่านกลับไปยัง LDAP ใช้เฉพาะเมื่อ Keycloak ได้รับอนุญาตให้เขียนใน directory
UNSYNCED    — Keycloak เก็บการเปลี่ยนแปลง attributes ในเครื่อง (ใน DB ของตัวเอง) โดยไม่เขียนไปยัง LDAP

# Recommended default for most deployments
Edit mode: READ_ONLY

Copy recommendation ⧉

Import users

• On (ค่าเริ่มต้น) — Keycloak import ข้อมูลผู้ใช้เข้า local database เมื่อ login ครั้งแรกและหลัง sync แต่ละครั้ง การค้นหาเร็วเพราะ query จาก local DB
• Off — Keycloak query LDAP ทุกครั้งที่ login เก็บข้อมูลในเครื่องน้อยกว่า แต่ทุก authentication ต้องผ่าน LDAP server

ขั้นตอนที่ 6 — Sync และ Save

1. คลิก Save
2. กลับไปที่หน้า User federation เปิด LDAP provider ของคุณ
3. เลื่อนลงไปที่ส่วน Synchronization
4. คลิก Synchronize all users เพื่อ sync ทั้งหมดทันที หรือตั้งค่า Changed users sync ให้รันตามกำหนดเวลา

หลัง sync ไปที่ Users ใน left sidebar คุณควรเห็นผู้ใช้ LDAP พร้อม badge “federated”

🔐 เลือก READ_ONLY ถ้าไม่ได้ตั้งใจจะเขียนกลับไปยัง LDAP

Edit mode READ_ONLY ป้องกัน Keycloak จากการแก้ไข LDAP directory นี่คือค่าเริ่มต้นที่ปลอดภัยสำหรับการ deploy Active Directory ในองค์กรที่ฝ่าย IT เป็นเจ้าของ directory เปลี่ยนเป็น WRITABLE เฉพาะเมื่อองค์กรอนุมัติให้ Keycloak เป็น client ที่เขียนได้ใน directory อย่างชัดเจน

ข้อแลกเปลี่ยน

ตัวเลือก	Benefit	Cost
READ_ONLY	ปลอดภัยที่สุด — Keycloak ไม่มีทางเขียนกลับไปยัง LDAP ไม่มีความเสี่ยงที่จะทำ directory ขององค์กรพัง เหมาะกับ corporate AD ที่ฝ่าย IT เป็นเจ้าของ	ผู้ใช้เปลี่ยนรหัสผ่านหรือ profile ผ่าน Keycloak ไม่ได้ ต้องไปเปลี่ยนที่ระบบต้นทาง (เช่น AD) เอง
WRITABLE	ผู้ใช้เปลี่ยนรหัสผ่านหรือ attributes ผ่าน Keycloak ได้โดยตรง สะดวกสำหรับ self-service	Keycloak มีสิทธิ์เขียนเข้า production directory — ถ้า config ผิดพลาดหรือ service account ถูกโจมตี อาจกระทบข้อมูลจริงใน LDAP/AD ทั้งองค์กร
UNSYNCED	เก็บการเปลี่ยนแปลง attributes ไว้ในเครื่อง (local DB) โดยไม่แตะ LDAP เลย — ยืดหยุ่นสำหรับ attribute เสริมที่ LDAP ไม่มี	ข้อมูลใน Keycloak กับ LDAP อาจไม่ตรงกัน (diverge) เมื่อเวลาผ่านไป เพราะ local override ไม่ sync กลับไปยัง source of truth

ข้อผิดพลาดที่พบบ่อย

• Import ผู้ใช้ทั้งหมดแบบ unpaged จาก directory ขนาดใหญ่ — ถ้า directory มีผู้ใช้หลักหมื่นหลักแสน การ sync แบบไม่แบ่งหน้า (paging) อาจทำให้ LDAP server หรือ Keycloak เองล่มจาก memory/timeout ควรตั้งค่า batch size และใช้ paged search ที่ LDAP server รองรับ
• ตั้ง edit mode เป็น WRITABLE โดยไม่ได้รับอนุมัติจากฝ่ายที่ดูแล directory — Keycloak จะกลายเป็น client ที่เขียนเข้า production AD/LDAP ได้ทันที ซึ่งเสี่ยงต่อการทำข้อมูลพนักงานเสียหายถ้า mapping ผิด ควรเริ่มจาก READ_ONLY เสมอแล้วค่อยขยับถ้าจำเป็นจริง ๆ
• ไม่ตั้งค่า Connection pooling หรือ scheduled sync ใน production — การ query LDAP ตรงทุกครั้งที่ login (import off) โดยไม่มี connection pooling ทำให้ LDAP server รับ load สูงเกินจำเป็นเมื่อผู้ใช้เยอะพร้อมกัน

💡 ตัวอย่างจากของจริง

องค์กรที่ bridge Keycloak เข้ากับ Active Directory เดิม — พนักงานยังคง login ด้วยรหัสผ่าน AD เดิมที่ใช้อยู่แล้วสำหรับ Windows login และอีเมล โดยไม่ต้องจำรหัสผ่านใหม่หรือสร้างบัญชี Keycloak แยกต่างหาก IT ทีมยังคงควบคุม password policy ผ่าน AD เหมือนเดิม

บริษัทที่มี OpenLDAP เป็นแหล่งข้อมูลพนักงานกลาง — ใช้ LDAP federation แบบ READ_ONLY เพื่อให้ระบบ internal tools ทั้งหมดที่ผ่าน Keycloak เห็นผู้ใช้ชุดเดียวกัน โดยไม่ต้อง sync ข้อมูลไปมาระหว่างระบบหลายตัว

ควรใช้ LDAP attribute อะไรเป็น username สำหรับ Active Directory?

uid cn sAMAccountName objectGUID

LDAP edit mode READ_ONLY หมายความว่าอะไร?

Keycloak อ่านผู้ใช้ได้แต่เก็บการเปลี่ยนแปลง attributes ในเครื่อง Keycloak ไม่สามารถแก้ไข LDAP attributes ใด ๆ — การเปลี่ยนรหัสผ่านถูกปฏิเสธ Keycloak อ่าน LDAP เฉพาะระหว่าง initial sync ผู้ใช้อ่านได้เฉพาะ profile ของตัวเอง — ไม่สามารถเปลี่ยนแปลงได้

จุดประสงค์ของ bind DN ใน LDAP federation คืออะไร?

เป็น base path ที่ Keycloak ค้นหาผู้ใช้ ระบุ UUID attribute ใน directory เป็น service account ที่ Keycloak ใช้ query LDAP directory กำหนด edit mode สำหรับ federation provider

เมื่อปิด "Import users" จะเกิดอะไรขึ้นทุกครั้งที่ login?

Keycloak สร้าง local copy ของผู้ใช้เฉพาะ login แรก Keycloak query LDAP server ทุกครั้งที่ authenticate Keycloak fallback ไปยัง internal user database Keycloak ปิดการ authenticate ด้วยรหัสผ่านสำหรับผู้ใช้ LDAP

Submit

Mark as complete