Netgate is offering COVID-19 aid for pfSense software users, learn more.
LDAP Authentication Servers¶
Though Lightweight Directory Access Protocol (LDAP) is technically a repository for user information, it also supports mechanisms for user authentication via bind operations.
There are many popular user directory implementations which use LDAP, including Active Directory, OpenLDAP, FreeIPA, and more.
LDAP server implementations and schemas vary widely. As such, there are no complete and specific examples in this document.
- Hostname or IP address
The address of the LDAP server. This can be a fully qualified domain name, an IPv4 IP address, or an IPv6 IP address.
If this LDAP server uses SSL, the value of this field must match the certificate presented by the LDAP server. Typically this means it must be a hostname which resolves to the IP address of the LDAP server, but the specific requirements depend on the contents of the server certificate.
For example, with a value of
ldap.example.comin this field, the server certificate must include an FQDN value of
ldap.example.commust resolve to
192.168.1.5. One exception to this is if the IP address of the server also happens to be the listed in the server certificate.
This can be worked around in some cases by creating a DNS host override to make the server certificate hostname resolve to the correct IP address if they do not match in this network infrastructure and they cannot be easily fixed.
- Port value
This setting specifies the port on which the LDAP server is listening for LDAP queries. The default port is
389for Standard TCP and STARTTLS, and
636for SSL. This field is updated automatically with the proper default value based on the selected Transport.
When using port
636for SSL, pfSense® uses an
ldaps://URL, not STARTTLS. Ensure that the LDAP server is listening on the correct port with the correct mode.
This setting controls which transport method will be used by the firewall to communicate with the LDAP server.
LDAP queries will contain sensitive data, such as usernames, passwords, and other information about the user. The best practice is for the firewall to use encryption when communicating with the LDAP server, if the LDAP server supports it. Both SSL/TLS and STARTTLS will encrypt traffic between the firewall and the LDAP server.
- Standard TCP
(Default) Plain unencrypted TCP connections on port
389. This is not secure, but is widely supported and also useful for debugging with packet captures. Do not use this protocol across untrusted networks.
- STARTTLS Encrypted
Connects using TCP port
389but negotiates encryption with the server using STARTTLS.
Not all LDAP servers support STARTTLS, check the LDAP server documentation and configuration.
- SSL/TLS Encrypted
Connects using SSL/TLS on TCP port
636to encrypt LDAP queries.
Not all LDAP servers support SSL/TLS, check the LDAP server documentation and configuration.
- Peer Certificate Authority
The CA chosen with this selector is used by the firewall to validate the LDAP server certificate when Transport is set to SSL/TLS Encrypted or STARTTLS Encrypted mode.
The selected CA must match the CA which signed the LDAP server certificate, otherwise validation will fail. If the LDAP server is using a globally trusted certificate (e.g. Let’s Encrypt or another public CA), choose Global Root CA List.
See Certificate Authority Management for more information on creating or importing CAs.
- Client Certificate
(Factory only) This certificate is sent to the LDAP server to identify this client when using an encrypted transport mode. If the LDAP server requires a client certificate, the server will use this certificate to ensure that the firewall is authorized to make LDAP queries.
This certificate must be issued by the CA used by the LDAP server to validate connecting clients.
- Protocol version
Chooses which version of the LDAP protocol is employed by the LDAP server, either 2 or 3, typically 3.
- Server Timeout
The time, in seconds, after which LDAP operations are considered as failed. Using a lower value will allow the GUI to try other authentication sources faster when the server fails. If the LDAP server is slow or overloaded, a larger value can help the firewall accept delayed responses.
- Search scope
Determines where, and how deep, an LDAP search will be performed to locate a match.
Controls the depth of the LDAP search.
- One Level
Search only one level, defined by the Authentication Containers.
- Entire Subtree
Search the entire subtree of the directory, starting with the Authentication Containers.
This is typically the best choice, and is nearly always required for Active Directory configurations.
- Base DN
Controls where the search will start. Typically set to the root of the LDAP structure, e.g.
- Authentication containers
A list of potential account locations or containers, separated by semicolons. These containers will be prepended to the Base DN above when the firewall crafts LDAP queries. Alternately, specify a full container path here and leave the Base DN blank.
If the LDAP server supports it, and the bind settings are correct, click Select a container to browse the LDAP server and select containers from a list.
Some examples of containers are:
CN=Users;DC=example;DC=comThis searches for users inside of the domain component
example.com, a common syntax for Active Directory
CN=Users,DC=example,DC=com;OU=OtherUsers,DC=example,DC=comThis searches in two different locations, the second of which is restricted to the
- Extended Query
Specifies an extra restriction to query after the username, which allows group membership to be used as a filter. This must include both the item to search as well as the method of searching. For example, a restriction based on group membership would use
memberOf. Check the LDAP server documentation for information on forming such queries.
To set an extended query, check the box and fill in the Query value with a filter such as:
- Bind credentials
Controls how this LDAP client will attempt to bind to the server.
Active Directory typically requires the use of bind credentials and may need a service account or administrator-equivalent depending on the server configuration. Consult Windows documentation to determine which is necessary in a specific environment.
- Bind Anonymous
(Default) When checked the firewall will use anonymous binds. When unchecked the GUI presents the Bind Credentials fields.
- Bind Credentials (User DN/Password)
When Bind Anonymous is unchecked, the credentials in these fields are used by the firewall to make authenticated binds when performing a query.
The User DN may be a username or a full DN, depending on what the LDAP server requires.
- Initial Template
This option only appears when initially creating an LDAP server entry. It pre-fills the remaining options on the page with common defaults for a given type of LDAP server. The choices include OpenLDAP, Microsoft AD, and Novell eDirectory.
- User naming attribute
The attribute used to identify the name of a user, most commonly
- Group naming attribute
The attribute used to identify a group, such as
- Group member attribute
The attribute of a user that signifies it is the member of a group, such as
- RFC2307 Groups
Specifies how group membership is organized on the LDAP server. When unset (default), the queries assume the server uses Active Directory style group membership (RFC 2307bis) where groups are listed as an attribute of the user object. When checked, queries use RFC 2307 style group membership where the users are listed as members on the group object.
In this mode the
Group member attributewill typically be set to
memberUid, but may vary by LDAP schema.
- RFC2307 User DN
When set, queries include the user DN when searching for groups.
- Group Object Class
Specifies the object class of RFC 2307 style groups. Typically
posixGroupbut it may vary by LDAP schema. Not necessary for Active Directory style groups.
- UTF8 Encode
When checked, queries to the LDAP server are encoded for UTF-8 and the responses are decoded from UTF-8. Support varies depending on the LDAP server. Generally only necessary if user names, groups, passwords, and other attributes contain UTF-8 or international style accented characters.
- Username Alterations
When unchecked, a username given as
user@hostnamewill have the
@hostnameportion stripped so only the username is sent in the LDAP bind request. When checked, the username is sent in full.
- Allow Unauthenticated Bind
When set, bind requests with empty passwords will be rejected locally. Some LDAP servers, specifically Microsoft Active Directory, will accept unauthenticated bind requests and treat them as successful.
This behavior must be disabled on the LDAP server where possible. Allowing requests to succeed with an empty password is a significant security risk and it affects any device or service authenticating against an LDAP server.
Though this option allows pfSense software to reject such authentication attempts, other LDAP clients may not offer the same choice. Disabling the feature on the server is the most secure means of correcting the problem. Consult the LDAP server documentation for information on disabling this behavior.
Adding an LDAP Server¶
To add a new LDAP server:
Make sure that the LDAP server can be reached by the firewall
Import the Certificate Authority used by the LDAP server into pfSense before proceeding if using SSL/TLS or STARTTLS encryption
See Certificate Authority Management for more information on creating or importing CAs.
Navigate to System > User Manager, Authentication Servers tab
Set the Type selector to LDAP
The GUI will change the form to display LDAP server settings
Fill in the fields as described previously in LDAP Configuration
Click Save to create the server
Visit Diagnostics > Authentication to test the LDAP server using a valid account
There are two requirements for LDAP groups to function properly:
The LDAP authentication settings must match the group membership style used by the LDAP server
The same groups must exist locally (Manage Local Groups)
If the LDAP query returns the group list properly for a user, and the groups exist locally, then the groups will be listed on the results when using the Diagnostics > Authentication page to test an account.
If the groups do not show up, ensure they exist on pfSense with matching names and that the proper group structure is present on the LDAP authentication server entry (e.g. RFC 2703 options.)