LDAP Integration

LDAP Integration in rConfig V8

LDAP integration in rConfig V8 addresses the challenge of managing user authentication across enterprise environments by leveraging existing directory services for centralized identity management. Organizations can integrate rConfig with Active Directory or FreeIPA to enable single sign-on capabilities, eliminate duplicate credential management, and maintain consistent access control aligned with enterprise identity governance.

This integration provides automatic user provisioning, password synchronization, group-based authorization, and fallback authentication mechanisms ensuring continuous access even during directory service outages. Organizations benefit from reduced administrative overhead, improved security posture through centralized credential management, and seamless user experience across enterprise applications.

Understanding LDAP Authentication

How LDAP Integration Works

When LDAP authentication is enabled, rConfig modifies the login flow to authenticate users against the configured directory service:

Standard login process:

1. User enters credentials on rConfig login page
2. rConfig queries LDAP server using configured bind credentials
3. LDAP server validates user credentials and group membership
4. If authentication succeeds and user belongs to authorized group, rConfig creates or updates local user account
5. User credentials are optionally synchronized to rConfig database (encrypted) for fallback authentication
6. User session is established with permissions based on assigned role

Fallback authentication: If LDAP servers are unreachable or authentication fails, rConfig automatically attempts authentication against locally stored credentials. This ensures continuous access during directory service maintenance or network issues.

Key Features and Capabilities

Automatic user provisioning: Users authenticating via LDAP are automatically created in rConfig with profile information populated from directory attributes. No manual user account creation required for LDAP-authenticated users.

Password synchronization: LDAP passwords can be synchronized to rConfig database (encrypted using application encryption key) enabling local authentication fallback when directory services are unavailable.

Group-based authorization: Access control is enforced by requiring users to belong to a specific LDAP group. Only members of the authorized group can authenticate to rConfig.

Multi-server support: Configure multiple LDAP servers for high availability. rConfig attempts authentication against servers in configured order, providing resilience against individual server failures.

Secure communication: Support for SSL/TLS encrypted connections protects credentials during transmission between rConfig and directory servers.

Flexible attribute mapping: Map LDAP attributes to rConfig user properties (username, email, first name, last name) accommodating different directory schemas.

Authentication Flow Diagram

User Login Attempt
       ↓
[LDAP Enabled?] → No → Local Authentication
       ↓ Yes
[Query LDAP Server]
       ↓
[LDAP Available?] → No → Fallback to Local Auth
       ↓ Yes
[Validate Credentials]
       ↓
[Valid?] → No → Authentication Failed
       ↓ Yes
[Check Group Membership]
       ↓
[Authorized Group?] → No → Access Denied
       ↓ Yes
[Create/Update Local User]
       ↓
[Sync Password (if enabled)]
       ↓
[Grant Access with Role Permissions]

Supported Directory Services

Active Directory

Microsoft Active Directory is fully supported for LDAP authentication in rConfig V8.

Configuration requirements:

• Active Directory domain with accessible domain controllers
• Service account with read access to directory
• LDAP or LDAPS protocol enabled on domain controllers
• Security group containing authorized rConfig users

Typical schema attributes:

• Username field: userPrincipalName (e.g., [email protected])
• Email field: mail
• First name field: givenName
• Last name field: sn (surname)

Base DN examples:

• DC=company,DC=com
• OU=Users,DC=company,DC=local
• OU=IT,OU=Departments,DC=company,DC=com

Group authorization format: Specify only the Common Name (CN) of the security group, not the full Distinguished Name (DN). For example, use rConfig Users rather than CN=rConfig Users,OU=Groups,DC=company,DC=com.

FreeIPA

FreeIPA (Identity, Policy, Audit) is supported for LDAP authentication in rConfig V8.

Configuration requirements:

• FreeIPA server with accessible replicas
• Service account with read access to users and groups
• LDAP or LDAPS protocol configured
• Group containing authorized rConfig users

FreeIPA-specific configuration: Enable FreeIPA schema by adding to .env file:

LDAP_SCHEMA=freeipa

This configures rConfig to use FreeIPA-specific attribute mappings and authentication logic.

Typical schema attributes:

• Username field: uid
• Email field: mail
• First name field: givenName
• Last name field: sn

Base DN examples:

• cn=users,cn=accounts,dc=example,dc=com
• cn=users,cn=accounts,dc=ipa,dc=company,dc=local

Unsupported Directory Services

Note

OpenLDAP support is planned for future rConfig releases but is not currently supported. Organizations using OpenLDAP should consider migrating to Active Directory or FreeIPA, or contact rConfig support to discuss custom integration requirements.

Configuration Prerequisites

Directory Service Requirements

Before configuring LDAP integration, ensure the following prerequisites are met:

Service account credentials: Create a dedicated service account in your directory with read-only access to user and group information. This account is used for LDAP bind operations and user lookups. Avoid using personal accounts or accounts with administrative privileges.

