@digiforce-nc/plugin-auth-ldap

Plugin xác thực qua LDAP / Active Directory — cho phép user đăng nhập bằng tài khoản doanh nghiệp từ LDAP server (OpenLDAP, Microsoft AD, FreeIPA...). Sử dụng thư viện ldapjs để kết nối và xác thực trực tiếp.

Plugin này làm gì?

LDAPAuth kế thừa BaseAuth, thực hiện xác thực trực tiếp với LDAP server — không qua redirect hay callback như OAuth. Plugin bind vào LDAP bằng service account, tìm kiếm user theo filter, rồi bind lại bằng mật khẩu user để xác minh.

Đặc điểm chính

#	Đặc điểm	Chi tiết
1	Direct authentication	Không redirect, không callback — xác thực trực tiếp qua LDAP bind
2	Two-phase bind	Bind service account để search → bind user DN để verify password
3	Flexible filter	Filter hỗ trợ placeholder (mail=PLACEHOLDER) thay bằng account nhập vào
4	Test connection	Admin có thể test kết nối LDAP trước khi bật cho user
5	Attribute mapping	Map LDAP attributes (cn, mail, uid...) sang local user fields

Luồng xác thực

Cấu hình

Tham số	Kiểu	Mô tả
url	string	URL kết nối LDAP (ví dụ: ldap://ad.company.com:389)
bindDN	string	Distinguished Name của service account để search
bindPassword	string	Mật khẩu service account
searchDN	string	Base DN để tìm kiếm user (ví dụ: ou=users,dc=company,dc=com)
filter	string	LDAP filter với placeholder account (ví dụ: (mail=PLACEHOLDER))
scope	string	Phạm vi search: base, one, hoặc sub
sizeLimit	number	Giới hạn số kết quả trả về
attributeMap	object	Mapping LDAP attributes → local fields (ví dụ: cn → nickname)
userBindField	string	Field dùng để liên kết LDAP user với local user
public.autoSignup	boolean	Tự tạo tài khoản nếu user chưa tồn tại

Ví dụ cấu hình Active Directory

{
  "url": "ldap://ad.company.com:389",
  "bindDN": "cn=svc-digiforce,ou=services,dc=company,dc=com",
  "bindPassword": "secret",
  "searchDN": "ou=employees,dc=company,dc=com",
  "filter": "(sAMAccountName=PLACEHOLDER)",
  "scope": "sub",
  "attributeMap": {
    "mail": "email",
    "cn": "nickname",
    "sAMAccountName": "username"
  }
}

API endpoints

Endpoint	Quyền	Mô tả
auth:signIn	Public	Đăng nhập — gửi kèm header X-Authenticator: ldap-{name}
ldap:test	Admin	Test kết nối LDAP (bind + search thử)

Thành phần client

Thành phần	Mô tả
LDAPForm	Form đăng nhập LDAP (account + password) trên trang login
Options	Form cấu hình LDAP trong Settings, có nút Test Connection

Dependencies

Package	Vai trò
ldapjs	Thư viện LDAP client cho Node.js
@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