> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tích hợp đăng nhập một lần (SSO) với nền tảng DBIZ

> Nền tảng DBIZ dùng Keycloak và OpenID Connect cho đăng nhập một lần. Tìm hiểu issuer, endpoint, claim trong token và cách chọn kiểu client cho app.

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ỗ.

| Ký hiệu | Ý nghĩa | Ví dụ |
| - | - | - |
| `<id-host>` | Host công khai của Keycloak | `id.example.com` |
| `<realm>` | Realm của khách hàng | `acme` |
| `<client-id>` | Mã client cấp riêng cho app của bạn | `report-acme` |
| `<app-host>` | Host công khai của app | `report.example.com` |

> [!NOTE]
>
> 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`.

| Mục | Đường dẫn (sau issuer) |
| - | - |
| Discovery | `/.well-known/openid-configuration` |
| Authorization | `/protocol/openid-connect/auth` |
| Token | `/protocol/openid-connect/token` |
| UserInfo | `/protocol/openid-connect/userinfo` |
| End session (đăng xuất) | `/protocol/openid-connect/logout` |
| JWKS (khoá kiểm chữ ký) | `/protocol/openid-connect/certs` |
| Device authorization | `/protocol/openid-connect/auth/device` |
| Introspection | `/protocol/openid-connect/token/introspect` |
| Revocation | `/protocol/openid-connect/revoke` |

## 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

| Claim | Nội dung | Ghi chú |
| - | - | - |
| `sub` | Định danh người dùng trong Keycloak (UUID) | Không đổi khi người dùng đổi email |
| `email`, `preferred_username`, `name` | Thông tin hồ sơ | Có sẵn qua scope mặc định `email`, `profile` |
| `groups` | Danh sách group của người dùng | Ghi đường dẫn đầy đủ, ví dụ `/nhom-cha/NHOM_CON` |
| `realm_access.roles` | Role cấp realm | Chỉ có trong access token |
| `resource_access.<client-id>.roles` | Role riêng của một client | Chỉ có khi client có role |
| `organization` | Organization người dùng thuộc về | Scope tuỳ chọn: cần gắn làm mặc định cho client hoặc xin khi đăng nhập |
| `aud` | Đối tượng nhận token | Mặc định thường là `account`. Muốn `aud` chứa client của bạn thì client cần audience mapper |
| `azp` | Client đã xin token | Backend nên kiểm để biết token đến từ app nào |

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

> [card] [Web SPA](https://docs.dbiz.com/sso/web-spa.md)
>
> App chạy hoàn toàn trên trình duyệt. Client public, PKCE S256.

> [card] [Web có backend](https://docs.dbiz.com/sso/web-backend.md)
>
> Backend tự làm code flow hoặc đứng sau oauth2-proxy. Client confidential.

> [card] [API kiểm token](https://docs.dbiz.com/sso/api-backend.md)
>
> API chỉ nhận và kiểm token do app khác gửi tới.

> [card] [Mobile](https://docs.dbiz.com/sso/mobile.md)
>
> iOS, Android, Flutter. Client public, PKCE, redirect về app.

> [card] [Desktop và CLI](https://docs.dbiz.com/sso/desktop-cli.md)
>
> Redirect về loopback 127.0.0.1, hoặc device grant cho CLI.

> [card] [Service-to-service](https://docs.dbiz.com/sso/service-to-service.md)
>
> 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](https://docs.dbiz.com/sso/dang-xuat.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.