@digiforce-nc/plugin-auth-saml

Plugin xác thực qua SAML 2.0 — hỗ trợ SSO với Okta, OneLogin, Azure AD, ADFS và bất kỳ Identity Provider nào tuân chuẩn SAML. Sử dụng thư viện @node-saml/node-saml để xử lý SAML assertion.

Plugin này làm gì?

SAMLAuth kế thừa BaseAuth, triển khai vai trò Service Provider (SP) trong luồng SAML 2.0 Web Browser SSO Profile. Plugin tạo AuthnRequest gửi đến IdP, nhận SAMLResponse qua HTTP POST binding, validate assertion và trích xuất user profile.

Các khái niệm SAML

Thuật ngữ	Vai trò trong plugin
Service Provider (SP)	Digiforce — nơi user muốn truy cập
Identity Provider (IdP)	Okta, Azure AD... — nơi user đăng nhập
SP Entity ID	Tên định danh SP = tên authenticator trong Digiforce
Assertion	XML chứa thông tin user, được IdP ký số
ACS URL	Callback URL nhận SAMLResponse (POST binding)

Luồng xác thực

Callback URL (ACS) cần đăng ký tại IdP:

{http|https}://{host}{API_BASE_PATH}saml:redirect?authenticator={name}&__appName={app}

Ví dụ: https://app.example.com/api/saml:redirect?authenticator=okta-sso&__appName=main

Cấu hình

Tham số	Kiểu	Mô tả
`ssoUrl`	`string`	IdP SSO URL — nơi gửi AuthnRequest
`certificate`	`string`	Certificate (PEM) của IdP để verify assertion signature
`idpIssuer`	`string`	Entity ID của IdP (phải khớp Issuer trong SAMLResponse)
`signResponse`	`boolean`	Yêu cầu toàn bộ Response phải được ký
`signAssertion`	`boolean`	Yêu cầu Assertion bên trong phải được ký
`signatureAlgorithm`	`string`	Thuật toán ký: `sha1`, `sha256`, `sha512`
`http`	`boolean`	Dùng HTTP thay HTTPS cho callback URL
`userBindField`	`string`	Field dùng để liên kết user (ví dụ: `email`)
`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

API endpoints

Endpoint	Quyền	Mô tả
`saml:getAuthUrl`	Public	Trả về URL redirect đến IdP (chứa SAMLRequest)
`saml:redirect`	Public	ACS endpoint — nhận SAMLResponse POST từ IdP
`saml:checkRedirect`	Public	Kiểm tra trạng thái redirect (cho auto-redirect)

Thành phần client

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

Dependencies

Package	Vai trò
`@node-saml/node-saml`	Thư viện xử lý SAML request/response, validate assertion
`@digiforce-nc/auth`	Base auth framework (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)