Tham số cấu hình LDAP

Tài liệu chi tiết tất cả tham số cấu hình của plugin @digiforce-nc/plugin-auth-ldap.

Tham số kết nối

Tham số	Kiểu	Mặc định	Mô tả
url	string	—	URL kết nối LDAP server. Hỗ trợ ldap:// (port 389) và ldaps:// (port 636). Ví dụ: ldap://ad.company.com:389
bindDN	string	—	Distinguished Name của service account dùng để bind và search. Ví dụ: cn=svc-app,ou=services,dc=company,dc=com
bindPassword	string	—	Mật khẩu của service account

Tham số tìm kiếm

Tham số	Kiểu	Mặc định	Mô tả
searchDN	string	—	Base DN làm gốc tìm kiếm. Ví dụ: ou=employees,dc=company,dc=com
filter	string	—	LDAP filter với placeholder account. Plugin thay thế account bằng giá trị user nhập vào. Ví dụ: (mail=account), (sAMAccountName=account)
scope	string	sub	Phạm vi tìm kiếm: base (chỉ entry gốc), one (một cấp con), sub (toàn bộ cây con)
sizeLimit	number	1000	Giới hạn tối đa số kết quả trả về từ LDAP server

Giới hạn biến môi trường

Tham số filter không thể cấu hình qua biến môi trường (nằm trong optionsKeysNotAllowedInEnv). Phải cấu hình trực tiếp trong giao diện Settings hoặc qua API.

Tham số user binding

Tham số	Kiểu	Mặc định	Mô tả
attributeMap	object	{}	Mapping từ LDAP attributes sang local user fields. Key là tên LDAP attribute, value là tên local field
userBindField	string	email	Field dùng để liên kết LDAP user với local user. Giá trị LDAP attribute (sau khi map) phải khớp với giá trị field này trong local user
public.autoSignup	boolean	true	Tự động tạo tài khoản local nếu user LDAP chưa có tài khoản trong Digiforce

Ví dụ attributeMap

Active Directory

{
  "mail": "email",
  "cn": "nickname",
  "sAMAccountName": "username",
  "telephoneNumber": "phone",
  "department": "department"
}

OpenLDAP

{
  "mail": "email",
  "cn": "nickname",
  "uid": "username",
  "mobile": "phone"
}

Ví dụ filter

Mục đích	Filter
Tìm theo email	(mail=account)
Tìm theo sAMAccountName (AD)	(sAMAccountName=account)
Tìm theo uid (OpenLDAP)	(uid=account)
Tìm theo email HOẶC username	(|(mail=account)(uid=account))
Chỉ user thuộc group cụ thể	(&(uid=account)(memberOf=cn=staff,ou=groups,dc=company,dc=com))

Placeholder account

Placeholder account trong filter được thay thế bằng giá trị mà user nhập vào form đăng nhập. Ví dụ nếu user nhập john@company.com, filter (mail=account) trở thành (mail=john@company.com).

Ví dụ cấu hình đầy đủ

{
  "url": "ldaps://ad.company.com:636",
  "bindDN": "cn=svc-digiforce,ou=services,dc=company,dc=com",
  "bindPassword": "service-account-password",
  "searchDN": "ou=employees,dc=company,dc=com",
  "filter": "(sAMAccountName=account)",
  "scope": "sub",
  "sizeLimit": 1000,
  "attributeMap": {
    "mail": "email",
    "cn": "nickname",
    "sAMAccountName": "username"
  },
  "userBindField": "email",
  "public": {
    "autoSignup": true
  }
}

Kiểm tra kết nối

Sử dụng endpoint ldap:test (yêu cầu quyền admin) để test:

1. Bind test: Kết nối đến LDAP server và bind bằng service account
2. Search test: Thực hiện search với filter mẫu để xác nhận cấu hình đúng

Nếu bind thất bại, kiểm tra:

• URL có đúng protocol và port không
• Bind DN có tồn tại trong directory không
• Password có đúng không
• Firewall có cho phép kết nối từ server Digiforce đến LDAP server không