Important

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.

Note

LDAP server implementations and schemas vary widely. As such, there are no complete and specific examples in this document.

LDAP Configuration

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.

Note

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.com in this field, the server certificate must include an FQDN value of ldap.example.com, and ldap.example.com must 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 389 for Standard TCP and STARTTLS, and 636 for SSL. This field is updated automatically with the proper default value based on the selected Transport.

Note

When using port 636 for SSL, pfSense® uses an ldaps:// URL, not STARTTLS. Ensure that the LDAP server is listening on the correct port with the correct mode.

Transport

This setting controls which transport method will be used by the firewall to communicate with the LDAP server.

Warning

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 389 but negotiates encryption with the server using STARTTLS.

Note

Not all LDAP servers support STARTTLS, check the LDAP server documentation and configuration.

SSL/TLS Encrypted

Connects using SSL/TLS on TCP port 636 to encrypt LDAP queries.

Note

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.

Level

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.

Tip

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. DC=example,DC=com

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.

Tip

If the LDAP server supports it, and the bind settings are correct, click fa-search Select a container to browse the LDAP server and select containers from a list.

Some examples of containers are:

  • CN=Users;DC=example;DC=com This 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=com This searches in two different locations, the second of which is restricted to the OtherUsers organizational unit.

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:

memberOf=CN=VPNUsers,CN=Users,DC=example,DC=com
Bind credentials

Controls how this LDAP client will attempt to bind to the server.

Note

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.

Attributes
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 cn or samAccountName.

Group naming attribute

The attribute used to identify a group, such as cn.

Group member attribute

The attribute of a user that signifies it is the member of a group, such as member, memberUid, memberOf, or uniqueMember.

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.

Note

In this mode the Group member attribute will 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 posixGroup but 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@hostname will have the @hostname portion 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.

Warning

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

  • Click fa-plus Add

  • 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

LDAP Groups

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.)