LDAP integration — central identity for the fleet

A fleet of firewalls with two hundred operators should not have two thousand local accounts. The canonical identity store is the directory — Active Directory, OpenLDAP, 389 Directory Server, FreeIPA — and the firewalls authenticate against it.

LDAP (Lightweight Directory Access Protocol) is the protocol that almost every directory speaks. This lesson covers how LDAP authentication works at the protocol level, how to configure OPNsense to authenticate against an LDAP directory, how to design LDAP groups that map to OPNsense roles, and the LDAP failure modes that lock operators out.

How LDAP authentication works

LDAP authentication is two operations:

1. Bind. The client (OPNsense) opens a connection to the LDAP server and authenticates. The bind can be anonymous, simple (username + password), or SASL (Kerberos, etc.). The bind credential is for the service account the firewall uses to talk to LDAP — not for the operator being authenticated.
2. Search. The firewall searches the directory for the operator’s record, using the bind service account’s permissions. The search filter is typically the username the operator typed into the GUI. The directory returns the matching entries (or none).

For operator authentication, the firewall uses the search to find the operator’s DN (distinguished name), then performs a second bind as the operator (with the password the operator typed) to verify the password is correct.

OPNsense                    LDAP server
  | --- Bind (service acct) ---->     |
  | <-- Bind success ------------     |
  | --- Search (filter) ----------->  |
  | <-- Entry: uid=jdoe,ou=ops,dc=ex |
  | --- Bind (jdoe, password) ---->   |
  | <-- Bind success (or failure) -  |

The bind result tells the firewall whether the operator’s password is correct. The search result tells the firewall which groups the operator belongs to, which the firewall maps to OPNsense roles.

Configuring OPNsense for LDAP

The configuration lives under System → Access → Servers. To add an LDAP server:

1. Click Add server.
2. Set the Type to LDAP.
3. Set the Hostname or IP to the LDAP server. Use the hostname so TLS certificate verification works.
4. Set the Port. 636 for ldaps://, 389 for ldap:// or STARTTLS.
5. Set the Transport to ldaps:// (or starttls if using STARTTLS on port 389).
6. Set the Bind DN — the service account the firewall uses for searches. Example: cn=opnsense-svc,ou=service-accounts,dc=example,dc=com.
7. Set the Bind password for the service account.
8. Set the Search base — where to look for operator records. Example: ou=operators,dc=example,dc=com.
9. Set the Search filter — what to match the username against. For AD: (&(objectClass=person)(userPrincipalName=%s)). For OpenLDAP: (&(objectClass=inetOrgPerson)(uid=%s)).
10. Set Extended query to retrieve group memberships. For AD: (&(objectClass=group)(member=%s)). For OpenLDAP: depends on the member attribute overlay.
11. Click Save, then Test to confirm the configuration works.

The OPNsense GUI attempts a test bind with the service account, runs a test search, and reports success or failure with diagnostic detail.

$ ldapsearch -H ldaps://ldap.example.com:636 -D "cn=opnsense-svc,ou=service-accounts,dc=example,dc=com" -w 'REDACTED' -b "ou=operators,dc=example,dc=com" "(&(objectClass=inetOrgPerson)(uid=jdoe))" dn cn mail memberOf

dn: uid=jdoe,ou=operators,dc=example,dc=com
cn: Jane Doe
mail: jdoe@example.com
memberOf: cn=admins,ou=groups,dc=example,dc=com
memberOf: cn=neteng,ou=groups,dc=example,dc=com

Designing LDAP groups

The directory should have groups that map cleanly to OPNsense roles. The mapping is configured in OPNsense under System → Access → Groups:

• Create an OPNsense group with the same name as the LDAP group (or use a mapping).
• Set the group’s privileges to the role’s permissions.
• LDAP-authenticated operators who are members of the LDAP group are automatically members of the OPNsense group with the role’s privileges.

Operators in multiple LDAP groups get the union of OPNsense group privileges. Membership changes in LDAP propagate to OPNsense on the next authentication.

LDAP failure modes

The LDAP integration has more failure modes than local authentication because the firewall now depends on the directory. The five most common:

1. LDAP server unreachable. Network partition, server down, DNS not resolving the LDAP hostname. Operators cannot authenticate. Fix: redundant LDAP servers, DNS monitoring, firebreaks.

2. Bind credential wrong. The service account password was rotated on the directory but not updated in OPNsense. The bind fails. Fix: monitor the OPNsense LDAP test result; update the bind password when the directory rotates.

3. Search returns nothing. The search base or filter does not match the operator’s record. The operator types a valid username but the firewall cannot find them. Fix: verify the search base and filter with ldapsearch outside OPNsense.

4. Certificate validation fails. ldaps:// requires the LDAP server certificate to chain to a CA the firewall trusts. A missing CA certificate in the trust store produces a TLS error. Fix: import the LDAP server CA certificate into System → Trust → Authorities.

5. Group mapping wrong. The LDAP group returns the operator as a member, but the OPNsense group is not configured to map from that LDAP group. The operator authenticates but has no privileges. Fix: verify the group mapping in System → Access → Groups.

$ openssl s_client -connect ldap.example.com:636 -servername ldap.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

subject=CN = ldap.example.com
issuer=O = Example Internal CA, CN = Example Internal Root
notBefore=Jun  1 00:00:00 2026 GMT
notAfter=Jun  1 00:00:00 2027 GMT

Operational discipline

The directory is a single point of failure for the entire identity stack. The discipline:

1. Run at least two LDAP servers. Master and replica (or multi-master). The firewall should be configured with both so a server outage does not lock everyone out.
2. Monitor the bind credential. The service account password rotation must be coordinated with OPNsense. Whoever rotates the directory password must update the firewall, or the bind fails for every operator.
3. Monitor certificate expiry. The LDAP server certificate must be renewed before expiry. The expiry monitoring lesson in this course applies.
4. Keep local break-glass accounts. When LDAP is down, operators need a way in. The local admin accounts described in the previous lesson are the answer.
5. Test authentication periodically. A cron job that attempts to authenticate a non-interactive test account and reports the result is the early-warning system for LDAP integration failures.

Summary

• LDAP bind authenticates the service account; LDAP search finds the operator’s record; a second bind as the operator verifies their password.
• Use ldaps:// or STARTTLS. Never bind in plaintext over the network.
• Map LDAP groups to OPNsense groups, which carry the role privileges. Membership changes propagate at next authentication.
• The directory is a single point of failure. Run redundant servers, monitor the bind credential, monitor certificate expiry, and keep local break-glass accounts.