Users

User คืออะไร?

user ใน Keycloak คือ record ของ identity ที่จัดเก็บอยู่ภายใน realm หนึ่ง โดยเก็บรายละเอียดบัญชี — username, อีเมล, ชื่อ, และ attribute แบบกำหนดเองใด ๆ — พร้อมกับ credential และสถานะวงจรชีวิตของบัญชี

user มีขอบเขตอยู่ภายใน realm (realm-scoped) user ที่สร้างใน realm my-app จะไม่มีอยู่ใน realm อื่นโดยอัตโนมัติ ขอบเขตนี้เป็นความตั้งใจ: แต่ละ realm เป็นโดเมน identity อิสระ และการแชร์ user ข้าม realm ต้องใช้ federation ไม่ใช่แค่การนำกลับมาใช้ใหม่อย่างง่าย

คุณสามารถจัดการ user ได้ผ่าน Keycloak admin console, ผ่าน Admin REST API, หรือโดยการ federate ไดเรกทอรีภายนอก (LDAP, Active Directory) บทเรียนนี้จะโฟกัสที่ console และ REST API

การสร้าง user

เปิด Keycloak admin console แล้วเลือก realm ที่ถูกต้องจาก drop-down ที่มุมซ้ายบน
คลิก Users ในแถบด้านซ้าย
คลิก Add user (มุมขวาบนของรายการ user)
กรอกรายละเอียดของ user:
- Username — จำเป็น; ต้องไม่ซ้ำกันภายใน realm ใช้ตัวพิมพ์เล็กและหลีกเลี่ยงการเว้นวรรค (เช่น jane.doe)
- Email — เป็นทางเลือกแต่แนะนำอย่างยิ่ง; จำเป็นหากคุณวางแผนจะใช้ flow ที่อิงอีเมล เช่น การรีเซ็ต password
- First name และ Last name — ฟิลด์แสดงผลที่เป็นทางเลือก
- Email verified — เปิดสวิตช์นี้ On หากคุณกำลังสร้างบัญชีในนามของ user ที่รู้จักและเชื่อถือได้ และไม่ต้องการให้ Keycloak ส่งอีเมลยืนยัน ปล่อยไว้ Off เพื่อบังคับให้ยืนยันอีเมลในการล็อกอินครั้งแรก
คลิก Create

Keycloak จะสร้าง user และเปิดหน้ารายละเอียดของพวกเขา บัญชียังไม่มี password เลย — คุณจะตั้ง credential จากแท็บ Credentials

รายการ user และการค้นหา

หน้า Users แสดงรายการ user ทั้งหมดใน realm แบบแบ่งหน้า (paginated) ใช้แถบค้นหาด้านบนเพื่อค้นหา user ตาม:

Username — รองรับการจับคู่บางส่วน (เช่น การค้นหา jane จะคืนค่า jane.doe และ jane.smith)
Email — จับคู่แบบตรงทั้งหมดหรือบางส่วน
First name หรือ Last name

คลิก username เพื่อเปิดมุมมองรายละเอียดของ user พร้อมแท็บต่าง ๆ: Details, Attributes, Credentials, Role mappings, Groups, Consents, Sessions, และ Admin events

User attribute

Attribute คือคู่ key-value ที่กำหนดได้อิสระซึ่งแนบไว้กับ user มีประโยชน์สำหรับการจัดเก็บ metadata เฉพาะแอปพลิเคชัน — ตัวอย่างเช่น รหัสแผนก, customer ID, หรือ locale ที่ต้องการ — โดยไม่ต้องแก้ไข data model ของ Keycloak

วิธีเพิ่ม attribute:

เปิดหน้ารายละเอียดของ user แล้วคลิกแท็บ Attributes
คลิก Add attribute
ใส่ Key (เช่น department) และ Value (เช่น engineering)
คลิก Save

Attribute จะถูกคืนค่าใน claim attributes ของ token ของ user หากคุณ map attribute นั้นไปยัง client scope โดยใช้ User Attribute mapper หากไม่มี mapper, attribute จะยังคงอยู่ฝั่ง server เท่านั้น

การเปิดและปิดการใช้งาน user

user ทุกคนมีสวิตช์ Enabled บนแท็บ Details ของพวกเขา เมื่อ user ถูกปิดการใช้งาน:

