Base configuration

The configuration step should be little more than copying the parameters used by ldapsearch to the ldap module configuration file.

The ldap module configuration file describes the configuration parameters accepted by the module, and what they do.

The default server configuration should be tested via the following command:

radiusd -XC

If the configuration is correct, then the server will print the following message:

Configuration appears to be OK

If that message does not appear, then it is necessary to correct any and all errors before proceeding to the next step. It is a good idea to ensure that the current configuration works before making changes to it.

Editing mods-available/ldap

As with all FreeRADIUS configuration files, please change at little as possible in the default configuration. The defaults are usually close to being correct. All that is necessary is to make minor changes, and test them. FreeRADIUS should look for data.

If the ldapsearch tests above pass, then the LDAP module configuration can be copied directly from the command-line options to that tool using the translation table on that page.

At a minimum you will need to set the following configuration items in in mods-available/ldap using the values you discovered running the ldapsearch tests.

ldap {
	# example - identity = 'cn=readonly,dc=example,dc=com'
	identity = '<readonly_user_dn>'             (1)

	# example - password = 'readonly'
	password = '<readonly_user_password>'       (2)

	# example - server = ldap://localhost
	server = '<uri>'                            (3)

	# example - base_dn = 'dc=example,dc=com'
	base_dn = '<dn_that_parents_user_objects_and_group_objects>'  (4)

	user {
		# example - base_dn = "ou=people,${..base_dn}"
		base_dn = "<path_from_base_dn_to_user_obj_dn>,${..base_dn}"  (5)

		# example = "(&(uid=%{&Stripped-User-Name || &User-Name})(objectClass=posixAccount))"
		filter = "(&(<user_uid_attribute>=%{&Stripped-User-Name || &User-Name})(<user_filter>))"  (6)
	}
}

1	A read only user that can bind to the directory to perform searches. This user should not have permission to modify the directory unless you’re also using LDAP for accounting accounting.
2	The password for the read only user.
3	An LDAP URI pointing to the server. If the LDAP server is on the same host as the RADIUS server, consider using a Unix Socket (`ldapi://`) to reduce network overhead.
4	The object containing all other objects we’re interested in.
5	The object containing all the users we need to perform AAA functions for.
6	A filter to select the object matching the authenticating user.

We do not recommend immediately configuring TLS unless you are testing against a production server. The best approach is to test one piece in isolation, before proceeding on to the next piece.

Enabling mods-available/ldap

The ldap module is enabled by creating a soft link from the mods-enabled/ directory to the mods-available/ directory.

cd raddb/mods-enabled && ln -s ../mods-available/ldap

Calling the LDAP module

The LDAP module needs to be listed in different section depending on the function(s) it’s performing.

User authorization and group checks

For simple authentication types like PAP and CHAP the LDAP module should be listed in the recv Access-Request { … } (≥ v4.0.x) or authorize { … } (≤ v3.2.x) section of the virtual server listening on the network (usually found in sites-available/default).

For EAP authentication the LDAP module should be listed in sites-available/inner-tunnel instead.

The LDAP module’s authorize method will discover the authenticating user’s DN and (optionally) cache that user’s group memberships.

It will also (optionally) check whether a user is authorized to use a particular service.

server default {
	...
	recv Access-Request {
		ldap
		...
	}
	...
}

Group checks may be performed using the xlat %ldap.group().

server default {
	...
	recv Access-Request {
		ldap
		if (%ldap.group(cn=authorized_users,ou=groups,dc=example,dc=com) == true) {
			reject
		}
		...
	}
}

See LDAP authorization for more detailed information on configuring LDAP/Group authorization. Including how to perform authorization after authentication.

User authentication with LDAP binds

Before deciding which authentication to use, you should read LDAP authentication concepts as it will explain which authentication methods are appropriate for different deployments and authentication protocols.

LDAP binds for simple authentication types like PAP the LDAP module should be listed in the recv Access-Request { … } and authenticate ldap { … } (≥ v4.0.x) or authorize { … } and authenticate { … } (≤ v3.2.x) sections of the virtual server listening on the network (usually found in sites-available/default).

For EAP authentication the LDAP module should be listed in sites-available/inner-tunnel instead. Be aware that LDAP binds will only work for EAP methods which provide the user’s password in the clear.

server default {
	...
	recv Access-Request {
		ldap
		if (ok || updated) {
			&control.Auth-Type := ldap
		}
	}

	authenticate ldap {
		ldap
	}
	...
}

See LDAP authentication for more detailed information on configuring LDAP authentication.

Testing the Server

After configuring the module, the server should be tested again via the following command:

radiusd -XC

When the configuration is correct, then the server will print the following message:

Configuration appears to be OK

Note that this test checks only that the configuration files can be parsed. It does not check that the module works correctly when packets are received.

When the configuration is correct, FreeRADIUS can then be started in debugging mode:

radiusd -X

If the module has been configured correctly, the final (or almost final) message will be

Ready to process requests

This message should be in bold on the console. Depending on which other modules are enabled, there may be a small number messages after this one.

If the server starts, then the next step is then to perform run-time tests.

Errors

If the Ready to process requests message does not appear, then the debug output will contain error messages clearly describing what went wrong. These error message must be read in order to gain insight as to the source of the problem.

Otherwise, look for messages containing ERROR or WARNING, or the module name. While the server can produce a large volume of messages, most of those can be ignored when debugging a particular problem. Simply search for a few key strings based on the files you changed, and the solution to the problem should be clear.

We recommend running the radiusd -XC test was performed before making any module changes for other reasons. If previous configuration worked, and the only change was to a particular module, then the source of the error is simple. There is no need to go searching through other configuration files or third-party web sites. Instead, change and test the module configuration until the server works.