Keycloak — Identity & Access Management cho Java/Spring Boot

Một tài liệu độc lập để hiểu Keycloak từ mental model đến production: realm, client, role, OIDC/OAuth2, token, session, MFA, federation, service account, token exchange, reverse proxy, TLS, HA, observability, security và debugging. Baseline nội dung: Keycloak 26.7.3.

1. Mental model: Keycloak đứng ở đâu?

Keycloak là Identity and Access Management (IAM) server. Ứng dụng không nên tự giữ password, tự xây SSO hoặc tự phát token nếu không thật sự cần. Thay vào đó, ứng dụng chuyển việc xác thực cho Keycloak và chỉ tin các token được ký bởi issuer mà nó đã cấu hình.

Browser / App
    |
    | 1) authorize / login
    v
Keycloak  ---- identity provider / LDAP / AD
    |
    | 2) code -> tokens
    v
Application / API
    |
    | 3) Bearer access_token
    v
Resource Server

2. Realm, user, group, role và client

3. OIDC/OAuth2 flow cho ứng dụng

3.1 Authorization Code Flow

Đây là flow điển hình cho web app và browser-based login. User được redirect sang Keycloak, đăng nhập tại đó, client nhận authorization code rồi đổi code lấy token. Với public client, PKCE là lớp bảo vệ quan trọng.

GET /realms/{realm}/protocol/openid-connect/auth
  ?client_id=my-app
  &response_type=code
  &redirect_uri=https://app.example.com/callback
  &scope=openid
  &code_challenge=...
  &code_challenge_method=S256

3.2 Client Credentials

Dùng cho machine-to-machine khi không có end-user. Trong Keycloak, service account của client là identity thực thi flow này.

POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=worker&client_secret=...

4. Token, claim, scope và session

Ba token thường gặp là access token, ID token và refresh token. Access token phục vụ API/resource server; ID token nói về authentication event và user cho client; refresh token dùng lấy access token mới mà không bắt user đăng nhập lại ngay.

JWT signature giúp resource server xác minh integrity và issuer. Nhưng token còn cần được kiểm tra iss, thời gian hiệu lực, audience phù hợp và các claim/role cần thiết.

5. Roles, scopes và authorization

RBAC cơ bản có thể thực hiện bằng realm role/client role. Với quyền phức tạp hơn, Keycloak Authorization Services hỗ trợ resource, scope, policy và permission. Tuy nhiên, domain authorization rất chi tiết thường vẫn nên nằm trong application/domain service thay vì đẩy toàn bộ vào IAM.

Authentication: "Bạn là ai?"
Coarse authorization: "Bạn có role REPORT_VIEWER không?"
Domain authorization: "Bạn có được xem invoice 981 của tenant A không?"

Nguyên tắc thực tế: Keycloak quản lý identity và coarse-grained entitlements; application vẫn chịu trách nhiệm với invariant/domain rule.

6. Authentication flow, MFA và required actions

Authentication flow là pipeline execution quyết định user phải đi qua bước nào. Browser flow có thể gồm username/password, conditional OTP, WebAuthn hoặc identity provider redirect. Required Actions dùng cho các việc như đổi password, cấu hình OTP hoặc cập nhật profile.

• Dùng MFA cho admin và tài khoản nhạy cảm.
• Không copy built-in flow rồi sửa vô hạn mà không ghi lại mục đích; flow tùy biến là cấu hình bảo mật cần version-control/export.
• Kiểm thử login, reset password, email verification, logout, expired session và account lockout.

7. Identity brokering và user federation

Identity brokering cho phép Keycloak nhận authentication từ external IdP như một OIDC/SAML provider khác. User federation kết nối user storage như LDAP/Active Directory để Keycloak dùng hoặc đồng bộ identity từ nguồn đó.

8. Service account và token exchange

Service account phù hợp cho backend service cần token của chính nó. Khi một service đang cầm token của user nhưng cần token nhắm tới service khác, token exchange có thể giúp tránh chuyển tiếp token quá rộng.

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<user-access-token>
audience=target-service

9. Spring Boot resource server mental model

Với Spring Security, ưu tiên OIDC/OAuth2 support chuẩn. Resource server chỉ cần issuer/JWK metadata để verify token, thay vì phụ thuộc adapter Keycloak cũ.

# application.yml (conceptual)
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://sso.example.com/realms/acme

// Authorization ở app
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/health").permitAll()
    .requestMatchers("/admin/**").hasRole("ADMIN")
    .anyRequest().authenticated());

10. Production deployment: build, database, hostname, TLS

Keycloak hiện dùng Quarkus distribution. Production nên dùng start, không dùng start-dev. Container nên được build/optimize trước để giảm startup work ở runtime.

