LDAP Authentication

LDAP Authentication Configuration 🔐

LDAP Banner

Calibre-Web Automated supports LDAP (Lightweight Directory Access Protocol) authentication, enabling seamless integration with enterprise directories like Active Directory, OpenLDAP, and other LDAP-compliant systems. This guide covers everything you need to know about configuring and using LDAP authentication in CWA.

🌟 Features Overview

CWA's LDAP implementation provides enterprise-grade authentication with the following features:

✅ Auto-User Creation: Automatically creates user accounts on first LDAP login (default: enabled)
✅ Default Permissions: New LDAP users inherit all default configuration settings
✅ Seamless Integration: Works with Active Directory, OpenLDAP, and LDAP-compliant systems
✅ API/OPDS Support: LDAP authentication works for API and OPDS access
✅ Enterprise Ready: Designed for corporate environments with centralized authentication
✅ Fallback Support: Can be combined with standard username/password authentication
✅ Comprehensive Logging: Detailed authentication logs for troubleshooting and auditing

🚀 Quick Setup Guide

Step 1: Access LDAP Settings

Log in as an Admin user
Navigate to Admin Panel → Basic Configuration
Scroll down to the LDAP Settings section

Step 2: Basic LDAP Configuration

Configure your LDAP server connection:

LDAP Server: ldap://your-ldap-server.com:389
LDAP Encryption: None (or SSL/TLS as required)
LDAP Base DN: dc=company,dc=com
LDAP User Object Filter: (&(objectClass=user)(sAMAccountName=%s))
LDAP Authentication: Simple Bind

Step 3: Enable Auto-Creation (Recommended)

✅ Enable "Auto-create users from LDAP" (enabled by default)

This allows LDAP users to automatically get accounts created on their first successful login, providing a seamless user experience.

Step 4: Test and Save

Test Configuration: Use a test LDAP user to verify connectivity
Save Configuration: Click Submit to apply settings
Restart CWA: Some LDAP changes may require a restart

🎯 LDAP User Auto-Creation

How Auto-Creation Works

When Auto-create users from LDAP is enabled (default):

First Login: User authenticates successfully against LDAP server
User Lookup: CWA checks if user account already exists
Auto-Creation: If not found, creates new user with default settings
Immediate Access: User is logged in automatically without manual account creation

Default Settings Applied to New LDAP Users

New LDAP users automatically inherit all default configuration settings:

📊 Default Role: Configured role permissions
📋 Sidebar View: Default sidebar visibility settings
🌍 Locale: Default interface language
📚 Default Language: Default book language filter
🏷️ Tag Restrictions: Default allowed/denied tags
📖 Content Restrictions: Default column restrictions
🎨 Theme: Default CWA theme setting
📱 Kobo Sync: Default Kobo integration settings

This ensures LDAP users get the same permissions and interface settings as manually created users.

⚙️ Detailed Configuration

LDAP Server Connection

Setting	Description	Example
LDAP Server	LDAP server hostname/IP and port	`ldap://dc.company.com:389`
LDAP Encryption	Security level (None/SSL/TLS)	`None` (internal network) or `SSL/TLS` (external)
LDAP Base DN	Base Distinguished Name for searches	`dc=company,dc=com`

Authentication Configuration

Setting	Description	Example
LDAP User Object Filter	LDAP query to find user objects	`(&(objectClass=user)(sAMAccountName=%s))`
LDAP Authentication	Authentication method	`Simple Bind` (most common)
LDAP Admin Username	Admin DN for LDAP binding (if required)	`cn=admin,dc=company,dc=com`
LDAP Admin Password	Password for admin binding	`[admin-password]`

Auto-Creation Settings

Setting	Description	Default
Auto-create users from LDAP	Enable automatic user creation	✅ Enabled

🏢 Provider-Specific Examples

Microsoft Active Directory