Security group: Create or identify an existing security group containing users authorized to access rConfig. All rConfig users must be members of this group for authentication to succeed.

Network connectivity: Verify network connectivity from rConfig server to directory service servers on appropriate ports (389 for LDAP, 636 for LDAPS, or custom ports). Firewall rules must permit bidirectional communication.

SSL/TLS certificates (if using secure connections): If using LDAPS or StartTLS, ensure the directory service presents a valid SSL certificate trusted by the rConfig server. Self-signed certificates require importing into the system trust store.

Directory schema knowledge: Understand your directory’s attribute naming conventions (userPrincipalName vs uid, givenName vs firstName, etc.) to configure correct attribute mappings.

rConfig Prerequisites

Admin access: You must have the Admin role to configure LDAP settings. Standard users cannot access LDAP configuration.

System backup: Create a complete system backup before enabling LDAP authentication. If LDAP misconfiguration locks out all users, you may need to restore from backup or manually disable LDAP via command line.

Test user credentials: Have credentials for at least one test user who is a member of the authorized group to validate configuration before enabling for all users.

Fallback admin account: Ensure at least one local administrator account with strong password exists before enabling LDAP. This provides emergency access if LDAP authentication fails.

LDAP Configuration Procedure

Accessing LDAP Settings

To configure LDAP authentication:

1. Log in to rConfig as an administrator
2. Navigate to Settings → System Settings
3. Scroll to the LDAP Authentication section
4. Configure LDAP parameters as described below

Configuration Parameters

Tip

Consult your Active Directory or FreeIPA administrator for assistance determining correct values for Base DN, authorized group names, and attribute mappings. Incorrect values will prevent authentication.

Enable LDAP

Description: Master switch enabling or disabling LDAP authentication system-wide.

Default: Disabled

Recommendation: Leave disabled until all configuration parameters are correctly set and tested. Enabling LDAP with incorrect configuration can lock out all users.

LDAP Server

Description: Hostname or IP address of LDAP/directory server.

Format: Single hostname/IP or comma-separated list for high availability.

Examples:

• ldap.company.com
• dc01.company.local
• 192.168.1.10
• dc01.company.local,dc02.company.local,dc03.company.local (multiple servers)

Behavior: When multiple servers are specified, rConfig attempts authentication against servers in the order listed. If the first server is unreachable, subsequent servers are tried automatically.

Best practice: Configure at least two directory servers for high availability. List servers in order of preference (primary, secondary, tertiary).

LDAP Port

Description: TCP port for LDAP communication.

Default: 389 (LDAP), 636 (LDAPS)

Standard ports:

• 389: Unencrypted LDAP or StartTLS
• 636: LDAPS (LDAP over SSL)
• Custom: Some organizations use non-standard ports for security

Recommendation: Use 636 with SSL enabled for encrypted communication. Port 389 with StartTLS (TLS enabled) is acceptable alternative. Avoid unencrypted LDAP in production environments.

Use SSL

Description: Enable LDAPS (LDAP over SSL) for encrypted communication.

Default: Disabled

Behavior: When enabled, port automatically changes to 636 (can be manually adjusted). All communication between rConfig and directory server is encrypted using SSL.

Requirements: Directory server must have valid SSL certificate. Self-signed certificates require importing into rConfig server trust store.

Recommendation: Enable SSL for production environments to protect credentials during transmission.

Caution

SSL and TLS options are mutually exclusive. Enabling SSL disables TLS. Enable one or the other, not both. Most environments should use SSL (LDAPS) on port 636 for maximum compatibility.

Use TLS

Description: Enable StartTLS for encrypted communication over standard LDAP port.

Default: Disabled

Behavior: When enabled, connection starts on port 389 (standard LDAP) and upgrades to TLS encryption via StartTLS command. SSL option is automatically disabled.

Requirements: Directory server must support StartTLS extension.

Recommendation: Use SSL (LDAPS) instead of TLS (StartTLS) unless organizational policy requires StartTLS. LDAPS provides simpler configuration and broader compatibility.

Sync Password

Description: Synchronize LDAP user passwords to rConfig database (encrypted) for fallback authentication.

Default: Disabled

Behavior: When enabled, user passwords are stored in rConfig database encrypted using the application encryption key. During LDAP outages, users can authenticate using synchronized passwords stored locally.

Security consideration: While passwords are encrypted, synchronization creates additional credential storage requiring protection. Disable if organizational policy prohibits password synchronization.

Recommendation: Enable password sync for environments requiring high availability where LDAP outages would otherwise prevent access to critical network configuration management.

Note

Password synchronization creates a brief window during password changes where both old and new passwords work. After changing LDAP password, the first successful login to rConfig updates the synchronized password to the new value.

LDAP Bind Username

