Client Scopes

Client Scopes คืออะไร

Client scope คือชุดของ mapper ที่ตั้งชื่อและนำกลับมาใช้ซ้ำได้ ช่วยให้กำหนด claim ชุดหนึ่งครั้งแล้ว attach ให้ client หลายตัวได้ แทนที่จะกำหนด mapper ซ้ำในแต่ละ client

Default vs Optional Scope

• Default scope จะรวมอยู่เสมอในทุก token request โดยไม่ต้องระบุเพิ่มเติม
• Optional scope จะรวมเฉพาะเมื่อ authorization request ระบุอย่างชัดเจนผ่าน scope parameter

Built-in Scopes

Scope	สิ่งที่เพิ่มลงใน Token
profile	เพิ่ม name, given_name, family_name, preferred_username
email	เพิ่ม email, email_verified
roles	เพิ่ม realm_access, resource_access
openid	จำเป็นสำหรับ OIDC
offline_access	ให้ refresh token ที่อยู่ได้นาน

วิธี Assign Optional Scope ให้ Client

1. ไปที่ Clients → เลือก client ของคุณ
2. คลิก tab Client scopes
3. คลิก Add client scope
4. เลือก scope ที่ต้องการแล้วตั้งเป็น Optional
5. คลิก Add

วิธีสร้าง Custom Scope

1. ไปที่ Client scopes → คลิก Create client scope
2. ตั้งชื่อ scope เช่น orders:read
3. เลือก Protocol: openid-connect
4. คลิก Save
5. ไปที่ tab Mappers เพื่อเพิ่ม mapper ลงใน scope นี้

ตัวอย่าง Authorization Request พร้อม Optional Scope

https://auth.example.com/realms/my-app/protocol/openid-connect/auth?client_id=my-app-frontend&response_type=code&redirect_uri=https://app.example.com/callback&scope=openid%20profile%20email%20address

Copy curl ⧉

🔐 Optional scope ช่วยให้ token มีขนาดเล็ก

Optional client scope ทำให้ access token มีขนาดเล็ก — Keycloak จะรวม claim เหล่านั้นเฉพาะเมื่อ client ร้องขออย่างชัดเจน ร้องขอเฉพาะ scope ที่แอปพลิเคชันต้องการจริงๆ เท่านั้น

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

ตัวเลือก	Benefit	Cost
Default scope	ทุก client ได้ claim ชุดเดียวกันอัตโนมัติโดยไม่ต้องตั้งค่าเพิ่ม ลดโอกาส config ผิดพลาดหรือลืม assign	Token มีขนาดใหญ่ขึ้นเสมอ แม้บาง client จะไม่เคยใช้ claim นั้นเลย
Optional scope	Token เล็กลง เพราะมีเฉพาะ claim ที่ client ร้องขอจริงผ่าน scope parameter	Client ต้องจำและระบุ scope ทุกครั้งใน authorization request ถ้าลืมจะไม่ได้ claim ที่ต้องการ
แยก scope ตาม API (เช่น orders:read, billing:write) แทนที่จะรวมไว้ scope เดียว	ควบคุมสิทธิ์แบบ least privilege ได้ละเอียดต่อ client ต่อ use case	ต้อง maintain scope และ mapper หลายชุดมากขึ้น เพิ่มภาระดูแล

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

• ตั้งทุก custom scope เป็น default — ทำให้ token บวมด้วย claim ที่ client ส่วนใหญ่ไม่ได้ใช้ ควรตั้งเป็น optional แล้วให้ client ที่ต้องการจริงร้องขอเอง
• ลืมระบุ scope ใน authorization request แล้วสงสัยว่าทำไม claim ไม่มา — การ assign optional scope ให้ client เพียงอย่างเดียวไม่ทำให้ claim ปรากฏใน token อัตโนมัติ ต้องระบุใน scope parameter ของ request ด้วยเสมอ
• ใช้ scope เดียวสำหรับหลาย API ที่ระดับสิทธิ์ต่างกัน — ทำให้ทุก client ที่ได้ scope นั้นมีสิทธิ์เท่ากันหมด ควรแยก scope ตามระดับความเสี่ยงของแต่ละ API

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

Multi-tenant SaaS platform — แยก optional scope ตาม module เช่น billing, reports, admin เพื่อให้ token ของแต่ละ integration หรือ third-party app มีแค่ claim ที่จำเป็นต่อ module ที่ขอใช้งานจริง

API gateway ระดับองค์กร — ใช้ default scope roles เพื่อให้ทุก client ได้ realm/client role claim พื้นฐานเสมอ ส่วน scope ที่ละเอียดอ่อนกว่าอย่างข้อมูลการเงินตั้งเป็น optional และเปิดให้เฉพาะ client ที่ผ่านการอนุมัติ

Client scope คืออะไร?

Role ของผู้ใช้ที่ scoped ให้ client ชุดของ mapper ที่ตั้งชื่อและแนบให้ client หลายตัวได้ ประเภทของ OIDC flow ข้อจำกัดของ redirect URI

จะร้องขอ optional client scope ในขั้นตอน authorization ได้อย่างไร?

เพิ่มเข้าไปใน Valid redirect URIs ระบุใน scope request parameter เปิดใช้งานใน Realm settings กำหนดเป็น required action บน user

Built-in scope ใดเพิ่ม realm_access และ resource_access เข้าใน token?

profile email openid roles

ความแตกต่างระหว่าง Default scope และ Optional scope คืออะไร?

Default scope ใช้ทรัพยากรในการประมวลผลมากกว่า Default scope รวมอยู่เสมอ; optional scope ต้องร้องขออย่างชัดเจน Optional scope เป็นแบบถาวร; default scope ลบได้ ไม่มีความแตกต่างในเชิงการทำงาน

Submit

Mark as complete