Section 3.9. LDAP configuration

3.9. LDAP configuration

Radiator's LDAP support requires Perl Net::LDAP module version 0.32 or later. Operating system vendors and Windows Perl distributions typically include Net::LDAP. If it is not present in your Perl distribution, see Section 2.1.2. CPAN for how to obtain and install it. Net::LDAP works with Microsoft Active Directory, Novell/NetIQ eDirectory, OpenLDAP, 389 Directory Server/FreeIPA, and other LDAP servers.

When an LDAP clause needs to fetch information from the LDAP server, it connects to the LDAP server specified by Host. Optionally, you can authenticate Radiator as a valid user of the LDAP server by specifying AuthDN and AuthPassword. This is not the same thing as authenticating a user. It happens before querying the LDAP server, and proves that this radiusd is allowed to talk to the LDAP database.

LDAPS and StartTLS connection methods are supported. A number of TLS specific parameters control verification of server certificates. TLS client authentication with certificate is also supported.

Important

System certificate store is not used. The TLS configuration parameters must cover all CAs and other settings that are needed.

At present, LDAP clauses do synchronous connections and searches. This can mean significant delays if your LDAP server is reached by a slow network connection, or your LDAP server is slow. If this is the case, consider putting the LDAP server in a sub-server and having your main Radiator forward requests for that realm to the RADIUS sub-server.

The following configuration clauses utilise LDAP:

SASL Authentication of the LDAP connection

LDAP clauses support SASL authentication of the connection to the LDAP server. If SASL authentication is specified, the LDAP server uses SASL to authenticate the SASL user credentials specified by SASLUser and SASLPassword. You must configure your LDAP server to enable SASL authentication, and to map SASL user names to LDAP server administrator names. For example, when using OpenLDAP see their SASL configuration guide for the details.

3.9.1. BaseDN

This is the base DN relative to which the searches are made.

Special formatting characters are permitted. See the specific LDAP configuration clauses for more information about the clause-specific formatting characters.

Here is an example of using BaseDN:

# Start looking here
BaseDN o=University of Michigan, c=US

3.9.2. SearchFilter

Each Radiator LDAP clause defines a default SearchFilter that sets the conditions an entry in the directory must meet to be returned by the search.

Special formatting characters are permitted. See the specific LDAP configuration clauses for more information about the clause specific formatting characters. For example, the default search filter for

<ClientList
                     LDAP>

is:

SearchFilter (objectclass=oscRadiusClient)

3.9.3. Scope

This optional parameter allows you to control the search scope used to find the user. The default value is sub.

The permitted options are:

base
one
sub or subtree
children Requires Net::LDAP 0.48 or better and LDAPv3 subordinate feature extension

Here is an example of using Scope:

# We know where the entry should be
Scope base

3.9.4. AuthDN

This is the optional name to use to authenticate this Radiator server to the LDAP server. You only need to specify this if the LDAP server requires authentication from its clients.

AuthBy
                     LDAP2

supports %0 as a special for DN escaped currently authenticated user name.

Here is an example of using AuthDN:

# Log in to LDAP as admin. You man need a DN formatted name.
# AuthDN admin
AuthDN cn=admin,dc=example,dc=com

3.9.5. AuthPassword

This is the optional password to use to authenticate this Radiator server to the LDAP server. You only need to specify this if the LDAP server requires authentication from its clients, and you specify AuthDN.

Here is an example of using AuthPassword:

# log in to LDAP with password adminpassword
AuthPassword adminpassword

3.9.6. Host

This specifies the LDAP host names to connect to. The default value is localhost. Special formatting characters are permitted. Multiple host names can be specified, and in this case Radiator tries connecting each configured host individually until it succeeds. If a Host name begins with ipv6: the subsequent host names are interpreted as IPv6 addresses where possible, and Net::LDAP uses IPv6 to connect to the LDAP server. IPv6 may require IO::Socket::INET6, Socket6 or other IPv6 specific Perl modules depending on your Perl version.

Here are examples of using Host:

Host ldaphost.example.com

Same as above, but resolve the name to individual addresses before connecting:

# May resolve to multiple addresses.
# Implicitly sets SSLExpectedServerName to ldaphost.example.com for each address.
Host ldaphost.example.com
ResolveHost

When there are multiple Host values, connect to the first server that works:

# Connect to first available server
Host ldaphost1.example.org
Host ldaphost2.example.org
Host ldaphost3.example.org

IPv4 and IPv6 address can also be used. When TLS is enabled, we need to tell TLS library what is the expected name in each Host's server certificate:

# Server 10.20.30.11 has name ldaphost1.example.org in its certificate.
# Server 10.20.30.22 is named ldaphost2.example.org, respectively.
Host 10.20.30.11
Host 10.20.30.22

SSLExpectedServerName ldaphost1.example.org
SSLExpectedServerName ldaphost2.example.org

3.9.7. Port

This parameter specifies the port to connect to the LDAP host. The default value is 389, the standard port for unencrypted LDAP. If UseSSL is specified, the default value is 636, the standard port for encrypted LDAP. Port can be a numeric port number or a symbolic service name from etc/ services or its equivalent on your system. Usually, there is no need to override the defaults. Port can contain special formatting characters. A typical use of special formatting characters is with GlobalVar and command line arguments.

Here is an example of using Port:

# Connect using the SSL encrypted port
Port 636

3.9.8. ResolveHost

ResolveHost flag parameter causes Radiator to resolve LDAP server name to addresses instead of passing the name directly to the LDAP library. This allows Radiator to have separate connection and failure backoff parameters for each address. To refresh resolved addresses, name resolution is done periodically and after LDAP connection, bind and other failures. Periodic refresh is currently done after one hour has elapsed from the previous refresh. This allows adding and withdrawing server addresses from name service without restarting Radiator. For more examples, see Section 3.9.6. Host.

# Name ldaphost.example.com resolves to multiple addresses.
# Implicitly sets SSLExpectedServerName to ldaphost.example.com for each address.
Host ldaphost.example.com
ResolveHost

3.9.9. UseSSL

This optional parameter specifies to use direct TLS, often called LDAPS, to connect to the LDAP server. This is an alternative for upgrading to TLS with StartTLS operation. For more about StartTLS support, see Section 3.9.10. UseTLS.

Here is an example of using UseSSL:

# Enable direct SSL/TLS (LDAPS)
UseSSL

A full SSL/TLS configuration requires setting the certificate locations and possible other parameters.

# Enable direct SSL/TLS (LDAPS) and tell it where to find certificates
UseSSL

# Name of the client certificate file:
SSLCAClientCert %D/certificates/cert-clt.pem
# Name of the file containing the client private key
SSLCAClientKey %D/certificates/cert-clt.pem

# Only need to set one of the following
#SSLCAPath %D/cadirectory
SSLCAFile %D/certificates/demoCA/cacert.pem

Tip

All certificates are required to be in PEM format.

Tip

If both UseSSL and UseTLS are specified, UseSSL is prioritised.

3.9.10. UseTLS

This optional parameter is used in a similar way as UseSSL. For more information, see Section 3.9.9. UseSSL. UseTLS enables StartTLS LDAP operation to upgrade the LDAP connection to use TLS authentication and encryption. UseTLS takes the same parameters as UseSSL, including SSLVerify, SSLCiphers, SSLCAPath, SSLCAFile, SSLCAClientCert, and SSLCAClientKey.

# Use StartTLS with this LDAP server
UseTLS

Tip

If both UseSSL and UseTLS are specified, UseSSL is prioritised.

Note

Net::LDAP 0.57 and earlier had a bug where LDAP + StartTLS followed by LDAPS failed. This happens when a clause with UseTLS is followed by another clause with UseSSL.

3.9.11. Debug

This parameter enables debugging of the Net::LDAP module. This sets the Net::LDAP debug parameter for the connection, which prints to stdout. See Debug_TLS for how to view messages written to stdout.

You can use the following debugging options by adding together the relevant bits. The available values are shown below:

1
Show outgoing packets (using asn_hexdump)
2
Show incoming packets (using asn_hexdump)
4
Show outgoing packets (using asn_dump)
8
Show incoming packets (using asn_dump)

Here is an example of enabling Debug messages for outgoing and incoming packet using asn_dump:

Debug 12

3.9.12. DebugTLS

This integer parameter enables TLS debugging in IO::Socket::SSL for all TLS based LDAP connections. The debug messages are printed to stderr. The available values as listed by IO::Socket::SSL version 2.0.69 are shown below:

1
Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.
2
Print also information about call flow from IO::Socket::SSL and progress information from Net::SSLeay.
3
Print also some data dumps from IO::Socket::SSL and from Net::SSLeay.

The following Radiator configuration file example enables all available debugging:

DebugTLS 3

When Radiator is run directly on console, LDAP TLS debug messages are directly visible. When Radiator is started with systemd utilities, use its utilities to view stderr messages. For example, using Linux command line:

% sudo journalctl -u radiator
% less /var/log/messages

Another option is to add a local systemd configuration change to redirect stdout and stderr to a file. For the details, see Section 5.1. Systemd service unit file