LDAP Server: ldap://dc.company.com:389
LDAP Encryption: None (or SSL for external access)
LDAP Base DN: dc=company,dc=com
LDAP User Object Filter: (&(objectClass=user)(sAMAccountName=%s))
LDAP Authentication: Simple Bind
Auto-create users from LDAP: ✅ Enabled

Login Format: Users log in with their Active Directory username (e.g., john.doe)

OpenLDAP

LDAP Server: ldap://openldap.company.com:389
LDAP Encryption: None (or TLS for security)
LDAP Base DN: ou=people,dc=company,dc=org
LDAP User Object Filter: (&(objectClass=inetOrgPerson)(uid=%s))
LDAP Authentication: Simple Bind
Auto-create users from LDAP: ✅ Enabled

Login Format: Users log in with their UID (e.g., jdoe)

FreeIPA

LDAP Server: ldap://ipa.company.com:389
LDAP Encryption: TLS (recommended)
LDAP Base DN: cn=users,cn=accounts,dc=company,dc=com
LDAP User Object Filter: (&(objectClass=person)(uid=%s))
LDAP Authentication: Simple Bind
Auto-create users from LDAP: ✅ Enabled

🧪 Testing & Troubleshooting

Testing LDAP Connection

Configure LDAP settings in the admin panel
Test with known user: Try logging in with an existing LDAP user
Check logs: Review CWA logs for authentication details
Verify auto-creation: Confirm new user appears in user management

Common Issues & Solutions

❌ "LDAP authentication failed"

Cause: Incorrect server configuration or user credentials Solution:

Verify LDAP server is accessible from CWA
Check LDAP Base DN and User Object Filter
Test with LDAP admin tools (ldapsearch, etc.)
Verify user exists in LDAP directory

❌ "User not found after LDAP authentication"

Cause: Auto-creation is disabled or failed Solution:

Enable Auto-create users from LDAP in admin settings
Check CWA logs for user creation errors
Verify default user settings are configured
Ensure database is writable

❌ LDAP users can't access books/features

Cause: Default permissions not properly configured Solution:

Configure default role and permissions in Admin → Basic Configuration → Feature Configuration
Auto-created LDAP users inherit these default settings
Manually adjust individual user permissions as needed

❌ "LDAP server connection timeout"

Cause: Network connectivity or firewall issues Solution:

Verify LDAP server is reachable from CWA container
Check firewall rules for LDAP ports (389/636)
Test connectivity with tools like telnet or nc

Debug Logging

Enable debug logging to troubleshoot LDAP issues:

Set log level to Debug in admin panel
Check container logs for detailed LDAP authentication flow
Look for LDAP binding and search operations
Review user creation process details

🔒 Security Best Practices

Network Security

Use TLS/SSL for LDAP connections when possible
Restrict network access to LDAP servers using firewall rules
Use dedicated service accounts for LDAP binding when required
Monitor authentication logs for suspicious activity

Account Security

Review default permissions to ensure appropriate access levels
Regularly audit auto-created accounts
Implement account cleanup for terminated employees
Use least-privilege principles for default role configuration

LDAP Server Security

Keep LDAP servers updated with security patches
Use strong authentication methods when available
Monitor LDAP server logs for authentication attempts
Implement account lockout policies on LDAP server

🔄 Authentication Mode Integration

Combining LDAP with Other Authentication Methods

LDAP authentication can be used alongside other authentication methods:

Standard Authentication: Users can still log in with CWA passwords
OAuth Integration: Combine LDAP with OAuth providers
Reverse Proxy: Use LDAP with reverse proxy authentication

Migration Scenarios

From Standard to LDAP Authentication

Configure LDAP settings with auto-creation enabled
Test with pilot users to verify configuration
Communicate changes to all users
Gradually migrate users to LDAP authentication
Maintain standard auth as fallback during transition

User Account Linking

When switching to LDAP:

Existing users keep passwords: They can still use standard login
LDAP users auto-created: New accounts created for LDAP users
Manual linking: Admin can manually link LDAP users to existing accounts if needed

📊 API and OPDS Integration