Giao diện

FAQ & Troubleshooting — LDAP ​

Các câu hỏi thường gặp và cách xử lý sự cố khi sử dụng plugin LDAP.

Test Connection thất bại ​

Triệu chứng: Nhấn "Test Connection" trong Settings nhưng báo lỗi.

Kiểm tra theo thứ tự:

  1. URL đúng chưa? — Phải bao gồm protocol và port: ldap://host:389 hoặc ldaps://host:636
  2. Bind DN tồn tại không? — Kiểm tra bằng công cụ LDAP (ldapsearch, Apache Directory Studio)
  3. Password đúng không? — Đảm bảo không có khoảng trắng thừa
  4. Firewall cho phép không? — Kiểm tra kết nối từ server Digiforce đến LDAP server trên port tương ứng
  5. Certificate (nếu dùng ldaps://) — CA certificate của LDAP server có trong trust store không?

Test nhanh từ command line:

bash
ldapsearch -H ldap://ad.company.com:389 \
  -D "cn=svc-digiforce,ou=services,dc=company,dc=com" \
  -w "password" \
  -b "ou=employees,dc=company,dc=com" \
  "(objectClass=person)" cn mail

Filter không tìm thấy user ​

Triệu chứng: Test connection OK nhưng đăng nhập báo "User not found".

Nguyên nhân phổ biến:

  1. Placeholder sai — Đảm bảo filter chứa account đúng vị trí. Ví dụ đúng: (mail=account). Plugin thay account bằng giá trị user nhập vào
  2. Search DN quá hẹp — Base DN không bao phủ OU chứa user cần tìm
  3. Scope chưa đúng — Dùng sub để tìm toàn bộ cây con thay vì one (chỉ một cấp)
  4. Attribute không khớp — User nhập email nhưng filter tìm theo uid, hoặc ngược lại

Gỡ lỗi: Dùng ldapsearch với filter đã thay thế account để kiểm tra:

bash
ldapsearch -H ldap://host:389 -D "bindDN" -w "pass" \
  -b "ou=employees,dc=company,dc=com" \
  "(mail=john@company.com)" dn

Attribute mapping không hoạt động ​

Triệu chứng: User tạo thành công nhưng thiếu thông tin (nickname, phone...).

Kiểm tra:

  1. Tên attribute đúng không? — LDAP attribute names phân biệt hoa/thường trên một số server. Kiểm tra tên chính xác từ ldapsearch
  2. Attribute có trong kết quả search không? — Một số LDAP server chỉ trả về attribute được yêu cầu rõ ràng
  3. Local field name đúng không? — Value trong attributeMap phải khớp với field name trong Digiforce user model

Ví dụ attributeMap đúng cho Active Directory:

json
{
  "mail": "email",
  "cn": "nickname",
  "sAMAccountName": "username"
}

Đăng nhập chậm hoặc timeout ​

Nguyên nhân:

  • LDAP server phản hồi chậm (network latency)
  • Search DN quá rộng, trả về nhiều kết quả
  • sizeLimit quá lớn

Giải pháp:

  • Thu hẹp searchDN đến OU cụ thể
  • Sử dụng filter chính xác hơn (tránh wildcard *)
  • Giảm sizeLimit xuống giá trị phù hợp

User LDAP đã bị xóa nhưng vẫn đăng nhập được ​

Khi user bị xóa khỏi LDAP directory, lần đăng nhập tiếp theo sẽ thất bại vì:

  1. Phase 2 (Search) không tìm thấy user → trả lỗi 401

Tuy nhiên, local user vẫn tồn tại trong Digiforce. Nếu muốn vô hiệu hóa hoàn toàn, admin cần xóa hoặc khóa local user thủ công.

Lỗi "filter cannot be set via env" ​

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