@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)

Mục lục chi tiết

• Hướng dẫn cài đặt
• Tham số cấu hình
• Chi tiết luồng xác thực
• FAQ & Troubleshooting