Description: Service account username for authenticating to directory service.

Format: Distinguished Name (DN) or userPrincipalName depending on directory type.

Active Directory examples:

• CN=rConfigService,OU=Service Accounts,DC=company,DC=com (Distinguished Name)
• [email protected] (userPrincipalName)

FreeIPA examples:

• uid=rconfig-svc,cn=users,cn=accounts,dc=company,dc=com (Distinguished Name)

Recommendation: Use a dedicated service account with read-only permissions. Avoid personal accounts or accounts with administrative privileges. Document service account purpose and ownership for audit purposes.

LDAP Bind Password

Description: Password for the bind username service account.

Security: Password is encrypted in database using application encryption key.

Best practice: Use strong, complex password for service account. Rotate password periodically according to organizational security policy. Update rConfig configuration immediately after password changes.

LDAP Authorized Group

Description: Security group whose members are authorized to access rConfig.

Format: Common Name (CN) only, not full Distinguished Name.

Examples:

• rConfig Users
• Network Engineers
• IT Operations

Behavior: Users must be members of this group to successfully authenticate. Empty value allows any directory user to authenticate (not recommended for production).

Recommendation: Create a dedicated security group specifically for rConfig access control. This simplifies audit trails and enables rapid access provisioning/deprovisioning by group membership changes.

Caution

Specify only the group Common Name (CN), not the full Distinguished Name (DN). For example, use rConfig Users not CN=rConfig Users,OU=Groups,DC=company,DC=com. rConfig constructs the full DN automatically using the Base DN.

Base DN

Description: Base Distinguished Name defining the directory search starting point.

Format: Distinguished Name components separated by commas.

Active Directory examples:

• DC=company,DC=com (search entire domain)
• OU=Users,DC=company,DC=local (search within Users OU only)
• OU=IT,OU=Departments,DC=company,DC=com (search within IT department)

FreeIPA examples:

• cn=accounts,dc=company,dc=com
• cn=users,cn=accounts,dc=ipa,dc=company,dc=local

Recommendation: Set Base DN to the narrowest scope containing all rConfig users. Broader scope (e.g., entire domain) increases query time. Narrower scope (e.g., specific OU) improves performance but may exclude users if organizational structure changes.

User Attribute Mapping

Map directory attributes to rConfig user properties. Correct mappings ensure user profiles populate with accurate information.

LDAP Username Field:

Description: Directory attribute used as rConfig username.

Active Directory default: userPrincipalName (e.g., [email protected])

FreeIPA default: uid

Requirement: This attribute must be unique across all users and match the format users will enter at login.

Note

Active Directory sAMAccountName is not supported for the LDAP Username Field. Use userPrincipalName instead to ensure compatibility and uniqueness across domains.

LDAP Email Field:

Description: Directory attribute containing user email address.

Standard attribute: mail

Usage: Email address is used for notification delivery and user identification.

LDAP First Name Field:

Description: Directory attribute containing user first name.

Active Directory default: givenName

Usage: Displayed in user interface and user management screens.

LDAP Last Name Field:

Description: Directory attribute containing user last name or surname.

Standard attribute: sn (Active Directory and FreeIPA)

Usage: Displayed in user interface and user management screens.

Configuration Steps

Active Directory

Step 1: Gather configuration information

Collect the following from Active Directory administrator:

• Domain controller hostname(s)
• Service account credentials (userPrincipalName and password)
• Base DN for user search scope
• Security group name for authorized users
• LDAPS port if non-standard

Step 2: Configure basic settings

1. Set LDAP Server: dc01.company.local,dc02.company.local
2. Set LDAP Port: 636
3. Enable Use SSL: On
4. Set Sync Password: On (for fallback authentication)

Step 3: Configure authentication credentials

1. Set LDAP Bind Username: [email protected]
2. Set LDAP Bind Password: Service account password
3. Set Base DN: DC=company,DC=com
4. Set LDAP Authorized Group: rConfig Users

Step 4: Configure attribute mappings

1. Set LDAP Username Field: userPrincipalName
2. Set LDAP Email Field: mail
3. Set LDAP First Name Field: givenName
4. Set LDAP Last Name Field: sn

Step 5: Test configuration

1. Click Test Connection button
2. Enter test user credentials when prompted
3. Verify successful authentication message
4. Review any error messages and adjust configuration

Step 6: Enable LDAP authentication

1. After successful test, enable Enable LDAP: On
2. Click Save to apply configuration
3. Test login with LDAP credentials in separate browser session
4. Verify local admin account still works (fallback)

FreeIPA

Step 1: Enable FreeIPA schema

Edit .env file to enable FreeIPA-specific configuration:

sudo nano /var/www/html/rconfig8/current/.env

Add or modify:

LDAP_SCHEMA=freeipa

Save and exit. Restart web server:

sudo systemctl restart apache2  # or nginx

