LDAP Integration Guide

Overview

Fess supports integration with LDAP (Lightweight Directory Access Protocol) servers, enabling authentication and user management in enterprise environments.

LDAP integration enables:

  • User authentication with Active Directory or OpenLDAP

  • Group-based access control

  • Automatic user information synchronization

Supported LDAP Servers

Fess supports integration with the following LDAP servers:

  • Microsoft Active Directory

  • OpenLDAP

  • 389 Directory Server

  • Apache Directory Server

  • Other LDAP v3 compatible servers

Prerequisites

  • Network access to the LDAP server

  • Service account for LDAP searches (bind DN)

  • Understanding of LDAP structure (base DN, attribute names, etc.)

Basic Configuration

Add the following configuration to app/WEB-INF/conf/system.properties.

LDAP Connection Settings

# Enable LDAP authentication
ldap.admin.enabled=true

# LDAP server URL
ldap.provider.url=ldap://ldap.example.com:389

# For secure connection (LDAPS)
# ldap.provider.url=ldaps://ldap.example.com:636

# Base DN
ldap.base.dn=dc=example,dc=com

# User authentication bind DN template (%s is replaced with username)
ldap.security.principal=uid=%s,ou=People,dc=example,dc=com

# Admin bind DN (service account for LDAP searches)
ldap.admin.security.principal=cn=fess,ou=services,dc=example,dc=com

# Admin bind password
ldap.admin.security.credentials=your_password

Account Filter Settings

# Account filter (search filter for user authentication)
ldap.account.filter=uid=%s

# Admin user search filter for LDAP management console
ldap.admin.user.filter=uid=%s

Note

ldap.account.filter is the search filter for user authentication, while ldap.admin.user.filter is the user search filter for the LDAP management console. Set each appropriately as they serve different purposes.

LDAP Admin Base DN Settings

# User search base DN
ldap.admin.user.base.dn=ou=People,dc=example,dc=com

# Role search base DN
ldap.admin.role.base.dn=ou=Roles,dc=example,dc=com

# Group search base DN
ldap.admin.group.base.dn=ou=Groups,dc=example,dc=com

Group Filter Settings

# Group filter
ldap.group.filter=(member=%s)

# memberOf attribute name
ldap.memberof.attribute=memberOf

Active Directory Configuration

Configuration example for Microsoft Active Directory.

Basic Configuration

ldap.admin.enabled=true
ldap.provider.url=ldap://ad.example.com:389
ldap.base.dn=dc=example,dc=com

# User auth bind DN template (UPN format)
ldap.security.principal=%s@example.com

# Admin bind DN (service account)
ldap.admin.security.principal=cn=fess,cn=Users,dc=example,dc=com
ldap.admin.security.credentials=your_password

# Account filter
ldap.account.filter=sAMAccountName=%s

# Group filter
ldap.group.filter=(member=%s)

Active Directory Specific Settings

# Using memberOf attribute
ldap.memberof.attribute=memberOf

# Nested group resolution (LDAP_MATCHING_RULE_IN_CHAIN)
ldap.group.filter=(member:1.2.840.113556.1.4.1941:=%s)

OpenLDAP Configuration

Configuration example for OpenLDAP.

ldap.admin.enabled=true
ldap.provider.url=ldap://openldap.example.com:389
ldap.base.dn=dc=example,dc=com

# User auth bind DN template
ldap.security.principal=uid=%s,ou=People,dc=example,dc=com

# Admin bind DN (service account)
ldap.admin.security.principal=cn=admin,dc=example,dc=com
ldap.admin.security.credentials=your_password

# Account filter
ldap.account.filter=uid=%s

# Group filter
ldap.group.filter=(memberUid=%s)

Security Settings

LDAPS (SSL/TLS)

Use encrypted connections:

# Use LDAPS
ldap.provider.url=ldaps://ldap.example.com:636

For self-signed certificates, import the certificate into the Java truststore:

keytool -import -alias ldap-server -keystore $JAVA_HOME/lib/security/cacerts \
        -file ldap-server.crt

Password Protection

Set passwords using environment variables:

ldap.admin.security.credentials=${LDAP_PASSWORD}

Failover

Failover to multiple LDAP servers:

# Specify multiple URLs separated by spaces
ldap.provider.url=ldap://ldap1.example.com:389 ldap://ldap2.example.com:389

Troubleshooting

Connection Error

Symptom: LDAP connection fails

Check:

  1. Is the LDAP server running?

  2. Is the port open in the firewall (389 or 636)?

  3. Is the URL correct (ldap:// or ldaps://)?

  4. Are the bind DN and password correct?

Authentication Error

Symptom: User authentication fails

Check:

  1. Is the user search filter correct?

  2. Does the user exist within the search base DN?

  3. Is the username attribute correct?

Cannot Retrieve Groups

Symptom: Cannot retrieve user groups

Check:

  1. Is the group search filter correct?

  2. Is the group membership attribute correct?

  3. Do the groups exist within the search base DN?

Debug Settings

Output detailed logs:

app/WEB-INF/classes/log4j2.xml:

<Logger name="org.codelibs.fess.ldap" level="DEBUG"/>

Reference Information