@digiforce-nc/plugin-auth-oidc

Plugin xác thực qua OpenID Connect (OIDC) — hỗ trợ đăng nhập SSO với Google, Azure AD, Keycloak, Auth0 và bất kỳ Identity Provider nào tuân chuẩn OIDC. Sử dụng thư viện openid-client để giao tiếp với IdP.

Plugin này làm gì?

OIDCAuth kế thừa BaseAuth, đóng vai trò cầu nối giữa Digiforce và Identity Provider bên ngoài. Plugin xử lý toàn bộ luồng Authorization Code: tạo URL đăng nhập, nhận callback, trao đổi token, lấy thông tin user và tạo/liên kết tài khoản nội bộ.

Các tính năng chính

#	Tính năng	Chi tiết
1	Authorization Code flow	Redirect user đến IdP, nhận authorization code qua callback
2	CSRF protection	State parameter chứa CSRF token, lưu trong cookie `digiforce_oidc`
3	RP-initiated logout	Lưu `id_token` trong cookie, gửi lại IdP khi logout
4	Auto-redirect SSO	Tự động redirect đến IdP thay vì hiện form đăng nhập
5	Gateway middleware	Xử lý state resolution cho kiến trúc multi-app

Luồng xác thực

Cấu hình

Tham số	Kiểu	Mô tả
`issuer`	`string`	URL của OIDC Issuer (ví dụ: `https://accounts.google.com`)
`clientId`	`string`	Client ID được cấp bởi IdP
`clientSecret`	`string`	Client Secret
`scope`	`string`	Scope yêu cầu (mặc định: `openid email profile`)
`idTokenSignedResponseAlg`	`string`	Thuật toán ký id_token (mặc định: `RS256`)
`userBindField`	`string`	Field dùng để liên kết user (ví dụ: `email`)
`fieldMap`	`object`	Mapping từ OIDC claims sang local user fields
`http`	`boolean`	Dùng HTTP thay HTTPS cho redirect URI
`port`	`string`	Port tùy chỉnh cho redirect URI
`stateToken`	`string`	Secret key để ký state parameter
`exchangeBodyKeys`	`string[]`	Các key bổ sung gửi kèm khi exchange token
`userInfoMethod`	`string`	Phương thức lấy userinfo: `GET` hoặc `POST`
`accessTokenVia`	`string`	Cách gửi access_token: `header`, `body`, hoặc `query`
`skipSSLVerification`	`boolean`	Bỏ qua kiểm tra SSL (dev only)
`enableRPInitiatedLogout`	`boolean`	Bật RP-initiated logout
`autoRedirect`	`boolean`	Tự động redirect đến IdP khi chưa đăng nhập
`public.autoSignup`	`boolean`	Tự tạo tài khoản nếu user chưa tồn tại

Redirect URI cần đăng ký tại IdP:

{origin}{API_BASE_PATH}oidc:redirect

Ví dụ: https://app.example.com/api/oidc:redirect

API endpoints

Endpoint	Quyền	Mô tả
`oidc:getAuthUrl`	Public	Trả về URL để redirect đến IdP
`oidc:redirect`	Public	Callback nhận code từ IdP, xử lý token exchange
`oidc:checkRedirect`	Public	Kiểm tra trạng thái redirect (dùng cho auto-redirect)

Thành phần client

Thành phần	Mô tả
`OIDCButton`	Nút "Đăng nhập bằng OIDC" trên trang login
`Options`	Form cấu hình OIDC trong Settings → Authentication
`OIDCAutoRedirectProvider`	Provider tự động redirect đến IdP nếu bật `autoRedirect`

Dependencies

Package	Vai trò
`openid-client`	Thư viện OIDC client, xử lý discovery, token exchange, userinfo
`@digiforce-nc/auth`	Base auth framework (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)