session ที่ใช้งานอยู่จะถูกยุติ
user ไม่สามารถเริ่มการล็อกอินใหม่ได้ ไม่ว่า credential จะถูกต้องหรือไม่
record ของบัญชีจะถูกเก็บรักษาไว้ — คุณสามารถเปิดการใช้งาน user กลับได้ทุกเมื่อ

สิ่งนี้มีประโยชน์สำหรับการล็อกบัญชีชั่วคราวโดยไม่ต้องลบบัญชีทิ้ง หากต้องการเปลี่ยนสถานะ ให้เปิดหน้ารายละเอียดของ user, สลับ Enabled เปิดหรือปิด, แล้วคลิก Save

การ query user ผ่าน Admin REST API

Admin REST API ช่วยให้คุณ list, ค้นหา, และจัดการ user ได้แบบ programmatic ก่อนเรียก API ให้ขอ token ของ service-account หรือ admin ที่มี realm role manage-users หรือ view-users

curl -s -H "Authorization: Bearer ${TOKEN}" http://localhost:8080/admin/realms/my-app/users | jq .

แทนที่ my-app ด้วยชื่อ realm ของคุณ และ TOKEN ด้วย bearer token ที่ถูกต้อง การตอบกลับคือ JSON array ที่แต่ละ element เป็น object ของ user ซึ่งมี id, username, email, firstName, lastName, enabled, emailVerified, และ attributes

คุณสามารถเพิ่ม query parameter เพื่อกรองผลลัพธ์ได้:

# Search by email (partial match)
curl -s -H "Authorization: Bearer ${TOKEN}" \
  "http://localhost:8080/admin/realms/my-app/users?email=jane" | jq .

# Paginate: skip first 20, return next 10
curl -s -H "Authorization: Bearer ${TOKEN}" \
  "http://localhost:8080/admin/realms/my-app/users?first=20&max=10" | jq .

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

ตัวเลือก	Benefit	Cost
ให้ admin สร้าง user เองทุกบัญชี (manual onboarding)	ควบคุมได้ละเอียด — admin กำหนด attribute, email verified, required action ได้ตั้งแต่วันแรก	ไม่ scale เมื่อจำนวน user เพิ่มขึ้น ต้องเสียเวลา admin ต่อบัญชี
เปิด self-registration ให้ user สมัครเอง	ลดภาระงาน admin, onboarding เร็วขึ้นมาก	ต้องวางระบบ default group และ required action ให้ดี ไม่งั้นบัญชีใหม่จะไม่มี permission ที่ถูกต้องหรือยังไม่ได้ยืนยันอีเมล
แนบ attribute แบบกำหนดเองบน user โดยตรง	ยืดหยุ่น เก็บ metadata เฉพาะแอปได้โดยไม่ต้องแก้ data model	ถ้าไม่ map เข้ากับ client scope ผ่าน mapper, attribute จะไม่ไปปรากฏใน token เลย ต้องดูแล mapping เพิ่ม

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

สร้าง user ทีละคนโดยไม่วางแผนเรื่อง group/permission — ทำให้การกำหนด role กระจัดกระจาย ควรคิดเรื่อง group และ default group ตั้งแต่ต้นแทนที่จะไล่แก้ทีหลัง
เปิด Email verified เป็น On โดยไม่ตรวจสอบว่าเป็น user จริง — ถ้า admin สร้างบัญชีแทน user แล้วปิดขั้นตอนยืนยันอีเมลโดยไม่จำเป็น จะเปิดช่องให้เกิดบัญชีปลอมหรืออีเมลผิดคนโดยไม่รู้ตัว
ลืมว่า user มีขอบเขตอยู่แค่ใน realm เดียว — พยายาม query หรืออ้างอิง user ข้าม realm โดยตรงจะไม่เจอ ต้องใช้ federation ถ้าต้องการแชร์ identity ข้าม realm

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

บริษัท SaaS B2B — ใช้ Admin REST API สร้าง user อัตโนมัติทุกครั้งที่มีการ provision tenant ใหม่ พร้อมตั้ง attribute เช่น tenantId และ plan ตั้งแต่ตอนสร้าง เพื่อให้ backend แยกสิทธิ์ตาม tenant ได้ทันทีโดยไม่ต้องรอ admin กดมือ

องค์กรขนาดใหญ่ (enterprise) — เปิด self-registration เฉพาะโดเมนอีเมลภายในองค์กร แล้วบังคับ required action verify-email เพื่อให้มั่นใจว่าทุกบัญชีที่เข้าระบบมาเป็นพนักงานจริง ก่อนจะให้เข้าถึง internal application ใด ๆ