# Ví dụ conceptual
/opt/keycloak/bin/kc.sh build --db=postgres
/opt/keycloak/bin/kc.sh start --optimized \
  --hostname=https://sso.example.com \
  --health-enabled=true \
  --metrics-enabled=true

• Dùng external relational database cho production; backup DB là một phần của upgrade plan.
• Cấu hình hostname rõ ràng để tránh URL/issuer bị suy ra từ request không tin cậy.
• Port management mặc định là 9000; không proxy public health/metrics nếu không cần.
• Secrets phải đi qua secret manager/environment injection phù hợp, không hard-code vào image/repo.

11. Reverse proxy và TLS

Ở production, Keycloak thường nằm sau reverse proxy/load balancer. Với TLS re-encrypt hoặc edge termination, cấu hình proxy-headers đúng loại header proxy thực sự ghi đè. Với TLS passthrough, không bật proxy-headers; dùng PROXY protocol nếu cần truyền real client IP.

# Re-encrypt / trusted forwarded headers
kc.sh start \
  --hostname=https://sso.example.com \
  --proxy-headers=xforwarded \
  --proxy-trusted-addresses=10.0.0.0/8

12. Cluster, cache, session và HA

Cluster nhiều node dùng distributed caches và cần database chia sẻ. Session affinity có thể cải thiện locality, nhưng thiết kế HA không nên giả định sticky session là cơ chế correctness duy nhất. Với multi-site hoặc topology phức tạp, dùng hướng dẫn HA chính thức thay vì tự ghép cache remote theo cấu hình cũ.

• Kiểm tra database latency, connection pool và transaction behavior.
• Hiểu distinction giữa online session, offline session và persistent user sessions.
• Test rolling/upgrade path theo version thực tế; patch rolling update support có điều kiện từ nhánh 26.6+.

13. Health, metrics, logs và OpenTelemetry

Bật health/metrics khi cần vận hành. Container docs hiện mô tả các endpoint management như /health, /health/ready, /health/live và /metrics trên port 9000 khi feature tương ứng được bật.

Những thứ nên monitor: login failure rate, request latency, DB pool, JVM/GC, cache health, cluster membership, HTTP 4xx/5xx, token endpoint latency và admin events.

14. Security checklist production

• Không chạy start-dev ở production.
• Không dùng master realm cho application users.
• Bảo vệ admin console/API; tách hostname hoặc network policy nếu cần.
• Không public management port 9000.
• Hostname cố định; proxy headers chỉ tin từ proxy đã kiểm soát.
• Client secret phải rotate; public client không có secret để “giấu”.
• Redirect URI phải chặt, tránh wildcard quá rộng.
• Access token TTL ngắn hợp lý; refresh/session policy phù hợp risk.
• Enable MFA cho admin và nhóm nhạy cảm.
• Audit admin events và authentication events cần thiết.
• Backup database trước upgrade; đọc migration notes từng version.
• Không chỉ decode JWT — phải verify signature/issuer/expiry/audience theo contract.

15. Debugging theo symptom

16. 20 câu hỏi phỏng vấn Keycloak

1. Keycloak giải quyết bài toán gì và app còn phải tự chịu trách nhiệm phần nào?
2. Realm khác client như thế nào?
3. Realm role và client role nên dùng khi nào?
4. Authorization Code Flow hoạt động ra sao?
5. PKCE bảo vệ vấn đề gì?
6. Access token khác ID token như thế nào?
7. Tại sao decode JWT chưa đủ để trust token?
8. Issuer và audience có vai trò gì?
9. Refresh token nên được bảo vệ khác access token ra sao?
10. Service account trong Keycloak là gì?
11. Khi nào dùng Client Credentials?
12. Identity brokering khác user federation như thế nào?
13. Authentication flow và Required Action khác nhau ra sao?
14. MFA nên được áp dụng ở đâu?
15. Vì sao wildcard redirect URI nguy hiểm?
16. Keycloak đứng sau reverse proxy cần lưu ý gì?
17. Tại sao không nên expose port 9000 ra internet?
18. Token exchange giúp giải quyết use case nào?
19. Keycloak HA phụ thuộc database/cache như thế nào?
20. Bạn debug case login thành công nhưng Spring API trả 403 như thế nào?

17. 6 labs thực hành

18. Version notes cần nhớ

• Baseline tài liệu: 26.7.3.
• Standard Token Exchange V2 là supported path; legacy V1 là deprecated/preview.
• Rolling update cho patch releases có support từ 26.6.0 theo điều kiện trong upgrade guide.
• Upgrade phải đọc migration notes từng version và backup database/config trước khi thay server.