3.9.13. Timeout

This optional parameter sets the timeout period in seconds for the connection to the LDAP server. The default value is 10 seconds. If this is set to 0, Radiator waits forever for LDAP connections and transactions.

If the connection times out :

LDAP authentication request are IGNOREd
LDAP Client list refresh is not done and Radiator continues to use the current client list

Here is an example of using Timeout:

# Make timeout really short, 2 seconds
Timeout 2

3.9.14. FailureBackoffTime

This optional parameter sets the period of time in seconds that this clause (AuthBy, <ClientListLDAP>, or other) stops trying to connect to its LDAP server after a connection failure. The default value is 600 seconds (10 minutes). This is intended to give the LDAP server time to recover after a failure. During the failure back-off interval, all authentication requests are IGNOREd.

3.9.15. BindFailedHook

This optional parameter allows you to define a Perl function that is run after an LDAP bind with AuthDN fails.

BindFailedHook is called with the following arguments:

A handle to the current Radius::Ldap object
AuthDN that failed LDAP bind
AuthPassword that was used with the failed LDAP bind
Error string from LDAP library
String with LDAP server and port the connection was made to
Possible SASL error string

The default is to log the error with the password set to **obscured**. If password debugging is required, redefine the hook or see console output when Debug flag parameter is enabled for the LDAP clause. For more information about Debug, see Section 3.9.11. Debug.

3.9.16. HoldServerConnection

By default the LDAP clauses, except

<AuthBy
                     LDAPRADIUS>

, disconnect from the LDAP server after each authentication. This is because not all LDAP servers permit multiple searches from the same LDAP connection. HoldServerConnection forces holding the connection to the LDAP server up for as long as possible. It is an optional parameter and available for <AuthBy LDAP2> and <AuthBy LDAPDIGIPASS>.

Most of the LDAP servers support this behaviour and it can significantly improve performance, especially where UseTLS or UseSSL is enabled. If you enable this parameter and get unwanted behaviour, you are probably using an unsupported LDAP server. In this case, remove this parameter.

Here is an example of using HoldServerConnection:

# Our server supports multiple searches
HoldServerConnection

Note

In some cases, using HoldServerConnection with ServerChecksPassword of

<AuthBy
                        LDAP2>

may cause failure situations. This is due to some LDAP servers' behaviour when the password check fails but the connection is not closed. A failure situation may also occur when the password check succeeds but the user is not allowed to perform searches in the server. If your users experience unexpected authentication failures, try testing your system without using these 2 parameters together.

3.9.17. NoBindBeforeOp

This optional parameter prevents Net::LDAP from binding with the AuthDN and password prior to a search operation.

Note

This is an advanced parameter. Most installations do not need to use it.

3.9.18. SSLVerify

This parameter can be used with UseSSL or UseTLS parameters to control how LDAP server's certificate is verified. The options are:

none
No server certificate is required, and if the server supplies a certificate it is not checked.
optional
Verify if the server offers a certificate.
require
The server must provide a certificate, and it must be valid.

The default value is require. Format specifiers, such as %{GlobalVar:name}, are evaluated when the configuration is loaded.

Tip

require is the most secure option.

3.9.19. SSLCiphers

This optional parameter specifies which subset of cipher suites are permissible for this connection, using the standard OpenSSL string format. The default value is DEFAULT:!EXPORT:!LOW.

Here is an example of using SSLCiphers:

# Exclude cipher suites using RC4 too
SSLCiphers DEFAULT:!EXPORT:!LOW:!RC4

3.9.20. SSLCAPath

SSLCAPath parameter specifies the name of a directory containing CA root certificates that may be required to validate TLS client certificates. Radiator looks for root certificates first in SSLCAFile, then in SSLCAPath, so there usually is no need to set both. When Certificate Revocation List (CRL) checks are enabled, this directory is also used by TLS library to look for CRL files.

Special characters are supported.The certificates and CRLs must be in PEM format, one per file. The file name has a special format. Setting up this directory is described in Setting up this directory is described in Section 3.11.3. TLS_CAPath.

Here is an example of using SSLCAPath:

SSLCAPath %D/cadirectory

3.9.21. SSLCAFile

Use this option to locate the file containing the certificates of the trusted certificate authorities. Thus, you can verify that the server certificate has been signed by a reputable certificate authority. Special characters are permitted.

Here is an example of using SSLCAFile:

SSLCAFile %D/certificates/demoCA/cacert.pem

3.9.22. SSLCAClientCert

This optional parameter specifies the location of the SSL client certificate that this LDAP connection uses to verify itself with the server. If SSL client verification is not required, then this option does not need to be specified. Special characters are permitted.

