xDev Asia

Làm quen Admin Console, tạo admin user đầu tiên, tạo và cấu hình Realm, Realm Settings (General, Login, Email, Themes, Localization, Keys, Security Defenses), Admin CLI (kcadm.sh) và Admin REST API cơ bản.

Keycloak từ Cơ bản đến Nâng cao

Phần 1: Nền tảng Keycloak

xdev.asia

1. Truy cập Admin Console

Sau khi cài đặt Keycloak (standalone hoặc Docker), bạn có thể truy cập Admin Console — giao diện quản trị tập trung cho toàn bộ hệ thống Keycloak.

URL truy cập

Mặc định, Admin Console có tại:

http://localhost:8080/admin

Nếu bạn chạy Keycloak bằng Docker với port mapping khác:

http://localhost:<PORT>/admin

Tạo Admin User đầu tiên

Khi lần đầu truy cập Keycloak, bạn cần tạo initial admin user để đăng nhập vào Admin Console. Có hai cách:

Cách 1: Qua biến môi trường (khuyến nghị cho Docker/Production)

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

Cách 2: Qua welcome page (chỉ khi truy cập từ localhost)

Truy cập http://localhost:8080, bạn sẽ thấy form tạo admin user. Nhập username và password, sau đó click Create.

Cách 3: Qua command line

# Standalone
export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=admin
bin/kc.sh start-dev

Giao diện Admin Console

Sau khi đăng nhập, bạn sẽ thấy giao diện Admin Console với các thành phần chính:

Realm selector (góc trái trên) — chọn realm đang quản lý
Left sidebar — menu điều hướng chính: Clients, Client scopes, Realm roles, Users, Groups, Sessions, Events, Realm settings, Authentication, Identity providers, User federation
Main content area — hiển thị nội dung chi tiết của mục được chọn
User dropdown (góc phải trên) — quản lý tài khoản admin, sign out

2. Tạo Realm đầu tiên

Master Realm vs Custom Realm

Khi cài đặt Keycloak, một realm có tên master được tạo sẵn. Master realm là realm đặc biệt dùng để quản lý các realm khác — không nên sử dụng master realm cho ứng dụng.

Best practices:

Sử dụng master realm chỉ cho super admin quản lý hệ thống Keycloak
Tạo custom realm riêng cho mỗi tổ chức, dự án, hoặc môi trường
Đặt tên realm có ý nghĩa: mycompany-dev, mycompany-staging, mycompany-prod

Tạo Realm qua Admin Console

Click vào realm selector (dropdown góc trái trên, đang hiển thị "master")
Click Create realm
Nhập thông tin:
- Realm name: my-company (chỉ chứa lowercase, numbers, hyphens)
- Enabled: ON
Click Create

Tạo Realm từ JSON file

Bạn có thể import realm từ file JSON — hữu ích cho việc tái tạo cấu hình giữa các môi trường:

{
  "realm": "my-company",
  "enabled": true,
  "displayName": "My Company",
  "displayNameHtml": "<strong>My Company</strong>",
  "sslRequired": "external",
  "registrationAllowed": false,
  "loginWithEmailAllowed": true,
  "duplicateEmailsAllowed": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "bruteForceProtected": true,
  "permanentLockout": false,
  "maxFailureWaitSeconds": 900,
  "minimumQuickLoginWaitSeconds": 60,
  "waitIncrementSeconds": 60,
  "quickLoginCheckMilliSeconds": 1000,
  "maxDeltaTimeSeconds": 43200,
  "failureFactor": 5,
  "defaultSignatureAlgorithm": "RS256",
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000
}

Import qua Admin Console: khi tạo realm, click Browse để chọn file JSON.

3. Realm Settings chi tiết

Sau khi tạo realm, truy cập Realm settings từ sidebar để cấu hình chi tiết.

3.1 Tab General

Setting	Mô tả	Giá trị khuyến nghị
Display name	Tên hiển thị trên login page	Tên công ty/dự án
HTML display name	Hỗ trợ HTML cho tên hiển thị	Logo + tên
Frontend URL	URL mà client sử dụng để kết nối	https://auth.mycompany.com
Require SSL	Yêu cầu SSL cho requests	`external` (dev) / `all` (prod)
User-managed access	Cho phép users quản lý resources (UMA)	OFF (trừ khi cần UMA)
ACR to LoA mapping	Mapping Authentication Context Class Reference	Cấu hình khi cần step-up auth