Step 2: Gather configuration information

Collect the following from FreeIPA administrator:

• FreeIPA server hostname(s)
• Service account credentials (uid and password)
• Base DN for user search scope
• Group name for authorized users
• LDAPS port if non-standard

Step 3: Configure basic settings

1. Set LDAP Server: ipa01.company.local,ipa02.company.local
2. Set LDAP Port: 636
3. Enable Use SSL: On
4. Set Sync Password: On (for fallback authentication)

Step 4: Configure authentication credentials

1. Set LDAP Bind Username: uid=rconfig-svc,cn=users,cn=accounts,dc=company,dc=local
2. Set LDAP Bind Password: Service account password
3. Set Base DN: cn=users,cn=accounts,dc=company,dc=local
4. Set LDAP Authorized Group: rconfig-users

Step 5: Configure attribute mappings

1. Set LDAP Username Field: uid
2. Set LDAP Email Field: mail
3. Set LDAP First Name Field: givenName
4. Set LDAP Last Name Field: sn

Step 6: Test configuration

1. Click Test Connection button
2. Enter test user credentials when prompted
3. Verify successful authentication message
4. Review any error messages and adjust configuration

Step 7: Enable LDAP authentication

1. After successful test, enable Enable LDAP: On
2. Click Save to apply configuration
3. Test login with LDAP credentials in separate browser session
4. Verify local admin account still works (fallback)

Testing LDAP Configuration

The Test Connection button validates LDAP configuration without enabling authentication system-wide:

Test procedure:

1. Configure all LDAP parameters
2. Click Save to persist settings (required before testing)
3. Click Test Connection button
4. Enter test user username and password in the prompt
5. Review test results

Successful test output:

• “Connection successful”
• “User found in directory”
• “User is member of authorized group”
• User profile information retrieved (name, email)

Common test failures:

“Cannot connect to LDAP server”: Verify server hostname, port, and network connectivity. Check firewall rules.

“Invalid bind credentials”: Verify bind username and password are correct. Ensure service account has read access to directory.

“User not found”: Verify Base DN is correct and includes the organizational unit containing the test user.

“User not in authorized group”: Add test user to the specified security group in directory service.

“SSL certificate error”: Import directory server SSL certificate into rConfig server trust store.

Caution

Always test LDAP configuration thoroughly with multiple test users before enabling authentication system-wide. Failed LDAP authentication can lock out all users if fallback accounts are not properly configured.

User Management with LDAP

Automatic User Provisioning

When users authenticate via LDAP for the first time, rConfig automatically creates local user accounts:

User creation process:

1. User enters LDAP credentials at login
2. rConfig authenticates against directory service
3. If successful, rConfig queries directory for user attributes
4. New user account is created in rConfig database
5. User profile populated with directory information (name, email)
6. Password optionally synchronized to database (encrypted)
7. User granted access with default role assignment

Default role: LDAP-authenticated users are assigned the default role configured in system settings. Administrators can change user roles after account creation via the Users management interface.

User Approval Workflow

Note

LDAP users require explicit approval before accessing rConfig. This prevents automatic provisioning from granting access to users who successfully authenticate via directory services but should not access rConfig. See User Management for approval procedures.

After first LDAP authentication, users appear in the Users list with “Pending Approval” status. Administrators must:

1. Navigate to Users management interface
2. Locate pending LDAP user
3. Click approve icon
4. Assign appropriate role (Admin, User, or custom role)
5. Save approval

Once approved, users can access rConfig according to their assigned role permissions.

Password Synchronization Behavior

When password synchronization is enabled:

Initial login: User’s LDAP password is captured during authentication and stored encrypted in rConfig database.

Subsequent logins: User authenticates against LDAP. If LDAP is available, authentication uses directory service. If LDAP is unavailable, authentication falls back to synchronized password.

Password changes: After changing LDAP password, the first successful login to rConfig updates synchronized password. During this transition, both old and new passwords work:

• Old password: Fails LDAP authentication, succeeds local authentication (synchronized password not yet updated)
• New password: Succeeds LDAP authentication, updates synchronized password

Password sync lifecycle: Synchronized passwords remain valid until:

• User changes LDAP password and logs in to rConfig with new password
• Administrator disables password synchronization (existing synced passwords retained)
• User account is deleted

Managing LDAP User Roles

LDAP users are assigned roles determining their permissions within rConfig:

Assigning roles:

1. Navigate to Users management interface
2. Locate LDAP-authenticated user
3. Click three-dot menu → Change Role
4. Select appropriate role (Admin, User, Read-only, or custom)
5. Save role assignment

Role changes take effect immediately for new sessions. Users currently logged in should log out and back in to activate new permissions.

Role assignment strategies:

Group-based role mapping (manual): Maintain documentation mapping directory security groups to rConfig roles. When approving LDAP users, check their directory group memberships and assign corresponding roles.

