Protocol Mappers

Protocol Mappers คืออะไร

Protocol mapper แปลงข้อมูลหนึ่ง — user attribute, ชื่อ group, หรือค่าที่กำหนดไว้ตายตัว — ให้กลายเป็น claim ใน access token, ID token หรือ userinfo response โดยไม่มี mapper token จะมีเพียง OIDC claim พื้นฐานที่ Keycloak เพิ่มให้เป็นค่าเริ่มต้น

ประเภทของ Mapper

ประเภท Mapper	หน้าที่
User Attribute mapper	แมป custom user attribute ลงใน claim
Group Membership mapper	เพิ่มรายชื่อ group ของผู้ใช้ลงใน token
Hardcoded Claim mapper	เพิ่มค่าคงที่ลงใน token ทุกใบ
Audience mapper	เพิ่มค่าใน claim `aud`
User Property mapper	แมป built-in user property ลงใน claim
Role mapper	จัดการ realm/client roles ใน token

วิธีเพิ่ม Mapper ใน Admin Console

ไปที่ Client scopes → เลือก scope ที่ต้องการ
คลิก tab Mappers
คลิก Add mapper → By configuration
เลือกประเภท mapper ที่ต้องการ
ตั้งค่า Name, Token Claim Name และตัวเลือกอื่นๆ
คลิก Save

วิธีเพิ่ม Audience Mapper

ไปที่ Client scopes → เลือก scope สำหรับ API ของคุณ
คลิก tab Mappers → Add mapper → By configuration
เลือก Audience
ตั้ง Name: audience-mapper
ตั้ง Included Client Audience: ใส่ client ID ของ API
เปิดใช้งาน Add to access token
คลิก Save

ตัวอย่าง Token Payload หลังเพิ่ม Audience Mapper

{
  "aud": ["account", "orders-api"],
  "azp": "my-app-frontend",
  "scope": "openid profile email",
  "department": "engineering"
}

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

ตัวเลือก	Benefit	Cost
Token แบบ “fat” (มี mapper และ claim จำนวนมาก)	Backend อ่าน claim ได้ทันทีจาก token เดียว ไม่ต้อง call API เพิ่มเพื่อเอาข้อมูล user	Token มีขนาดใหญ่ขึ้น ส่งผลต่อ header size และมีข้อมูลให้รั่วมากขึ้นหาก token หลุด
Token แบบ “thin” (มีเฉพาะ claim ที่จำเป็นจริงๆ)	Token เล็ก ปลอดภัยกว่าเพราะมีข้อมูลให้ leak น้อย ดูแล mapper ง่ายกว่า	Backend อาจต้อง query เพิ่มเพื่อได้ข้อมูลที่ไม่ได้ฝังไว้ใน token
Hardcoded Claim mapper	ค่าคาดเดาได้ ดีสำหรับ debug และ config ที่ตายตัว เช่นระบุ audience	ไม่ยืดหยุ่น เปลี่ยนตามผู้ใช้ไม่ได้ ต้องแก้ mapper ทุกครั้งถ้าค่าต้องเปลี่ยน

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

ใส่ mutable หรือข้อมูลที่เปลี่ยนบ่อยลงใน claim (เช่น role ปัจจุบัน, ยอดเงินคงเหลือ, สถานะ subscription) — claim คือ snapshot ณ เวลาที่ token ถูกออก ไม่ใช่ live data ถ้าข้อมูลจริงเปลี่ยนไป token เก่าจะยังโชว์ค่าเดิมจนกว่าจะ refresh ใหม่
เพิ่ม mapper สำหรับทุก user attribute “เผื่อไว้ก่อน” — ทำให้ token บวมโดยไม่จำเป็น เพิ่ม mapper เฉพาะ claim ที่มี consumer ใช้งานจริง
ลืมเปิด “Add to access token” หรือเปิดผิดที่ (เช่นเปิดเฉพาะ userinfo) — mapper ถูกสร้างไว้แต่ claim ไม่ปรากฏใน access token จริง ทำให้ debug เสียเวลาโดยไม่จำเป็น

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

E-commerce platform — ใช้ Group Membership mapper ใส่ tier ของลูกค้า (gold/silver) ลง token เพื่อให้ frontend ปรับ UI ได้ทันที แต่ตั้ง access token lifespan สั้นไว้เพื่อไม่ให้ tier เก่าค้างนานเกินไปหากมีการอัปเกรด/ดาวน์เกรด tier

Enterprise internal tools — เลือกใช้ thin token ที่มีแค่ sub และ role พื้นฐาน แล้วให้ backend เรียก profile service แยกต่างหากเมื่อจำเป็น เพื่อให้มั่นใจว่าข้อมูลที่แสดงเป็นค่าล่าสุดเสมอ ไม่ใช่ค่าจาก snapshot ตอน login