Cấu hình behavior của trang đăng nhập:

Setting	Mô tả	Mặc định
User registration	Cho phép đăng ký tài khoản mới	OFF
Forgot password	Hiển thị link "Quên mật khẩu"	OFF
Remember me	Checkbox "Ghi nhớ đăng nhập"	OFF
Email as username	Dùng email làm username	OFF
Login with email	Cho phép đăng nhập bằng email	ON
Duplicate emails	Cho phép trùng email	OFF
Verify email	Bắt buộc xác thực email	OFF
Edit username	Cho phép thay đổi username	OFF

Khuyến nghị cho production:

User registration: OFF (hoặc ON với reCAPTCHA)
Forgot password: ON
Remember me: ON
Email as username: Tùy yêu cầu
Login with email: ON
Verify email: ON
Edit username: OFF

3.3 Tab Email

Cấu hình SMTP server để gửi email (verification, reset password, notifications):

Setting	Mô tả
From	Địa chỉ email gửi đi (ví dụ: [email protected])
From display name	Tên hiển thị trong email
Reply to	Địa chỉ reply (ví dụ: [email protected])
Host	SMTP server hostname
Port	SMTP port (587 cho STARTTLS, 465 cho SSL)
Encryption	Bật SSL hoặc STARTTLS
Authentication	Username và password cho SMTP

Ví dụ cấu hình với Gmail SMTP:

Host: smtp.gmail.com
Port: 587
From: [email protected]
Enable StartTLS: ON
Authentication: ON
Username: [email protected]
Password: app-specific-password

3.4 Tab Themes

Tùy chỉnh giao diện cho các trang khác nhau:

Login theme — trang đăng nhập, đăng ký, reset password
Account theme — trang quản lý tài khoản cho users
Admin console theme — giao diện Admin Console
Email theme — template cho emails

Keycloak cung cấp theme keycloak (mặc định) và keycloak.v2 (Account Console v3, React-based). Bạn có thể tạo custom themes — sẽ được đề cập trong bài sau.

3.5 Tab Localization

Hỗ trợ đa ngôn ngữ cho các trang login, account, email:

Bật Internationalization: ON
Chọn Supported locales: en, vi, ja, zh-CN,...
Chọn Default locale: vi (cho giao diện tiếng Việt mặc định)
Tùy chỉnh message bundles cho từng locale nếu cần

3.6 Tab Keys

Quản lý cryptographic keys cho realm — dùng để ký và mã hóa tokens:

Active keys — keys đang được sử dụng để ký tokens
Passive keys — keys cũ vẫn dùng để verify tokens đã ký trước đó
Disabled keys — keys không còn sử dụng

Các key providers mặc định:

Provider	Algorithm	Mục đích
rsa-generated	RS256	Ký JWT tokens
rsa-enc-generated	RSA-OAEP	Mã hóa tokens
hmac-generated	HS512	HMAC signing
aes-generated	AES	Symmetric encryption
ecdsa-generated	ES256	Elliptic curve signing

Key rotation: Thêm key provider mới → key mới trở thành active → key cũ chuyển sang passive → sau một thời gian, disable key cũ.

3.7 Tab Tokens

Cấu hình thời gian sống và behavior của tokens:

Setting	Mô tả	Giá trị khuyến nghị
Default Signature Algorithm	Algorithm ký JWT	RS256
Revoke Refresh Token	Thu hồi refresh token sau khi sử dụng	ON (production)
SSO Session Idle	Thời gian session idle tối đa	30 phút
SSO Session Max	Thời gian session tối đa	10 giờ
Access Token Lifespan	Thời gian sống của access token	5 phút
Client login timeout	Thời gian tối đa cho login flow	5 phút

3.8 Tab Security Defenses

Cấu hình bảo mật cho realm:

Headers:

Header	Giá trị mặc định	Mô tả
X-Frame-Options	SAMEORIGIN	Chống clickjacking
Content-Security-Policy	frame-src 'self'; ...	CSP header
X-Content-Type-Options	nosniff	Chống MIME sniffing
X-XSS-Protection	1; mode=block	XSS filter
Strict-Transport-Security	max-age=31536000	Bắt buộc HTTPS
Referrer-Policy	no-referrer	Kiểm soát Referrer header

Brute Force Detection:

Enabled: ON (bật chống brute force)
Permanent lockout: OFF (tự động unlock sau thời gian)
Max login failures: 5 (sau 5 lần đăng nhập thất bại sẽ bị lock)
Wait increment: 60 seconds (thời gian chờ tăng dần)
Max wait: 900 seconds (thời gian chờ tối đa 15 phút)
Quick login check: 1000 ms (phát hiện login quá nhanh)

4. Admin CLI (kcadm.sh)

Keycloak cung cấp Admin CLI (kcadm.sh) — công cụ command-line để quản trị Keycloak mà không cần truy cập Admin Console.

4.1 Cấu hình Credentials

Trước khi sử dụng Admin CLI, cần đăng nhập:

# Đăng nhập vào Keycloak server bin/kcadm.sh config credentials \ --server http://localhost:8080 \ --realm master \ --user admin \ --password admin Với Docker

docker exec -it keycloak /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin

Lưu ý bảo mật: Trong production, sử dụng --client và --secret thay vì username/password trực tiếp trên command line.

4.2 Quản lý Realm với CLI

Tạo realm mới:

# Tạo realm cơ bản
bin/kcadm.sh create realms \
  -s realm=my-company \
  -s enabled=true \
  -s displayName="My Company"
Tạo realm với nhiều cấu hình
bin/kcadm.sh create realms 

-s realm=my-company 

-s enabled=true 

-s displayName="My Company" 

-s registrationAllowed=false 

-s loginWithEmailAllowed=true 

-s resetPasswordAllowed=true 

-s sslRequired=external 

-s bruteForceProtected=true

Xem danh sách realms:

# Lấy tất cả realms
bin/kcadm.sh get realms --fields realm,enabled,displayName
Output:
[ {
"realm" : "master",
"displayName" : "Keycloak",
"enabled" : true
}, {
"realm" : "my-company",
"displayName" : "My Company",
"enabled" : true
} ]

Xem chi tiết realm:

bin/kcadm.sh get realms/my-company

Cập nhật realm:

bin/kcadm.sh update realms/my-company \
  -s displayName="My Company Production" \
  -s sslRequired=all \
  -s bruteForceProtected=true \
  -s failureFactor=5

Xóa realm:

bin/kcadm.sh delete realms/my-company

4.3 Cấu hình Realm Settings với CLI

Cấu hình Login settings:

bin/kcadm.sh update realms/my-company \
  -s registrationAllowed=true \
  -s resetPasswordAllowed=true \
  -s rememberMe=true \
  -s verifyEmail=true \
  -s loginWithEmailAllowed=true \
  -s duplicateEmailsAllowed=false

Cấu hình Token settings:

bin/kcadm.sh update realms/my-company \
  -s accessTokenLifespan=300 \
  -s ssoSessionIdleTimeout=1800 \
  -s ssoSessionMaxLifespan=36000 \
  -s revokeRefreshToken=true \
  -s refreshTokenMaxReuse=0

Cấu hình SMTP Email:

bin/kcadm.sh update realms/my-company \
  -s 'smtpServer={"host":"smtp.gmail.com","port":"587","from":"[email protected]","fromDisplayName":"My Company","starttls":"true","auth":"true","user":"[email protected]","password":"app-password"}'

Export realm configuration:

# Export realm sang file JSON
bin/kcadm.sh get realms/my-company > my-company-realm.json

5. Admin REST API

Keycloak cung cấp Admin REST API cho phép quản trị hoàn toàn qua HTTP requests — phù hợp cho automation, CI/CD, và tích hợp với các hệ thống khác.

5.1 Lấy Access Token

Trước khi gọi API, cần lấy access token từ master realm:

# Lấy access token bằng admin credentials ACCESS_TOKEN=$(curl -s -X POST \ "http://localhost:8080/realms/master/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin" \ -d "password=admin" \ -d "grant_type=password" \ -d "client_id=admin-cli" | jq -r '.access_token')

echo $ACCESS_TOKEN

5.2 Quản lý Realm với API

Lấy danh sách realms:

curl -s -X GET \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" | jq '.[].realm'

Tạo realm mới:

curl -s -X POST \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "my-company",
    "enabled": true,
    "displayName": "My Company",
    "sslRequired": "external",
    "registrationAllowed": false,
    "loginWithEmailAllowed": true,
    "resetPasswordAllowed": true,
    "bruteForceProtected": true,
    "failureFactor": 5
  }'

Lấy chi tiết realm:

curl -s -X GET \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

Cập nhật realm:

curl -s -X PUT \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Company Updated",
    "sslRequired": "all"
  }'

Xóa realm:

curl -s -X DELETE \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