Default role for most users: Assign the “User” role to most LDAP-authenticated users, reserving “Admin” for designated system administrators.

Least privilege: Default to Read-only role for new LDAP users, promoting to User or Admin roles only when operational needs require elevated permissions.

For comprehensive role management documentation, see Roles and Permissions.

High Availability and Failover

Multiple LDAP Servers

Configure multiple directory servers for resilience against individual server failures:

Configuration: Specify comma-separated list of servers in LDAP Server field:

dc01.company.local,dc02.company.local,dc03.company.local

Failover behavior:

1. rConfig attempts authentication against first server in list
2. If first server is unreachable (timeout, connection refused), second server is tried
3. Process continues through all configured servers until successful authentication or all servers exhausted
4. Failover occurs automatically without user intervention

Best practices:

• List servers in order of preference (primary, secondary, tertiary)
• Use geographically distributed servers if available for site-level resilience
• Monitor all configured LDAP servers for availability
• Test failover periodically by temporarily disabling primary server

Local Authentication Fallback

Local authentication fallback ensures continuous access during directory service outages:

Fallback scenarios:

• All configured LDAP servers are unreachable
• LDAP authentication times out
• Network connectivity to directory services is lost
• Directory service experiences service degradation

Fallback behavior:

1. rConfig attempts LDAP authentication first
2. If LDAP authentication fails due to connectivity issues, local authentication is attempted
3. User credentials are compared against synchronized passwords (if password sync enabled)
4. If match found, user granted access with existing role permissions
5. User is notified that LDAP authentication failed and fallback authentication was used

Requirements for effective fallback:

• Password synchronization must be enabled
• Users must have logged in at least once before LDAP outage (to synchronize password)
• Local admin accounts must exist for administrators requiring access during outages

Limitations: Password synchronization only captures passwords during successful LDAP logins. Users who never logged in successfully before LDAP outage cannot authenticate via fallback.

Caution

Local authentication fallback requires password synchronization to be enabled. Without synchronized passwords, users cannot authenticate when LDAP services are unavailable. Organizations disabling password sync for security reasons must accept that LDAP outages will prevent user access.

Security Considerations

Protecting LDAP Credentials

Encrypt communications: Always use SSL (LDAPS on port 636) or TLS (StartTLS on port 389) for production environments. Unencrypted LDAP transmits credentials in plaintext over the network.

Secure service account: Use dedicated service account with read-only permissions. Avoid using administrative accounts or accounts with write access to directory. Rotate service account password regularly according to security policy.

Protect .env file: Service account password is stored in .env file encrypted with application encryption key. Ensure .env file has restrictive permissions (600) and is excluded from backups transmitted insecurely.

Monitor service account usage: Configure directory service auditing to log service account authentication attempts. Unusual patterns may indicate credential compromise.

Managing Synchronized Passwords

Understand encryption: Synchronized passwords are encrypted using rConfig’s application encryption key (APP_KEY in .env file). Security of synchronized passwords depends entirely on protecting this encryption key.

Key rotation impact: Rotating the application encryption key requires re-encrypting all synchronized passwords. See System Encryption Key for key rotation procedures. Contact rConfig support before rotating encryption keys in LDAP-enabled environments.

Compliance considerations: Some regulatory frameworks or organizational policies prohibit password synchronization even when encrypted. Evaluate compliance requirements before enabling password sync.

Data residency: Synchronized passwords reside in rConfig database. Ensure database backup and storage locations comply with data residency requirements.

Access Control Best Practices

Use security groups: Leverage LDAP authorized groups to centrally manage rConfig access. Adding users to or removing users from the security group automatically grants or revokes rConfig access.

Implement least privilege: Assign LDAP-authenticated users the minimum role necessary for their job functions. Default to User or Read-only roles unless administrative access is required.

Audit user access: Regularly review LDAP-authenticated user accounts in rConfig. Remove or disable accounts for users who no longer require access. Monitor user activity logs for suspicious patterns.

Maintain local admin accounts: Preserve at least one local administrator account with strong password as emergency access method if LDAP integration fails. Store local admin credentials securely (password manager, secure documentation).

Certificate Management

When using SSL/TLS for LDAP connections:

Certificate trust: rConfig server must trust the certificate presented by directory service. Self-signed certificates require importing into system trust store.

Certificate expiration: Monitor directory service certificate expiration dates. Expired certificates cause LDAP authentication failures. Implement alerting for certificates expiring within 30 days.

Certificate renewal: After renewing directory service certificates, verify rConfig LDAP authentication continues functioning. New certificates from different CAs may require trust store updates.

Troubleshooting

Symptom: Cannot Connect to LDAP Server

Diagnosis: Verify network connectivity and server configuration.

Possible Causes:

• Incorrect server hostname or IP address
• Network firewall blocking LDAP ports
• Directory service not running
• Wrong port configured

Resolution Steps:

1. Verify network connectivity from rConfig server:

   telnet ldap.company.com 389
   telnet ldap.company.com 636

2. Check DNS resolution:

   nslookup ldap.company.com

3. Verify firewall rules permit traffic:

   sudo iptables -L | grep -E "389|636"

4. Test with ldapsearch utility:

   ldapsearch -H ldap://ldap.company.com:389 -x -b "DC=company,DC=com"

5. Review System Logs for specific error messages

Symptom: Invalid Bind Credentials Error

Diagnosis: Verify service account credentials and permissions.

Possible Causes:

• Incorrect bind username or password
• Service account locked or disabled
• Service account lacks read permissions
• Bind username format incorrect for directory type

Resolution Steps:

1. Verify service account credentials in directory service

2. Test service account with ldapsearch:

   ldapsearch -H ldap://ldap.company.com:389 -D "CN=rConfigService,DC=company,DC=com" -W -b "DC=company,DC=com"

3. Verify service account is not locked or disabled in directory

4. Check service account has read permissions on users and groups

5. Ensure bind username format matches directory type (DN for AD, uid for FreeIPA)

Symptom: User Not Found in Directory

Diagnosis: Verify Base DN and user location.

Possible Causes:

• Base DN does not include user’s organizational unit
• User account does not exist in directory
• Username attribute mapping incorrect
• User located in different OU than Base DN

Resolution Steps:

1. Verify user exists in directory service

2. Confirm user’s full Distinguished Name includes Base DN

3. Expand Base DN to broader scope if needed:

   Before: OU=IT,DC=company,DC=com
   After:  DC=company,DC=com

4. Test directory query with ldapsearch:

   ldapsearch -H ldap://ldap.company.com:389 -D "bind-user" -W -b "DC=company,DC=com" "([email protected])"

5. Verify username attribute mapping matches directory schema

Symptom: User Not in Authorized Group

Diagnosis: Verify group membership and group name configuration.

Possible Causes:

• User not a member of specified security group
• Group name configured incorrectly (using DN instead of CN)
• Group does not exist in directory
• Nested group membership not evaluated

Resolution Steps:

1. Verify user is member of authorized group in directory service

2. Confirm group name uses CN format only:

   Correct: rConfig Users
   Incorrect: CN=rConfig Users,OU=Groups,DC=company,DC=com

3. Test group membership query:

   ldapsearch -H ldap://ldap.company.com:389 -D "bind-user" -W -b "DC=company,DC=com" "(&(objectClass=group)(cn=rConfig Users))"

4. Add user to authorized group if not already member

5. Verify nested groups are not being used (direct membership required)

Symptom: SSL Certificate Errors

Diagnosis: Verify certificate trust and validity.

Possible Causes:

• Directory service certificate not trusted by rConfig server
• Self-signed certificate not imported into trust store
• Certificate expired
• Certificate hostname mismatch

Resolution Steps:

1. Verify certificate validity:

   openssl s_client -connect ldap.company.com:636

2. Check certificate expiration date in output

3. For self-signed certificates, import into system trust store:

   sudo cp ca-certificate.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates

4. Restart web server after trust store updates:

   sudo systemctl restart apache2  # or nginx

5. Retry LDAP test connection after certificate trust established

Symptom: Password Synchronization Not Working

Diagnosis: Verify password sync is enabled and user has logged in.

Possible Causes:

• Password sync disabled in configuration
• User has not logged in since password sync was enabled
• Encryption key changed invalidating synchronized passwords
• Database permission issues preventing password writes

Resolution Steps:

1. Verify password sync is enabled in LDAP settings
2. Confirm user logged in successfully at least once since enabling sync
3. Check System Logs for password synchronization errors
4. Verify database connectivity and permissions
5. Have user log in again with current password to re-sync

Symptom: LDAP Users Locked Out After Enabling

Diagnosis: Configuration error preventing LDAP authentication

Possible Causes:

• LDAP configuration incorrect but Enable LDAP was activated
• All LDAP servers unreachable
• Password synchronization not enabled and LDAP unavailable
• Authorized group misconfigured preventing all access

Resolution Steps:

1. Do NOT panic - local admin accounts should still work for fallback access
2. Log in using local administrator account
3. Navigate to Settings → System Settings → LDAP Authentication
4. Disable Enable LDAP temporarily
5. Review and correct configuration parameters
6. Test connection with corrected settings
7. Only re-enable LDAP after successful test
8. If local admin account also fails, disable LDAP via command line:

   sudo nano /var/www/html/rconfig8/current/.env

   Set:

   LDAP_ENABLED=false

   Save and restart web server:

   sudo systemctl restart apache2  # or nginx

Caution

