Events & Audit

Event สองประเภท

Keycloak บันทึก event สองหมวดหมู่ที่แตกต่างกัน:

Login event — การกระทำที่มาจาก end-user: การ login สำเร็จ, การพยายาม login ที่ล้มเหลว, การ refresh token, การ logout, การรีเซ็ตรหัสผ่าน และอื่นๆ สิ่งเหล่านี้เก็บไว้ต่อ realm และเป็น audit trail หลักสำหรับกิจกรรมของผู้ใช้
Admin event — การกระทำที่มาจาก administrator ใน admin console หรือผ่าน Admin REST API: การสร้าง realm, การลงทะเบียน client, การอัปเดตผู้ใช้, การกำหนด role และอื่นๆ

ทั้งสองประเภทถูกปิดใช้งานโดยค่าเริ่มต้น คุณต้องเปิดใช้งานอย่างชัดเจน

การเปิดใช้งาน event ใน admin console

เปิด admin console และเลือก realm ของคุณ
คลิก Realm settings ใน sidebar ซ้าย
คลิกแท็บ Events
ใต้ User events settings สลับ Save events เป็น On
ตั้งค่า Expiration (เช่น 7 วัน) เพื่อป้องกันการเติบโตอย่างไม่จำกัดใน database
หรือขยาย Saved types เพื่อจำกัดว่าจะเก็บ event type ใดบ้าง
คลิก Save

เปิดใช้งาน admin event

บนแท็บ Events เดียวกัน เลื่อนลงไปที่ Admin events settings
สลับ Save events เป็น On
หรือเปิดใช้ Include representation เพื่อเก็บ JSON payload เต็มรูปแบบของแต่ละการเปลี่ยนแปลง (มีประโยชน์สำหรับ audit โดยละเอียด แต่เพิ่มการใช้งาน storage)
คลิก Save

การดู event

หลังจากเปิดใช้งาน event แล้ว จะสะสมแบบ real time

Login event: ใน sidebar ซ้าย คลิก Events แท็บ User events แสดงรายการ login event แบบแบ่งหน้า พร้อม timestamp, ผู้ใช้, IP address และ event type ใช้ search filter เพื่อกรองตาม event type (เช่น LOGIN_ERROR) หรือช่วงวันที่

Admin event: คลิกแท็บ Admin events แต่ละรายการแสดง operation type (CREATE, UPDATE, DELETE), resource type (เช่น USER, CLIENT) และ representation ก่อน/หลังตามต้องการ

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

คุณยังสามารถ fetch event แบบ programmatic:

curl -s "https://localhost:8080/admin/realms/my-app/events?type=LOGIN_ERROR&max=20" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq .

แทนที่ my-app ด้วยชื่อ realm และ \${TOKEN} ด้วย admin token ที่ valid

Event listener

นอกจากการเก็บ event ใน database แล้ว Keycloak ยังรองรับ event listener — plugin ที่ตอบสนองต่อ event แบบ real time event listener ที่มีมาให้สองตัวที่มีประโยชน์ทันที:

Listener	สิ่งที่ทำ
`jboss-logging`	Log event ไปยัง Keycloak server log (เปิดใช้งานโดยค่าเริ่มต้น)
`email`	ส่ง email ไปยังผู้ใช้เมื่อเกิด event เช่น `LOGIN_ERROR`

วิธีเปิดใช้งาน listener:

ไปที่ Realm settings > Events > Event listeners
เพิ่มชื่อ listener จาก drop-down
คลิก Save

สำหรับ integration แบบกำหนดเอง (เช่น การส่ง event ไปยัง webhook หรือ message queue) คุณสามารถ implement Keycloak SPI (EventListenerProvider) และ deploy เป็น provider JAR

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

ตัวเลือก	Benefit	Cost
เก็บ admin event พร้อม “Include representation”	ได้ full JSON payload ก่อน/หลังของทุกการเปลี่ยนแปลง เหมาะกับ audit ที่ต้องรู้ว่าอะไรเปลี่ยนไปบ้าง	เพิ่มการใช้งาน storage อย่างมาก โดยเฉพาะ realm ที่มี admin เข้ามาแก้ config บ่อย
Expiration สั้น (7 วัน)	ควบคุม storage ให้อยู่ในขอบเขต ไม่ต้องดูแล archive เอง	หากเกิดเหตุการณ์ที่ต้องสืบสวนย้อนหลังเกิน 7 วัน ข้อมูลอาจหายไปแล้ว
Expiration ยาว หรือ export ไปเก็บนอกระบบ	รองรับ compliance/audit ที่ต้องเก็บ log ย้อนหลังนาน (เช่น SOC2)	เพิ่ม storage cost และต้องมีกลไก archive/export แยกต่างหาก

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

ไม่เปิดใช้งาน event เลยจนกว่าจะเกิดเหตุการณ์ผิดปกติ — event ถูกปิดโดยค่าเริ่มต้น ทีมจำนวนมากเปิดใช้งานหลังเกิด incident ไปแล้ว ทำให้ไม่มีข้อมูลสำหรับสืบสวนย้อนหลัง ควรเปิดใช้งานก่อน go live เสมอ
ไม่ตั้งค่า Expiration เลย — ปล่อยให้ event สะสมไม่จำกัดใน database ทำให้ table โตขึ้นเรื่อย ๆ จนกระทบ performance ของ Keycloak เอง ควรตั้งอายุที่เหมาะสมกับความต้องการ audit ขององค์กร
เปิด “Include representation” ทุก realm โดยไม่พิจารณา storage cost — เก็บ JSON payload เต็มของทุกการเปลี่ยนแปลงในทุก realm รวมถึง realm ที่ไม่จำเป็นต้อง audit ละเอียดขนาดนั้น เพิ่มภาระ storage โดยไม่จำเป็น

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

SOC2 / compliance audit — องค์กรที่ต้องผ่าน SOC2 หรือมาตรฐาน compliance อื่นมักตั้งค่า admin event ให้เก็บ representation เต็มรูปแบบ แล้ว export ไปยัง SIEM หรือ log aggregation ภายนอกเป็นระยะ เพื่อพิสูจน์ว่าทุกการเปลี่ยนแปลงด้าน identity ถูกบันทึกไว้

Security incident response — ทีม security ใช้ login event เพื่อสืบสวนว่า account ใดถูกโจมตีแบบ credential stuffing โดยกรองด้วย event type LOGIN_ERROR และช่วงเวลาที่เกิดเหตุผ่าน Admin REST API แทนการไล่ดูทีละหน้าใน console