Skip to main content
Nền tảng DBIZ xác thực người dùng bằng Keycloak theo chuẩn OpenID Connect (OIDC). App của bạn không tự giữ mật khẩu: người dùng đăng nhập trên trang của Keycloak, app nhận token và đọc danh tính, nhóm, vai trò từ token. Trang này giới thiệu các khái niệm chung, các phần sau hướng dẫn kết nối theo từng loại app.

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ạng https://<id-host>/realms/<realm>. Giá trị này nằm trong claim iss của mọi token.
  • So khớp iss chí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ộ), iss vẫ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 kid và tải lại khi gặp kid lạ.
  • 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

  1. Khai issuer https://<id-host>/realms/<realm> và để thư viện đọc discovery.
  2. Kiểm iss khớp tuyệt đối.
  3. Scope tối thiểu là openid. Các scope email, profile, roles, groups thường đã là mặc định.
  4. Dùng Authorization Code (kèm PKCE với client public). Không dùng Implicit.
  5. 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.
  6. Khi đăng xuất, kết thúc luôn phiên Keycloak. Xem Đăng xuất.