Realms, Clients & Roles

🔐 Run Keycloak with Docker first

Start Keycloak in dev mode:

docker run --name keycloak -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Then open http://localhost:8080 and sign in to the admin console with admin / admin.

start-dev uses an in-memory database — perfect for learning. Use a real database and start for production.

โมดูลนี้ครอบคลุมอะไรบ้าง

โมดูลนี้จะสอนองค์ประกอบหลักสามอย่างที่ทุกการ deploy Keycloak ประกอบขึ้นมา ได้แก่ realm, client และ role ก่อนที่คุณจะสามารถรักษาความปลอดภัยให้แอปพลิเคชันสักตัวด้วย Keycloak ได้ คุณจำเป็นต้องเข้าใจว่าแนวคิดเหล่านี้คืออะไร เกี่ยวข้องกันอย่างไร และจะสร้างกับตั้งค่าใน admin console ได้อย่างไร

เมื่อจบโมดูลนี้ คุณจะสามารถ:

สร้างและตั้งค่า realm เฉพาะสำหรับแอปพลิเคชันของคุณได้
ลงทะเบียนแอปพลิเคชัน (client) เข้ากับ Keycloak ได้
เข้าใจความแตกต่างระหว่าง public client กับ confidential client และเลือกใช้ตัวที่เหมาะสมได้
สร้าง realm role และ client role แล้วกำหนดให้กับ user ได้
อ่าน JWT ที่ถอดรหัสแล้วและค้นหา role ที่อยู่ข้างในได้

องค์ประกอบหลักสามอย่าง

Realm

realm คือขอบเขตการแยกระดับบนสุด (top-level isolation boundary) ของ Keycloak ลองนึกถึง realm เป็น tenant หนึ่ง ๆ ที่มีชุดของ user, client, role, identity provider และการตั้งค่า token เป็นของตัวเอง ไม่มีอะไรรั่วไหลข้ามระหว่าง realm — session ใน realm A ไม่สามารถยืนยันตัวตน user เข้าสู่ realm B ได้

Keycloak มาพร้อม realm ที่สร้างไว้ล่วงหน้าหนึ่งตัวคือ master realm master คือ realm สำหรับงานบริหารจัดการ — คุณใช้ realm นี้ log in เข้า admin console และจัดการ realm อื่น ๆ คุณไม่ควร deploy แอปพลิเคชันของตัวเองไว้ภายใน master realm เด็ดขาด

Client

client คือแอปพลิเคชันใด ๆ ที่มอบหมายงาน authentication ให้ Keycloak จัดการ client อาจเป็น single-page app (SPA), mobile app, แอปพลิเคชันเว็บฝั่ง server หรือ service แบบ machine-to-machine ก็ได้ client แต่ละตัวจะลงทะเบียนตัวเองไว้ใน realm หนึ่ง ประกาศ redirect URI ของตัวเอง และรับ token จาก Keycloak หลังจาก user ยืนยันตัวตนแล้ว

Role

role คือสิทธิ์ (permission) ที่มีชื่อ ซึ่งสามารถผูกเข้ากับ user หรือ group ได้ มีอยู่สองแบบ:

Realm role — กำหนดที่ระดับ realm และใช้ได้กับทุก client ใน realm นั้น
Client role — กำหนดบน client เฉพาะตัวและจำกัดขอบเขตอยู่ที่ client นั้น

role จะปรากฏอยู่ใน token เพื่อให้แอปพลิเคชันของคุณตัดสินใจเรื่องการให้สิทธิ์ (authorisation) ได้โดยไม่ต้องเรียก Keycloak อีกครั้ง

ทั้งหมดทำงานร่วมกันอย่างไร

flowchart TD
  R[Realm] --> U[Users]
  R --> RR[Realm-level roles]
  R --> C[Clients]
  C --> CR[Client roles]
  C --> RU[Valid redirect URIs / settings]

How a realm contains users, roles, and clients

user ใน realm หนึ่งสามารถถูกกำหนดทั้ง realm role และ client role ได้ เมื่อ user ยืนยันตัวตนผ่าน client ตัวหนึ่ง token ที่ได้จะมี role เหล่านั้นอยู่ภายในเพื่อให้ client บังคับใช้การควบคุมการเข้าถึง (access control) ได้

บทเรียนในโมดูลนี้

บทเรียน	สิ่งที่คุณจะได้เรียนรู้
Realms	สร้างและตั้งค่า realm
Clients	ลงทะเบียนแอปพลิเคชันเป็น client
Client Types	public กับ confidential client และ PKCE
Roles	realm role, client role และ composite role