Skip to main content

​
Overview

Faction supports LDAP (Lightweight Directory Access Protocol) authentication, allowing you to integrate with Active Directory, OpenLDAP, or other LDAP-compliant directory services. This enables centralized user management and single sign-on capabilities.

​
Configuration

​
Basic LDAP Settings

Configure LDAP authentication in Faction’s system settings: 
ldapURL: ldap://your-ldap-server:389
ldapBaseDN: dc=example,dc=com
ldapBindDN: cn=admin,dc=example,dc=com
ldapBindPassword: your-bind-password
ldapSecurity: ssl  # or 'tls' or 'none'
ldapObjectClass: user  # or leave empty for auto-detection
ldapInsecureSSL: false  # only set to true for testing

​
Parameter Descriptions

ParameterDescriptionExample
ldapURLLDAP server URL and portldap://ldap.example.com:389 or ldaps://ldap.example.com:636
ldapBaseDNBase Distinguished Name for searchesdc=company,dc=com
ldapBindDNDN for binding to LDAPcn=faction,ou=services,dc=company,dc=com
ldapBindPasswordPassword for bind DN
ldapSecuritySecurity protocolssl, tls, or none
ldapObjectClassLDAP object class filteruser, inetOrgPerson, or empty
ldapInsecureSSLSkip SSL certificate validationtrue or false (default)

​
Active Directory Configuration

For Microsoft Active Directory: 
ldapURL: ldap://ad.company.com:389
ldapBaseDN: dc=company,dc=com
ldapBindDN: cn=faction-service,ou=Service Accounts,dc=company,dc=com
ldapSecurity: tls
ldapObjectClass: user

​
OpenLDAP Configuration

For OpenLDAP servers: 
ldapURL: ldap://openldap.company.com:389
ldapBaseDN: dc=company,dc=com
ldapBindDN: cn=admin,dc=company,dc=com
ldapSecurity: ssl
ldapObjectClass: inetOrgPerson

​
User Provisioning

​
Automatic User Creation

When a user successfully authenticates via LDAP, Faction automatically provisions their account using the following attributes:
LDAP AttributeFaction FieldFallback
mailEmailRequired
givenNameFirst Name
snLast Name
sAMAccountNameUsernameuid
uidUsernamesAMAccountName

​
Search Filters

Faction uses the following search filters to locate users: With ObjectClass specified: 
(&(ObjectClass=user)(uid=username))
Without ObjectClass (auto-detection): 
(|(uid=username)(sAMAccountName=username))
For user search functionality, Faction queries multiple attributes: 
(|(uid=search*)(sAMAccountName=search*)(mail=search*)(givenName=search*)(sn=search*))

​
Testing LDAP Connection

​
Connection Validation

  1. Navigate to Settings > Authentication > LDAP
  2. Enter your LDAP configuration parameters
  3. Click Test Connection to validate:
    • Server connectivity
    • Bind credentials
    • Base DN accessibility
  4. If successful, you’ll see a confirmation message

​
Test User Authentication

To verify user authentication:
  1. In LDAP settings, use the Test User section
  2. Enter a username from your directory
  3. Click Search User to verify Faction can locate and retrieve user attributes
  4. Review the retrieved attributes (email, first name, last name)

​
Security Configuration

​
SSL/TLS Options

Use LDAPS on port 636 for encrypted connections:
ldapURL: ldaps://ldap.example.com:636
ldapSecurity: ssl
Use TLS upgrade on standard LDAP port 389:
ldapURL: ldap://ldap.example.com:389
ldapSecurity: tls
For testing with self-signed certificates:
ldapSecurity: ssl
ldapInsecureSSL: true
Never use ldapInsecureSSL: true in production environments.

​
Implementation Details

Faction’s LDAP implementation uses the following Java JNDI context properties: 
Context.INITIAL_CONTEXT_FACTORY: com.sun.jndi.ldap.LdapCtxFactory
Context.PROVIDER_URL: <ldapURL>
Context.SECURITY_AUTHENTICATION: simple
Context.SECURITY_PRINCIPAL: <ldapBindDN>
Context.SECURITY_CREDENTIALS: <ldapBindPassword>
Context.SECURITY_PROTOCOL: <ldapSecurity>
Relevant source code: src/com/fuse/authentication/LDAPValidator.java

​
Troubleshooting

  • Verify the LDAP server URL and port are correct
  • Ensure firewall rules allow outbound LDAP/LDAPS traffic
  • Check if the LDAP server is running and accessible
  • Test connectivity using telnet ldap.example.com 389
  • Verify bind DN and password are correct
  • Ensure the bind DN has search permissions on the base DN
  • Check LDAP server logs for authentication errors
  • Verify the user exists in the directory with correct attributes
  • Import the LDAP server’s SSL certificate into Faction’s trust store
  • Verify the certificate is valid and not expired
  • Check that the certificate CN matches the LDAP server hostname
  • For testing only, enable ldapInsecureSSL
  • Verify the base DN is correct
  • Check that the user exists under the base DN
  • Ensure the objectClass filter matches your directory schema
  • Test with an empty objectClass to use auto-detection
  • Verify your LDAP schema includes the required attributes
  • Check LDAP attribute mappings (mail, givenName, sn, uid/sAMAccountName)
  • Ensure the bind account has read permissions for user attributes

​
Best Practices

Use Service Accounts

Create a dedicated service account for Faction’s LDAP binding with minimal required permissions.

Enable SSL/TLS

Always use encrypted LDAP connections (LDAPS or StartTLS) in production environments.

Restrict Base DN

Use the most specific base DN possible to limit search scope and improve performance.

Monitor Authentication

Review LDAP authentication logs regularly to detect suspicious activity.

Build docs developers (and LLMs) love

Get started for freeTalk to us