Giao diện
Hướng dẫn cài đặt — IDP OAuth
Tổng quan
Plugin @digiforce-nc/plugin-idp-oauth biến DigiForce thành OAuth 2.1 / OpenID Connect Identity Provider (IdP), cho phép ứng dụng bên thứ ba đăng nhập bằng tài khoản DigiForce. Plugin sử dụng thư viện oidc-provider và jose để xử lý toàn bộ flow OAuth chuẩn.
Phân biệt
plugin-auth-oidc: DigiForce là client — đăng nhập bằng provider bên ngoài (Google, Azure AD)plugin-idp-oauth: DigiForce là server (IdP) — cung cấp đăng nhập cho ứng dụng bên ngoài
Yêu cầu
- Server DigiForce đang chạy với HTTPS (bắt buộc cho OAuth 2.1)
- Biết Redirect URI (callback URL) của ứng dụng bên thứ ba
Bước 1: Kích hoạt plugin
Vào Settings → Plugin Manager, tìm plugin-idp-oauth và bật lên.
Bước 2: Tạo OAuth Application
Vào Settings → IDP OAuth → Applications, nhấn Create:
| Trường | Mô tả | Bắt buộc |
|---|---|---|
| Application Name | Tên ứng dụng (hiển thị trên consent screen) | ✅ |
| Client ID | Tự động sinh — cung cấp cho ứng dụng bên ngoài | Tự động |
| Client Secret | Tự động sinh — giữ bí mật, chỉ hiển thị một lần | Tự động |
| Redirect URIs | Danh sách URL callback cho phép (phải khớp chính xác) | ✅ |
| Scopes | Quyền truy cập: openid, profile, email, offline_access | ✅ |
| Grant Types | authorization_code, refresh_token | ✅ |
Bảo mật
Client Secret chỉ hiển thị một lần khi tạo. Hãy lưu lại ngay. Nếu mất, cần tạo secret mới.
Bước 3: Cấu hình ứng dụng bên ngoài
Cung cấp cho ứng dụng bên thứ ba các endpoint sau:
| Endpoint | URL |
|---|---|
| Authorization | https://your-domain/api/idpOAuth/auth |
| Token | https://your-domain/api/idpOAuth/token |
| UserInfo | https://your-domain/api/idpOAuth/me |
| JWKS | https://your-domain/api/idpOAuth/jwks |
| Discovery (OAuth) | https://your-domain/api/.well-known/oauth-authorization-server |
| Discovery (OIDC) | https://your-domain/api/.well-known/openid-configuration |
| Interaction | https://your-domain/api/idpOAuth/interaction/ |
TIP
Nếu ứng dụng hỗ trợ auto-discovery, chỉ cần cung cấp Discovery URL. Ứng dụng sẽ tự lấy các endpoint còn lại.
Bước 4: Kiểm tra luồng đăng nhập
Kiến trúc middleware
Plugin đăng ký 3 middleware vào ứng dụng, tất cả chạy trước dataSource:
| Middleware | Tag | Chức năng |
|---|---|---|
idp-oauth-provider | Provider dispatch | Chặn request đến path OAuth (/api/idpOAuth/*) và chuyển đến oidc-provider |
idp-oauth-resource-auth | Resource auth | Xác thực Bearer token trên mọi API request |
idp-oauth-interaction | Interaction handler | Xử lý trang đăng nhập và consent (GET/POST) |
Lưu ý quan trọng
- HTTPS bắt buộc: OAuth 2.1 yêu cầu HTTPS để bảo vệ token và authorization code. Trong môi trường development có thể dùng HTTP nhưng không khuyến nghị.
- Redirect URI phải khớp chính xác: Bao gồm protocol (
http/https), domain, port, path, và trailing slash. - Client Secret phải được bảo mật: Không commit vào source control, không expose trên client-side.
- Plugin sử dụng in-memory cache cho bridge token — token sẽ mất khi restart server.