Netgate is offering COVID-19 aid for pfSense software users, learn more.
From the pfSense® WebGUI, using the Authentication Servers tab under System > User Manager, RADIUS and LDAP servers may be defined as authentication sources. See Support Throughout pfSense for information on where these servers may be used in pfSense software currently. To add a new server from this screen, click Add. To edit an existing server, click next to its entry.
For additional information, you may access the Hangouts Archive to view the August 2015 Hangout on RADIUS and LDAP.
To add a new RADIUS server:
Make sure that the RADIUS server has the firewall defined as a client before proceeding.
Navigate to System > User Manager, Authentication Servers tab.
Set the Type selector to RADIUS. The RADIUS Server Settings will be displayed.
Fill in the fields as described below:
- Descriptive name
The name for this RADIUS server. This name will be used to identify the server throughout the pfSense GUI.
- Hostname or IP address
The address of the RADIUS server. This can be a fully qualified domain name, or an IPv4 IP address.
- Shared Secret
The password established for this firewall on the RADIUS server software.
- Services offered
This selector set which services are offered by this RADIUS server. Authentication and Accounting , Authentication only, or Accounting only. Authentication will use this RADIUS server to authenticate users. Accounting will send RADIUS start/stop accounting packet data for login sessions if supported in the area where it is used.
- Authentication port
Only appears if an Authentication mode is chosen. Sets the UDP port where RADIUS authentication will occur. The default RADIUS authentication port is 1812.
- Accounting port
Only appears if an Accounting mode is chosen. Sets the UDP port where RADIUS accounting will occur. The default RADIUS accounting port is 1813.
- Authentication Timeout
Controls how long, in seconds, that the RADIUS server may take to respond to an authentication request. If left blank, the default value is 5 seconds. If an interactive two-factor authentication system is in use, increase this timeout to account for how long it will take the user to receive and enter a token, which can be 60-120 seconds or more if it must wait for an external action such as a phone call, SMS message, etc.
Click Save to create the server.
Visit Diagnostics > Authentication to test the RADIUS server using a valid account.
For RADIUS groups, the RADIUS server must return a list of groups in the
Class RADIUS reply attribute as a string. Multiple groups must be separated
by a semicolon.
For example, in FreeRADIUS, to return the “admins” and “VPNUsers” groups, the following Reply-Item RADIUS Attribute would be used:
Class := "admins;VPNUsers"
If the RADIUS server 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 server is returning the Class attribute as a string, not binary.
To add a new LDAP server:
Make sure that the LDAP server can be reached by the firewall.
If SSL will be used, import the Certificate Authority used by the LDAP server into pfSense before proceeding. See Certificate Authority Management for more information on creating or importing CAs.
Navigate to System > User Manager, Servers tab.
Set the Type selector to LDAP. The LDAP Server Settings will be displayed.
Fill in the fields as described below:
- 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 SSL will be used, a Hostname must be specified here and the hostname must match the Common Name of the server certificate presented by the LDAP server and that hostname must resolve to the IP address of the LDAP server, e.g. CN=ldap.example.com, and ldap.example.com is 192.168.1.5. The only exception to this is if the IP address of the server also happens to be the CN of its server certificate.
This can be worked around in some cases by creating a DNS Forwarder host override to make the server certificate CN 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 TCP port is 389, and 636 for SSL. This field is updated automatically with the proper default value based on the selected Transport.
When using port 636 for SSL, pfSense uses an ldaps:// URL, it does not support 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 to communicate with the LDAP server. The first, and default, selection is TCP - Standard which uses plain TCP connections on port 389. A more secure choice, if the LDAP server supports it, is SSL - Encrypted on port 636. The SSL choice will encrypt the LDAP queries made to the server, which is especially important if the LDAP server is not on a local network segment.
It is always recommended to use SSL where possible, though plain TCP is easier to setup and diagnose since a packet capture would show the contents of the queries and responses.
- Peer Certificate Authority
If SSL - Encrypted was chosen for the Transport, then the value of this selector is used to validate the certificate of the LDAP server. The selected CA must match the CA configured on the LDAP server, otherwise problems will arise. See Certificate Authority Management for more information on creating or importing CAs.
- Protocol version
Chooses which version of the LDAP protocol is employed by the LDAP server, either 2 or 3, typically 3.
- Search scope
Determines where, and how deep, a search will go for a match.
Choose between One Level or Entire Subtree to control how deep the search will go. Entire Subtree is the best choice when the decision is not certain, 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 semicolon-separated list of potential account locations or containers. These containers will be prepended to the search Base DN above or 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 the Select button to browse the LDAP server containers and select them there. Some examples of these containers are:
CN=Users;DC=example;DC=comThis would search for users inside of the domain component example.com, a common syntax to see for Active Directory
CN=Users,DC=example,DC=com;OU=OtherUsers,DC=example,DC=comThis would search 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. To set an Extended Query, check the box and fill in the value with a filter such as:
- Bind credentials
Controls how this LDAP client will attempt to bind to the server. By default the Use anonymous binds to resolve distinguished names box is checked to perform an anonymous bind. If the server requires authentication to bind and perform a query, uncheck that box and then specify a User DN and Password to be used for the bind.
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.
- Initial Template
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 a user’s name, 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 unchecked, Active Directory style group membership is used where groups are listed as an attribute of the user object. When checked, RFC 2307 style group membership is used where the users are listed as members on the group object.
When this is used, the Group member attribute may also need
changed, typically it would be set to
memberUid in this case, but may vary
by LDAP schema.
- Group Object Class
Used with RFC 2307 style groups, it specifies the object class of the group, typically
posixGroupbut it may vary by LDAP schema. It is not needed for Active Directory style groups.
- UTF8 Encode
When checked, queries to the LDAP server will be UTF8-encoded and the responses will be UTF8-decoded. Support varies depending on the LDAP server. Generally only necessary if user names, groups, passwords, and other attributes contain non-traditional 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.
Click Save to create the server.
Visit Diagnostics > Authentication to test the LDAP server using a valid account.
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 selected (e.g. RFC 2703 groups may need to be selected.)