Always maintain at least one local administrator account with a strong password before enabling LDAP. This provides emergency access if LDAP configuration prevents authentication. Store local admin credentials securely (password manager) for disaster recovery scenarios.

Best Practices

Implementation

Test in non-production first: Configure and test LDAP integration in development or staging environments before enabling in production. Validate all failure scenarios including LDAP outages, incorrect credentials, and group membership changes.

Phase rollout: Enable LDAP for small pilot group initially. After confirming successful operation, expand to broader user population. This limits impact of configuration issues.

Document configuration: Maintain detailed documentation of LDAP configuration including server hostnames, Base DN, group names, and attribute mappings. Include contact information for directory service administrators. Store documentation securely outside rConfig for reference during outages.

Coordinate with directory administrators: Work closely with Active Directory or FreeIPA administrators during configuration and testing. They can provide correct values for Base DN, verify group memberships, and troubleshoot directory-side issues.

Create dedicated service account: Use service account specifically for rConfig LDAP integration rather than repurposing existing service accounts. This simplifies auditing and permission management.

Operations

Monitor LDAP health: Implement monitoring for directory service connectivity from rConfig server. Alert on connection failures, authentication errors, or increased latency indicating directory service issues.

Test failover regularly: Periodically test LDAP server failover by temporarily disabling primary server. Verify secondary servers assume authentication without user impact.

Validate fallback authentication: Test local authentication fallback by temporarily making LDAP servers unreachable. Confirm users with synchronized passwords can still access rConfig.

Review user accounts quarterly: Conduct regular reviews of LDAP-authenticated users. Identify accounts for users who left the organization, changed roles, or no longer require rConfig access. Remove or adjust permissions accordingly.

Audit group memberships: Regularly audit directory security group membership for authorized rConfig users. Ensure membership aligns with current organizational structure and access requirements.

Security

Enable encrypted connections: Always use SSL (LDAPS) or TLS (StartTLS) for production LDAP communications. Unencrypted LDAP exposes credentials during authentication.

Rotate service account credentials: Change LDAP bind account password regularly according to organizational security policy. Update rConfig configuration immediately after rotation.

Implement strong group controls: Use dedicated security group for rConfig access control rather than broad groups like “All IT Staff”. Specific groups provide better audit trails and simplified access management.

Monitor authentication failures: Review Application Logs regularly for repeated authentication failures indicating potential brute force attacks or account compromise attempts.

Protect encryption key: The application encryption key protects synchronized passwords. Ensure .env file containing this key has restrictive permissions and is excluded from insecure backups. See System Encryption Key for key protection guidance.

Disable unneeded features: If organizational policy prohibits password synchronization, disable this feature even though it reduces fallback authentication capability. Security policy compliance takes precedence over convenience.

Maintenance

Plan for directory service maintenance: Coordinate with directory service administrators about planned maintenance windows. Ensure fallback authentication is functional before maintenance begins.

Update certificates proactively: Monitor directory service SSL certificate expiration dates. Renew certificates well before expiration to prevent authentication outages. Test rConfig LDAP connectivity after certificate renewals.

Review configuration after upgrades: After rConfig version upgrades, validate LDAP configuration remains correct and functional. Test authentication with multiple users before declaring upgrade complete.

Maintain emergency access: Regularly test local administrator accounts to ensure emergency access works if LDAP fails. Rotate local admin passwords periodically and store credentials securely.

Document changes: Maintain change log of LDAP configuration modifications including what changed, why, who approved, and when implemented. This aids troubleshooting and audit compliance.

Performance Optimization

Connection Pooling

LDAP connections are pooled and reused to minimize authentication latency:

Connection pool behavior: rConfig maintains persistent connections to directory servers, reusing connections across multiple authentication attempts. This eliminates connection establishment overhead for each login.

Connection timeout: Idle connections are closed after timeout period to prevent resource exhaustion. New connections are established as needed for authentication requests.

Multiple servers: Each configured LDAP server has independent connection pool. Connections are established to servers only when needed for authentication or failover.

Caching Considerations

LDAP user information is cached after successful authentication to reduce directory queries:

Cached information:

• User profile data (name, email)
• Group membership for authorized group
• User account status

Cache duration: User information cached for session duration. Next login retrieves fresh data from directory service ensuring changes (name updates, group membership changes) are reflected.

Cache invalidation: Cache is automatically invalidated when:

• User logs out
• Session expires
• LDAP configuration changes
• User account is modified by administrator

Load Balancing

When multiple LDAP servers are configured, rConfig distributes load across servers:

Load distribution: Authentication attempts are directed to first available server in configured list. If first server is busy or slow to respond, subsequent requests may use alternate servers.

Health checking: Server health is inferred from authentication success/failure patterns. Repeatedly failing servers are temporarily deprioritized in favor of servers responding successfully.

Geographic distribution: For globally distributed deployments, configure geographically close directory servers first in the list to minimize authentication latency.

