LDAP & Active Directory Integration Guide

FirmFlow natively supports authenticating users against existing LDAP directories and Microsoft Active Directory (AD) instances. This allows firm staff to use their existing Windows credentials for Single Sign-On (SSO) into the application.

1. Environment Configuration

To enable LDAP Auth, the following environment variables must be injected into the FirmFlow container runtime (.env file or orchestrator config):

# Enable the module by providing the connection URL and Base DN
LDAP_URL="ldap://your-dc.internal.firm.local:389" 
LDAP_BASE_DN="DC=internal,DC=firm,DC=local"

# (Optional) Service Account to bind for searching
LDAP_BIND_DN="CN=FirmFlow Reader,OU=ServiceAccounts,DC=internal,DC=firm,DC=local"
LDAP_BIND_PASSWORD="SecretPassword123!"

# (Optional) Override Search Filter. Default handles mail or userPrincipalName.
LDAP_SEARCH_FILTER="sAMAccountName={{email}}"

2. Authentication Flow

When a user attempts to log in via /login: 1. FirmFlow checks if LDAP_URL is set. 2. If set, FirmFlow attempts an LDAP bind using the configured credentials. 3. If successful, FirmFlow creates or merges the session with the Local Database account. 4. Fallback: If the LDAP server is unreachable OR the user is an external client (not in AD), FirmFlow transparently falls back to checking the password hash in the local database.

3. Microsoft Active Directory Specifics

When connecting to AD, it is common to map usernames differently than standard OpenLDAP: * Set LDAP_SEARCH_FILTER="(sAMAccountName={{email}})" if users will log in using their short username (e.g., jsmith). * Ensure that SSL (ldaps://) is used if you are transmitting credentials over untrusted segments of your network.

4. Troubleshooting

Check the container logs during a failed login attempt. You will see prefix markers: * [LDAP] Attempting authentication for... * [Auth] LDAP Auth Handshake failed...

If you receive InvalidBindCredentials, double check that your LDAP_BIND_DN is a fully qualified Distinguished Name, not just a username.