Thông tin bạn cần nhận
Đội vận hành DBIZ cung cấp các giá trị dưới đây cho từng hệ thống. Các trang trong mục này dùng chúng làm chỗ giữ chỗ.Client secret (chỉ có ở client confidential) được cấp qua kho secret của nền tảng. Không gửi secret qua chat hay email, không đưa vào mã nguồn hay image.
Issuer
Issuer là định danh của nơi phát token, có dạnghttps://<id-host>/realms/<realm>. Giá trị này nằm trong claim iss của mọi token.
- So khớp
isschính xác từng ký tự, không có/ở cuối. - Dù app gọi Keycloak qua địa chỉ nào (kể cả địa chỉ nội bộ),
issvẫn là địa chỉ công khai. - Khai issuer cho thư viện OIDC rồi để thư viện tự đọc discovery, thay vì ghi cứng từng endpoint.
Endpoint
Mọi endpoint đều có trong tài liệu discovery:https://<id-host>/realms/<realm>/.well-known/openid-configuration.
Token và phiên
- Token ký bằng RS256. Kiểm chữ ký bằng JWKS, cache theo
kidvà tải lại khi gặpkidlạ. - Access token sống ngắn (mặc định của Keycloak là 5 phút). App phải dùng refresh token để lấy access token mới.
- Khi refresh token báo
invalid_grant, phiên đã hết hạn: xoá token và cho người dùng đăng nhập lại. - Thời gian phiên SSO và phiên offline do realm quy định. Hỏi đội vận hành nếu app cần phiên dài.
Claim trong token
Phân quyền trong app nên dựa vào
groups hoặc realm_access.roles, không dựa vào tên hiển thị hay email.
Chọn kiểu client
Web SPA
App chạy hoàn toàn trên trình duyệt. Client public, PKCE S256.
Web có backend
Backend tự làm code flow hoặc đứng sau oauth2-proxy. Client confidential.
API kiểm token
API chỉ nhận và kiểm token do app khác gửi tới.
Mobile
iOS, Android, Flutter. Client public, PKCE, redirect về app.
Desktop và CLI
Redirect về loopback 127.0.0.1, hoặc device grant cho CLI.
Service-to-service
Dịch vụ gọi dịch vụ, không có người dùng. Client credentials.
Quy tắc chung cho mọi app
- Khai issuer
https://<id-host>/realms/<realm>và để thư viện đọc discovery. - Kiểm
isskhớp tuyệt đối. - Scope tối thiểu là
openid. Các scopeemail,profile,roles,groupsthường đã là mặc định. - Dùng Authorization Code (kèm PKCE với client public). Không dùng Implicit.
- Không lấy token bằng mật khẩu (Direct Access Grants luôn tắt). Người dùng luôn đăng nhập trên trang của Keycloak.
- Khi đăng xuất, kết thúc luôn phiên Keycloak. Xem Đăng xuất.