LDAP Connector
The LDAP connector enables authentication against any RFC 4510-compliant LDAP directory server — OpenLDAP, 389 Directory Server, FreeIPA, Novell eDirectory, and others. While the Active Directory connector is optimised for Microsoft domain environments, the generic LDAP connector supports the full range of LDAP schema variants through configurable filter expressions and attribute mappings.
'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}public/assets/img/docs/connector-ldap/overview.png
LDAP vs Active Directory Connector
The Active Directory connector is purpose-built for Windows AD environments and handles AD-specific behaviours automatically (UPN suffix, sAMAccountName lookup, nested group membership). The generic LDAP connector is used for all other LDAP-compatible directories:
| Active Directory Connector | LDAP Connector | |
|---|---|---|
| Best for | Windows Server AD domains | OpenLDAP, FreeIPA, 389 DS, eDirectory, etc. |
| Username format | Automatically appends account_suffix | Resolved via configurable user_filter |
| User lookup | Searches using sAMAccountName by default | Searches using configurable username_attribute |
| Schema | Fixed AD schema; common attributes pre-mapped | Fully configurable — any LDAP schema |
Configuration Fields
| Field | Description |
|---|---|
name | Instance label to distinguish this LDAP connector from others (e.g., FreeIPA Production, OpenLDAP HQ) |
is_active | Enable or disable this connector without losing configuration |
host | Hostname or IP address of the LDAP server (e.g., ldap.example.com or 192.168.10.5) |
port | LDAP port. Default: 389 for LDAP, 636 for LDAPS. |
use_ssl | Connect using LDAPS (LDAP over SSL/TLS on port 636). The server must present a valid certificate. |
use_tls | Upgrade an existing LDAP connection to TLS using STARTTLS (typically on port 389). Mutually exclusive with use_ssl. |
base_dn | The LDAP search base — the distinguished name of the subtree Kiwire searches for user entries (e.g., ou=people,dc=example,dc=com) |
bind_dn | The full DN of the service account used to bind to the directory for user lookup (e.g., cn=kiwire-svc,ou=services,dc=example,dc=com). Leave blank only if your directory allows anonymous binds for user search. |
bind_password | Password for the bind DN service account. Stored encrypted at rest. |
username_attribute | The LDAP attribute that holds the username. Users enter this value in the login form. Common values: uid (OpenLDAP), sAMAccountName (AD-style), mail (email as username). |
user_filter | LDAP search filter used to locate the user entry. Use {{username}} as a placeholder for the value entered by the user (e.g., (uid={{username}}) or (&(mail={{username}})(objectClass=inetOrgPerson))). |
The user_filter must be a valid LDAP filter expression. The {{username}} placeholder is substituted with the exact string entered by the user in the login form. Test your filter with an LDAP browser tool (e.g., Apache Directory Studio) before saving the connector configuration.
Encryption Options
Kiwire supports two methods for encrypting LDAP traffic:
- LDAPS (
use_ssl = true) — establishes a TLS-encrypted connection from the start on port 636. The server must present a certificate signed by a trusted CA. This is the recommended option for modern LDAP servers. - STARTTLS (
use_tls = true) — connects on port 389 in plaintext and then upgrades the connection to TLS using the STARTTLS extended operation. Some older LDAP servers only support this method.
Do not use plain LDAP (no SSL or TLS) in production environments. User credentials are transmitted in plaintext during the bind operation. Enable at least STARTTLS if LDAPS is not available.
Attribute Mapping
The LDAP connector supports the same attribute mapping system as the Active Directory connector. Configure the mapping in the Advanced Configuration section to populate Kiwire user fields from directory attributes:
| Common LDAP Attribute | OpenLDAP / FreeIPA attribute | Kiwire Field |
|---|---|---|
| Email address | mail | email_address |
| Full name | cn or displayName | fullname |
| Phone number | telephoneNumber or mobile | phone_number |
| Username | uid | username |
| Department | ou or departmentNumber | department |
| Employee ID | employeeNumber | employee_id |
Testing the Connection
Click Test Connection after saving to verify that Kiwire can reach the LDAP server and successfully bind with the service account credentials. The test also validates the base_dn by performing a test search and reporting the number of entries found.
Use the User Authentication Test to enter a real username and password and trace the full authentication path — service bind → user search using the user_filter → user bind with provided password → attribute retrieval. This confirms end-to-end LDAP authentication is working before enabling the connector on the live portal.
If the User Authentication Test fails at the "user search" step but the service bind succeeds, check your user_filter expression. Use an LDAP browser to run the filter manually and confirm it returns exactly one result for a known test user.
Required Permissions
view-connector-ldap · edit-connector-ldap