5.3 Các API Endpoints quan trọng

Endpoint	Method	Mô tả
/admin/realms	GET	Danh sách realms
/admin/realms	POST	Tạo realm mới
/admin/realms/{realm}	GET	Chi tiết realm
/admin/realms/{realm}	PUT	Cập nhật realm
/admin/realms/{realm}	DELETE	Xóa realm
/admin/realms/{realm}/users	GET	Danh sách users
/admin/realms/{realm}/users	POST	Tạo user
/admin/realms/{realm}/clients	GET	Danh sách clients
/admin/realms/{realm}/roles	GET	Danh sách realm roles
/admin/realms/{realm}/groups	GET	Danh sách groups
/admin/realms/{realm}/events	GET	Events log

5.4 Sử dụng Postman

Keycloak cung cấp OpenAPI spec cho Admin REST API. Bạn có thể import vào Postman hoặc Swagger UI để dễ dàng khám phá và test API:

# OpenAPI spec URL
http://localhost:8080/admin/realms/{realm}/.well-known/openid-configuration

6. Bài tập thực hành

Thực hiện các bài tập sau để củng cố kiến thức:

Tạo realm "dev-company" qua Admin Console với các settings:
- Display name: "Dev Company"
- Login with email: ON
- User registration: ON
- Forgot password: ON
- Verify email: ON
- Remember me: ON
Cấu hình Brute Force Detection cho realm vừa tạo:
- Max login failures: 3
- Wait increment: 120 seconds
- Max wait: 600 seconds
Sử dụng kcadm.sh để tạo realm "staging-company" với cấu hình tương tự
Sử dụng Admin REST API (curl) để tạo realm "test-company" và verify bằng cách lấy danh sách realms
Export realm "dev-company" sang JSON và import lại với tên khác

7. Tổng kết

Trong bài này, bạn đã học:

Cách truy cập và sử dụng Admin Console
Tạo admin user đầu tiên qua nhiều phương thức
Tạo và cấu hình Realm — đơn vị quản lý chính trong Keycloak
Hiểu các Realm Settings quan trọng: General, Login, Email, Themes, Localization, Keys, Tokens, Security Defenses
Sử dụng Admin CLI (kcadm.sh) để quản trị qua command line
Sử dụng Admin REST API để tự động hóa quản trị

Bài tiếp theo sẽ hướng dẫn chi tiết về quản lý Users, Groups và User Profile trong Keycloak.

Bài 3: Admin Console và tạo Realm đầu tiên

1. Truy cập Admin Console

URL truy cập

Tạo Admin User đầu tiên

Giao diện Admin Console

2. Tạo Realm đầu tiên

Master Realm vs Custom Realm

Tạo Realm qua Admin Console

Tạo Realm từ JSON file

3. Realm Settings chi tiết

3.1 Tab General

3.3 Tab Email

3.4 Tab Themes

3.5 Tab Localization

3.6 Tab Keys

3.7 Tab Tokens

3.8 Tab Security Defenses

4. Admin CLI (kcadm.sh)

4.1 Cấu hình Credentials

Với Docker

4.2 Quản lý Realm với CLI

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

`} ]`

4.3 Cấu hình Realm Settings với CLI

5. Admin REST API

5.1 Lấy Access Token

5.2 Quản lý Realm với API

5.3 Các API Endpoints quan trọng

5.4 Sử dụng Postman

6. Bài tập thực hành

7. Tổng kết

Bài 3: Admin Console và tạo Realm đầu tiên

1. Truy cập Admin Console

URL truy cập

Tạo Admin User đầu tiên

Giao diện Admin Console

2. Tạo Realm đầu tiên

Master Realm vs Custom Realm

Tạo Realm qua Admin Console

Tạo Realm từ JSON file

3. Realm Settings chi tiết

3.1 Tab General

3.2 Tab Login

3.3 Tab Email

3.4 Tab Themes

3.5 Tab Localization

3.6 Tab Keys

3.7 Tab Tokens

3.8 Tab Security Defenses

4. Admin CLI (kcadm.sh)

4.1 Cấu hình Credentials

Với Docker

4.2 Quản lý Realm với CLI

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

} ]

4.3 Cấu hình Realm Settings với CLI

5. Admin REST API

5.1 Lấy Access Token

5.2 Quản lý Realm với API

5.3 Các API Endpoints quan trọng

5.4 Sử dụng Postman

6. Bài tập thực hành

7. Tổng kết

`} ]`