Admin REST API

Admin REST API คืออะไร?

ทุกปุ่มใน Keycloak admin console ถูกขับเคลื่อนด้วย Admin REST API endpoint เดียวกันนั้นมีเอกสารอย่างเป็นทางการและพร้อมให้คุณใช้งาน ซึ่งหมายความว่าคุณสามารถ:

ทำให้การสร้างและกำหนดค่า realm เป็นอัตโนมัติใน CI pipeline
สร้างผู้ใช้และกำหนด role จาก bootstrap script
ลงทะเบียน client โดยผ่านโปรแกรม แทนที่จะคลิกผ่าน wizard

API อยู่ที่ https://<keycloak-host>/admin/realms/<realm>/...

การรับ admin access token

ก่อนเรียก admin endpoint ใดๆ คุณต้องมี Bearer token ที่ออกโดย Keycloak เอง มีสองวิธีทั่วไป

ตัวเลือกที่ 1 — client admin-cli ที่มีอยู่แล้ว

Keycloak มี client ชื่อ admin-cli ใน realm master มาให้ คุณสามารถแลก master-admin credentials เป็น token ได้:

curl -s -X POST https://localhost:8080/realms/master/protocol/openid-connect/token \
  -d client_id=admin-cli \
  -d grant_type=password \
  -d username=admin \
  -d password=admin \
  | jq -r '.access_token'

เก็บผลลัพธ์ไว้ในตัวแปร เช่น TOKEN=$(...) token มีอายุสั้น (โดยทั่วไป 60 วินาที) ดังนั้นให้ขอใหม่ทุกครั้งที่ script ทำงาน

ตัวเลือกที่ 2 — service account เฉพาะทาง

สำหรับ automated pipeline ให้สร้าง confidential client ใน realm ที่คุณจัดการ เปิดใช้ Service accounts roles และกำหนด realm-management role ที่จำเป็น (เช่น manage-users, manage-clients) จากนั้นแลก client credentials:

curl -s -X POST https://localhost:8080/realms/my-app/protocol/openid-connect/token \
  -d client_id=my-admin-client \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d grant_type=client_credentials \
  | jq -r '.access_token'

การเรียก Admin REST API endpoint

เมื่อได้ token แล้ว ส่งเป็น Bearer header ตัวอย่างนี้แสดงรายการผู้ใช้ทั้งหมดใน realm:

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

แทนที่ my-app ด้วยชื่อ realm ของคุณ และ \${TOKEN} ด้วย access token ที่ได้มา

Admin endpoint ทั่วไป:

Operation	Method	Path
แสดงรายการผู้ใช้	GET	`/admin/realms/{realm}/users`
สร้างผู้ใช้	POST	`/admin/realms/{realm}/users`
แสดงรายการ client	GET	`/admin/realms/{realm}/clients`
แสดงรายการ realm role	GET	`/admin/realms/{realm}/roles`

kcadm.sh เป็นทางเลือก

Keycloak มาพร้อม CLI tool ชื่อ kcadm.sh (ภายใน container ที่ /opt/keycloak/bin/kcadm.sh) โดยห่อ Admin REST API ไว้ด้วย syntax ที่เป็นมิตรกว่า:

# Authenticate once
/opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password admin

# List users in a realm
/opt/keycloak/bin/kcadm.sh get users -r my-app

kcadm.sh cache token ไว้ในเครื่อง คุณจึงต้อง authenticate เพียงครั้งเดียวต่อ session สำหรับ script ที่ทำงานภายใน Keycloak container (เช่น ใน Docker entrypoint) kcadm.sh มักง่ายกว่า raw curl

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

ตัวเลือก	Benefit	Cost
`admin-cli` + master admin password	ใช้งานได้ทันทีโดยไม่ต้องตั้งค่าอะไรเพิ่ม เหมาะกับการทดลองหรือ debug ชั่วคราว	ผูกทุก automation กับ super-user credentials ตัวเดียว หากหลุดจะกระทบทั้งระบบ และ rotate ยาก
Service account เฉพาะทาง (confidential client)	จำกัดสิทธิ์ให้เหลือเฉพาะ `realm-management` role ที่จำเป็น rotate secret ได้อิสระต่อ pipeline	ต้องสร้างและดูแล client เพิ่มอีกตัว ต้องกำหนด role ให้ถูกต้องล่วงหน้า
`kcadm.sh` CLI	syntax สั้นกว่า raw curl, cache token ให้อัตโนมัติต่อ session	ใช้ได้เฉพาะเมื่อเข้าถึง shell ของ container/host ได้ ไม่เหมาะกับ automation ที่รันนอก environment ของ Keycloak

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

ทำงานอัตโนมัติทั้งหมดด้วย master admin username/password — เพิ่มความเสียหายเป็นวงกว้างหาก credentials รั่วไหล และ rotate ยากเพราะ credentials นี้ผูกกับทุก script ควรสร้าง service account เฉพาะทางแทน
กำหนด role ให้ service account กว้างเกินความจำเป็น — เผื่อไว้ล่วงหน้าด้วยการให้ realm-management ทุก role ทั้งที่ script ต้องใช้แค่ manage-users เพียงอย่างเดียว เพิ่มความเสี่ยงหาก client secret หลุด
ลืมว่า admin token มีอายุสั้นมาก — เก็บ token ไว้ในตัวแปรแล้วใช้ซ้ำข้าม script run โดยไม่ขอใหม่ ทำให้ automation ล้มเหลวกลางทางด้วย 401 เมื่อ token หมดอายุ (ปกติ ~60 วินาที)

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

CI/CD pipeline สำหรับ config-as-code — ทีม platform จำนวนมากใช้ service account client เพื่อ import/export realm configuration เป็นส่วนหนึ่งของ deployment pipeline แทนที่จะให้ engineer คลิกผ่าน admin console ด้วยมือ

Terraform Keycloak provider — เครื่องมือ infrastructure-as-code อย่าง mrparkers/keycloak provider เรียก Admin REST API เบื้องหลังด้วย service account credentials เพื่อสร้างและจัดการ realm, client และ role แบบ declarative