Here is an example of using SSLCAClientCert:

SSLCAClientCert %D/certificates/cert-clt.pem

3.9.23. SSLCAClientKey

This optional parameter specifies the location of the SSL private key that this connection uses to communicate with the server. If SSL client verification is not required, then this option does not need to be specified. Special characters are permitted.

It is common for the SSL client private key to be in the same file as the client certificate. In that case, both SSLCAClientCert and SSLCAClientKey refer to the same file.

If SSLCAClientKey contains a private key in encrypted format, you need to specify the decryption password in SSLCAClientKeyPassword.

Here is an example of using SSLCAClientKey:

SSLCAClientKey %D/certificates/cert-clt.pem

3.9.24. SSLCAClientKeyPassword

This optional parameter specifies the passphrase to decrypt SSLCAClientKey. This parameter is only required when SSL client verification is required and the key file configured with SSLCAClientKey is encrypted. Special characters are permitted.

SSLCAClientKeyPassword whatever

3.9.25. SSLExpectedServerName

This optional parameter specifies the name to use when verifying LDAP server certificate. Useful, for example, when Host is configured with an IP address. Special characters are permitted. For an example, see Section 3.9.6. Host.

# Certificate does not have a fully qualified name
SSLExpectedServerName myserver

3.9.26. Version

This optional parameter sets the LDAP version number to use. Currently supported values are 2 and 3. The default value is 3.

Here is an example of using Version:

# Support LDAP protocol version 2 as
# required by very old servers
Version 2

3.9.27. Deref

By default, aliases are dereferenced to locate the base object for the search, but not when searching subordinates of the base object. Change this by specifying Deref with one of the following case-sensitive values:

never
Do not dereference aliases in searching or in locating the base object of the search.
search
Dereference aliases in subordinates of the base object in searching, but not in locating the base object of the search.
find
Dereference aliases in locating the base object of the search, but not when searching subordinates of the base object. This is the default.
always
Dereference aliases both in searching and in locating the base object of the search.

Note

Usually, there is no need to use this parameter.

3.9.28. UseSASL

This optional parameter tells Radiator to request SASL authentication of the connection to the LDAP server instead of the default simple authentication. AuthDN and AuthPassword are used as the SASL credentials. Only if AuthDN and AuthPassword are not defined, SASLUser and SASLPassword are used.

Using this parameter requires the Authen-SASL-2.09 module or later. It is part of CPAN. For more information, see Section 2.1.2. CPAN.

3.9.29. SASLUser

Note

This parameter is deprecated.

This is a string that defines the user name, which is used for SASL authentication during the connection to the LDAP server. However, if AuthDN is defined, it overrides SASLUser and is used instead. Only if AuthDN is not defined and SASLUser is defined, SASLUser is used for authentication. For more information, see Section 3.9.4. AuthDN.

3.9.30. SASLPassword

Note

This parameter is deprecated.

This is a string that defines the password, which is used for SASL authentication during the connection to the LDAP server. However, if AuthPassword is defined, it overrides SASLPassword and is used instead. Only if AuthPassword is not defined and SASLPassword is, SASLPassword is used for authentication. For more information, see Section 3.9.5. AuthPassword.

3.9.31. SASLMechanism

If UseSASL is enabled, this optional parameter specifies what SASL mechanisms are to be used to authenticate the connection to the LDAP server. SASLMechanism is a space-separated list of mechanism names supported by Authen::SASL, such as

ANONYMOUS
CRAM-MD5
DIGEST-MD5
EXTERNAL
LOGIN
PLAIN

The default value is DIGEST-MD5. If you change this, it is possible that you need also to change your SASL to LDAP user mapping. See your SASL system documentation for details on what mechanisms are supported.

Here is an example of using SASLMechanism:

SASLMechanism DIGEST-MD5,PLAIN

3.9.32. BindAddress

You can specify the local address for the client side of the LDAP connection with BindAddress, in the form hostname[:port]. Special formatting characters are permitted.

Use this parameter to set LocalAddr parameter of the underlying IO::Socket used as the LDAP client. This is usually useful only on multi-homed hosts, where you need to control the source address of the LDAP connection, perhaps for firewall rules. There is no default and the system chooses the address.

Tip

This parameter is separate from the global BindAddress, see Section 3.7.9. BindAddress.

3.9.33. MultiHomed

This optional flag enables the MultiHomed option in Net::LDAP and IO::Socket for this LDAP connection. If this is set then Net::LDAP tries all addresses for a multi-homed LDAP host until one is successful. The default value is true.