Compliance and Auditing

Authentication Audit Trails

LDAP authentication events are logged for compliance and security auditing:

Logged events:

• Successful LDAP authentication attempts
• Failed LDAP authentication attempts (invalid credentials)
• Fallback to local authentication
• Group membership check results
• New user account creation via LDAP
• Password synchronization events

Accessing logs: View authentication events in the Application Log:

1. Navigate to Application Log
2. Filter by severity: Info (successful) or Error (failures)
3. Search for keywords: LDAP, authentication, login

See Application Log for detailed log review procedures.

User Activity Tracking

The User Activity Log tracks all authentication activity including LDAP events:

1. Navigate to Users → Activity Log
2. Filter by event type: Login, Logout, Failed Login
3. Review source IP addresses and timestamps
4. Export log data for external analysis or compliance reporting

See User Management for user activity log documentation.

Compliance Reporting

Generate compliance reports demonstrating access control effectiveness:

User access report: Export list of all LDAP-authenticated users with roles, last login dates, and approval status. Demonstrates who has access and when they last used it.

Authentication failure report: Report on failed authentication attempts by user, source IP, and timestamp. Identifies potential security issues or compromised credentials.

Group membership report: Document which directory security groups map to which rConfig roles. Demonstrates alignment between directory access control and rConfig permissions.

Configuration audit: Maintain dated records of LDAP configuration changes including what changed, business justification, approver, and implementation date.

Migration and Disaster Recovery

Migrating to LDAP from Local Authentication

When migrating existing local user accounts to LDAP:

Migration planning:

1. Identify which local users should migrate to LDAP
2. Ensure corresponding accounts exist in directory service
3. Add users to LDAP authorized group
4. Document username mapping (local username to LDAP username)

Migration procedure:

1. Configure LDAP integration following standard procedures
2. Test with pilot users before broad rollout
3. Communicate migration to all users with instructions
4. Users log in with LDAP credentials, triggering automatic account provisioning
5. Approve new LDAP accounts as they appear in Users list
6. Assign appropriate roles matching previous permissions
7. Disable or delete old local accounts after confirming LDAP accounts work
8. Maintain admin local accounts for emergency access

User communication: Inform users their login credentials will change from local username/password to LDAP/directory credentials. Provide clear instructions on format (e.g., “use your company email address and network password”).

Disaster Recovery Scenarios

LDAP configuration loss: If LDAP configuration is lost (database corruption, accidental deletion):

1. Access rConfig using local administrator account
2. Restore LDAP configuration from documented settings
3. Test configuration before re-enabling
4. Review backup procedures to prevent future loss

Directory service failure: During extended directory service outages:

1. Users with synchronized passwords can authenticate locally
2. Users without synchronized passwords cannot access rConfig
3. Monitor directory service restoration progress
4. Communicate status to affected users
5. After restoration, verify LDAP authentication resumes normally

rConfig server failure: When restoring rConfig from backup:

1. Restore rConfig application and database from backup
2. LDAP configuration restores with database
3. Verify .env file contains correct encryption key
4. Test LDAP authentication after restoration
5. Synchronized passwords remain valid if encryption key unchanged

Encryption key loss: If application encryption key is lost:

1. Synchronized passwords become unrecoverable
2. LDAP authentication continues functioning (primary authentication method)
3. Local fallback authentication fails for LDAP users
4. Local admin accounts unaffected if created before LDAP enabled
5. Generate new encryption key and have users log in to re-sync passwords

See System Encryption Key for key management procedures.

Related Documentation

• User Management - Managing user accounts and approval workflow
• Roles and Permissions - Role-based access control and permission management
• System Encryption Key - Protecting synchronized passwords with encryption
• Application Log - Viewing authentication events and troubleshooting
• Security Best Practices - Comprehensive security hardening guidance

Summary

LDAP integration in rConfig V8 provides centralized authentication, automatic user provisioning, and high availability through directory service integration. Organizations can leverage Active Directory or FreeIPA to manage rConfig access control using existing identity infrastructure, eliminating duplicate credential management and simplifying user lifecycle administration.

Key takeaways for successful LDAP integration:

• Test thoroughly in non-production environments before enabling in production to validate configuration and failure scenarios
• Enable SSL/TLS for encrypted communication protecting credentials during transmission
• Configure multiple servers for high availability ensuring authentication continues during individual server failures
• Enable password synchronization for fallback authentication during directory service outages
• Maintain local admin accounts as emergency access method if LDAP integration fails
• Use dedicated security groups for precise access control and simplified audit trails
• Monitor authentication logs regularly for security incidents and configuration issues

Proper LDAP integration balances security, availability, and operational efficiency, enabling organizations to manage rConfig access through proven enterprise identity management systems while maintaining fallback mechanisms ensuring continuous access to critical network configuration management capabilities.